未来的开发考验的是写文档的能力

一、引言：当代码成为副产物

AI Coding 正在重塑软件开发的底层逻辑。

过去十年，我们见证了从手写到 IDE 辅助，再到 Copilot 补全的演进。而 2024-2025 年的标志性转变是：AI Agent 开始独立完成端到端的开发任务。从需求理解、架构设计、代码实现到测试部署，人类开发者的角色正在从"编写者"转向"指挥者"。

在这个范式转移中，一个反直觉的事实浮现出来：代码本身正在贬值，而描述代码的文档正在升值。当 AI 可以秒级生成数百行代码时，约束它的不再是语法知识，而是人类对问题的精确描述能力。

本文将深入探讨这一趋势，并通过 Claude Code、AI Agent、Cursor 等主流工具的设计哲学，以及规范驱动开发（SDD）的方法论，论证一个核心观点：未来的软件开发，本质上是高质量的文档工程。

---

二、AI Coding 的演进：从补全到自主

2.1 三代 AI 编程工具的跃迁

阶段	代表工具	交互模式	人类职责
第一代	GitHub Copilot	代码补全	思考 + 编写 + 审查
第二代	Cursor、Windsurf	对话式生成	需求描述 + 审查 + 调试
第三代	Claude Code、Devin、OpenAI Codex CLI	Agent 自主执行	文档定义 + 目标设定 + 验收

第三代的本质特征是上下文自主（Contextual Autonomy）。AI 不再等待人类逐行指导，而是基于一组预定义的约束和目标独立工作。这使得"约束的定义"比"代码的编写"更为关键。

2.2 上下文窗口的军备竞赛

2024 年，Claude 3.5 Sonnet 的 200K 上下文窗口和 Gemini 1.5 Pro 的 2M 上下文窗口，彻底改变了游戏规则。AI 现在可以：

• 一次性理解整个代码库的结构
• 记住跨文件的依赖关系
• 遵循复杂的多步骤指令

但这也暴露了一个瓶颈：AI 的理解能力取决于输入信息的质量。给它混乱的提示，它输出混乱的代码；给它精确的规范，它输出优雅的实现。

结论很明确：上下文窗口解决了"能读多少"的问题，但文档质量决定了"理解多深"。

---

三、案例分析：文档即代码的基础设施

3.1 Claude Code：skills.md 的技能声明

Anthropic 的 Claude Code 是第三代 AI 编程工具的代表。其核心设计之一是 skills.md 机制——一种用于定义 AI 能力的结构化文档。

skills.md 的典型结构：

# Skill: Database Migration

## Description
Handle PostgreSQL schema migrations using Alembic with zero-downtime guarantees.

## Requirements
- Always backup before migration
- Use transactional DDL where possible
- Generate rollback scripts automatically

## File Patterns
- `migrations/versions/*.py`
- `alembic.ini`

## Commands
- `alembic revision --autogenerate -m "{message}"`
- `alembic upgrade head`
- `alembic downgrade -1`

## Examples

### Good: Adding a nullable column
```python
def upgrade():
    op.add_column('users', sa.Column('bio', sa.Text(), nullable=True))
    # No backfill needed for nullable columns

Bad: Adding non-nullable column without default

def upgrade():
    # DANGER: This locks the table!
    op.add_column('users', sa.Column('email', sa.String(), nullable=False))

#### 深层分析：

`skills.md` 不是简单的配置，而是**可执行知识的文档化**。它包含：

1. **边界定义**（Description）：AI 知道何时调用该技能
2. **约束条件**（Requirements）：硬性规则，不可违背
3. **上下文关联**（File Patterns）：触发条件与环境感知
4. **操作手册**（Commands）：可执行的原子操作
5. **正反示例**（Examples）：少样本学习（Few-shot Learning）的素材

**关键洞察**：在 Claude Code 的架构中，`skills.md` 就是代码的生成器。人类编写文档，AI 生成实现。文档的完备性直接决定了 AI 输出的可靠性。

### 3.2 AI Agent：agent.md 的角色定义

在 Multi-Agent 系统（如 AutoGen、CrewAI、OpenAI Swarm）中，**`agent.md`** 用于定义单个 Agent 的角色、能力和协作边界。

#### agent.md 的范式：

```markdown
# Agent: Security Auditor

## Role
You are a security-focused code reviewer specializing in OWASP Top 10 vulnerabilities.

## Goals
- Identify injection vulnerabilities in user inputs
- Flag insecure authentication patterns
- Verify proper secrets management

## Constraints
- NEVER suggest `eval()` or `exec()` as solutions
- Reject any hardcoded credentials with ERROR severity
- All suggestions must include CVE references when applicable

## Tools
- `semgrep_scan`: Run static analysis
- `dependency_check`: Scan for known vulnerabilities
- `code_review`: Line-by-line security review

## Communication Style
- Direct and technical
- Cite specific line numbers
- Provide exploit scenarios for critical issues

## Handoff Conditions
- Escalate to `Senior Architect` if architectural changes needed
- Notify `DevOps Agent` if CI/CD modifications required

架构意义：

agent.md 实现了文档驱动的 Agent 编排。在复杂系统中，多个 Agent 协作完成开发任务，每个 Agent 的行为完全由其对应的 .md 文件定义。这带来了：

• 可组合性：通过组合不同的 agent.md 构建团队
• 可测试性：Agent 的行为边界清晰，便于验证
• 可演进性：修改文档即可改变 Agent 行为，无需重训练

开发范式转变：传统开发中，我们编写代码实现功能；在 Agent 系统中，我们编写文档定义角色，让 Agent 自行决定如何编码。

3.3 Cursor：rules.md 的规范嵌入

Cursor 作为第二代向第三代过渡的工具，通过 .cursor/rules.md 实现了项目级规范的注入。

rules.md 的应用场景：

# Project Rules: FinTech API

## Architecture Constraints
- All database access must go through Repository pattern
- API responses follow JSend format
- No raw SQL in handlers

## Code Style
- Use functional error handling (Result<T, E> pattern)
- Prefer explicit types over inference in public APIs
- All async functions must have timeout decorators

## Testing Requirements
- 100% coverage for payment-related code
- Property-based testing for financial calculations
- Integration tests use testcontainers

## Prohibited Patterns
- ❌ Direct `float` for monetary values (use `Decimal`)
- ❌ `requests` library (use `httpx` with async)
- ❌ `time.sleep()` in production code

## Mandatory Checks
- [ ] Pre-commit hooks pass
- [ ] SonarQube quality gate green
- [ ] Performance regression < 5%

技术实现机制：

Cursor 将 rules.md 注入到每次 AI 交互的系统提示（System Prompt）中，形成持续约束（Persistent Constraints）。这与单次提示（One-shot Prompt）有本质区别：

特性	单次提示	rules.md
持久性	当前会话	整个项目生命周期
一致性	依赖记忆	强制规范
可维护性	分散在聊天记录	版本控制
团队协作	个人习惯	团队共识

核心启示：rules.md 将团队的隐性知识显性化，成为 AI 的"宪法"。开发者不再需要对 AI 反复叮嘱，而是将约定写入文档，让 AI 持续遵循。

3.4 规范驱动开发（SDD）：文档即契约

规范驱动开发（Specification-Driven Development, SDD）是 TDD 和 DDD 在 AI 时代的进化形态。其核心主张是：在编写任何代码之前，先编写机器可读的规范文档。

SDD 的文档体系：

docs/
├── specifications/
│   ├── api/
│   │   ├── user-management.openapi.yml    # OpenAPI 规范
│   │   └── payment.webhook.schema.json    # JSON Schema
│   ├── domain/
│   │   ├── order.aggregate.md             # 领域模型文档
│   │   └── inventory.rules.drl            # 业务规则
│   └── infrastructure/
│       ├── deployment.terraform.md        # IaC 规范
│       └── monitoring.slo.yml             # SLO 定义
└── context/
    ├── architecture-decision-records/     # ADR
    ├── runbooks/                          # 运维手册
    └── ai-prompts/                        # 优化后的提示模板

SDD 的工作流：

1. 规范编写：人类用结构化文档定义行为（OpenAPI, JSON Schema, Markdown）
2. 规范验证：工具自动检查一致性（spectral, jsonschema）
3. AI 生成：AI 基于规范生成代码骨架和测试
4. 人类审查：验证 AI 输出是否符合规范意图
5. 规范演进：文档变更驱动代码重构

与传统开发的对比：

维度	传统开发	SDD
真相源（Source of Truth）	代码	规范文档
变更发起	修改代码	修改规范
AI 角色	辅助编码	基于规范生成
可维护性	依赖注释	自描述规范
跨团队协作	API 文档滞后	契约先行

范式总结：SDD 将文档提升到与代码同等甚至更高的地位。在 AI 的加持下，规范文档可以直接生成可执行代码，实现**文档即代码（Docs as Code）**的终极形态。

---

四、深层剖析：为什么开发等于写文档

4.1 认知卸载（Cognitive Offloading）的转移

软件开发本质上是复杂性管理。人类大脑的工作记忆有限（约 7±2 个信息块），传统开发中，我们用文档来卸载记忆负担：

• 需求文档：卸载业务逻辑记忆
• 设计文档：卸载架构决策记忆
• API 文档：卸载接口契约记忆

在 AI Coding 时代，这种卸载发生了转移：AI 成为外部认知主体，文档成为人类与 AI 之间的接口。

人类意图 → 文档（结构化知识） → AI 处理 → 代码实现

文档质量决定了信息在传递过程中的保真度。模糊的需求产生模糊的代码，精确的规范产生精确的实现。

4.2 提示工程（Prompt Engineering）的文档化

早期的 Prompt Engineering 强调"对话技巧"——如何与 AI 聊天以获得好结果。但随着工具成熟，最佳实践正在文档化：

• Claude 的 skills.md：将提示模板固化为可复用技能
• Cursor 的 rules.md：将项目约束沉淀为持续上下文
• OpenAI 的 GPTs：将角色定义封装为可分发配置

这揭示了一个趋势：有效的提示工程正在从"艺术"转变为"工程"，其核心产出就是结构化的文档。

4.3 代码生成的可控性

AI 生成代码的最大风险是幻觉（Hallucination）和不一致性。文档提供了控制机制：

1. 约束传播：通过文档将架构约束传递给 AI
2. 示例引导：Few-shot 示例规范输出模式
3. 验证闭环：文档中的规范可作为自动验证的基准

核心公式：

可控性 = f(文档完备性, 规范明确性, 示例质量)

当文档足够完备时，AI 生成的代码可以达到生产级质量；当文档缺失时，AI 只能进行猜测性实现。

---

五、实践指南：如何写好 AI 时代的开发文档

基于上述分析，以下是针对 AI Coding 场景的文档编写指南，分为五个维度：

5.1 精确性原则（Precision）

核心要求：消除歧义，使用精确的技术词汇。

反例：

# Bad
Handle user login properly with security.

正例：

# Good
Implement OAuth 2.0 Authorization Code flow with PKCE:
- Token endpoint: POST /oauth/token
- Access token TTL: 3600s
- Refresh token rotation: mandatory
- Storage: httpOnly, secure, sameSite=strict cookies

AI 影响：精确的描述减少 AI 的猜测空间，降低幻觉风险。

5.2 结构化原则（Structure）

核心要求：使用标准格式，便于 AI 解析。

推荐格式：

# [Component Name]

## Purpose
One-sentence description of what this does.

## Interface
| Input | Type | Constraints |
|-------|------|-------------|
| userId | UUID | Must exist in users table |

## Logic
1. Validate input against schema
2. Check permission using RBAC
3. Execute core operation
4. Emit domain event
5. Return standardized response

## Error Handling
| Error Code | HTTP Status | Retryable |
|------------|-------------|-----------|
| USER_NOT_FOUND | 404 | No |

## Dependencies
- `UserRepository` for data access
- `EventBus` for async notifications

AI 影响：结构化文档可被 AI 直接转换为代码骨架、测试用例和 API 文档。

5.3 示例驱动原则（Examples）

核心要求：提供正反示例，进行 Few-shot 教学。

模板：

## Examples

### ✅ Correct Implementation
```python
# Good: Uses connection pooling
async def get_user(db: AsyncSession, user_id: UUID) -> User:
    result = await db.execute(select(User).where(User.id == user_id))
    return result.scalar_one_or_none()

❌ Incorrect Implementation

# Bad: Creates new connection per call
def get_user(user_id: str):
    conn = psycopg2.connect(DSN)  # Anti-pattern: No pooling
    cursor = conn.cursor()
    cursor.execute(f"SELECT * FROM users WHERE id = {user_id}")  # SQL Injection risk
    return cursor.fetchone()

**AI 影响**：示例是最高效的教学方式，AI 通过模式匹配生成符合预期的代码。

### 5.4 约束显性化原则（Constraints）

**核心要求**：将隐性的"常识"显式写入文档。

**检查清单**：

- [ ] **性能约束**：响应时间、吞吐量、资源限制
- [ ] **安全约束**：认证方式、授权级别、数据加密要求
- [ ] **兼容性约束**：API 版本、数据库迁移策略、浏览器支持
- [ ] **运维约束**：部署方式、监控指标、回滚策略

**示例**：

```markdown
## Constraints

### Performance
- P99 latency < 200ms for GET endpoints
- Database query timeout: 5s (hard fail)
- Max payload size: 1MB

### Security
- All endpoints require JWT validation except /health
- Rate limiting: 100 req/min per IP, 1000 req/min per user
- PII fields must be encrypted at rest (AES-256-GCM)

AI 影响：显性约束防止 AI 生成不符合非功能性需求的代码。

5.5 可验证原则（Verifiability）

核心要求：文档中的声明必须可自动验证。

实现方式：

1. 架构约束测试：

# test_architecture.py
def test_no_direct_db_access_in_handlers():
    violations = scan_for_violation("handlers/", "import psycopg2")
    assert len(violations) == 0, f"Direct DB access found: {violations}"

2. API 契约测试：

# tests/contract/user-api.yml
tests:
  - name: create_user_returns_201
    request:
      method: POST
      path: /users
      body: { "email": "test@example.com" }
    response:
      status: 201
      schema: { "$ref": "#/components/schemas/User" }

3. 文档-代码同步检查：

# CI pipeline
spectral lint docs/api/*.yml  # Validate OpenAPI
markdown-link-check docs/**/*.md  # Check dead links
adr-tools check  # Verify ADR completeness

AI 影响：可验证的文档形成闭环，确保 AI 生成的代码持续符合规范。

---

六、组织架构：文档工程化的实施路径

6.1 团队角色演变

传统角色	新兴角色	职责转变
后端开发工程师	规范工程师	编写 API 规范、领域模型文档
架构师	上下文架构师	设计 AI 可理解的系统上下文
技术写作者	提示工程师	优化 AI 交互文档和模板
QA 工程师	验证工程师	构建文档到代码的验证管道

6.2 文档即代码的工具链

编写阶段          验证阶段           生成阶段           部署阶段
┌─────────┐      ┌─────────┐       ┌─────────┐       ┌─────────┐
│ Markdown│ ───→ │ spectral│ ────→ │ AI Agent│ ────→ │ CI/CD   │
│ OpenAPI │      │ jsonschema      │ Code Gen│       │ Validate│
│ JSON Sch│      │ markdownlint    │ Test Gen│       │ Deploy  │
└─────────┘      └─────────┘       └─────────┘       └─────────┘
     ↑                                                 │
     └─────────────────────────────────────────────────┘
                    反馈循环

6.3 成熟度模型

级别	特征	文档类型	AI 参与度
L1 初始	无结构化文档	零散注释	辅助补全
L2 管理	项目级规范	rules.md, skills.md	对话生成
L3 定义	领域模型文档化	ADR, 领域词汇表	基于规范生成
L4 量化	文档-代码双向验证	可执行规范	自主实现 + 人类审查
L5 优化	AI 驱动的文档演进	自优化提示模板	端到端自主开发

---

七、结论：从代码优先到文档优先

AI Coding 不是让开发者失业，而是将开发者的核心价值从代码编写转移到问题定义。在这个新范式中：

1. 代码是廉价的：AI 可以生成无限量的代码，但只有符合需求的代码才有价值
2. 需求是昂贵的：准确理解并描述需求是稀缺能力，决定了 AI 输出的上限
3. 文档是接口：人类与 AI 的协作通过文档完成，文档质量决定协作效率

回顾本文的案例：

• Claude Code 的 skills.md 证明：技能的可复用性取决于文档的完备性
• AI Agent 的 agent.md 证明：Agent 的能力边界由文档定义
• Cursor 的 rules.md 证明：项目规范通过文档持续约束 AI 行为
• SDD 方法论 证明：文档可以成为代码生成的唯一真相源

最终建议：

投资你的文档能力，就像十年前投资你的算法能力一样。未来的顶级开发者不是那些打字最快的人，而是那些能够用最精确的语言描述问题、定义约束、设计验证的人。

在 AI 时代，写文档不是开发的附属品，而是开发本身。

---

本文基于 2024-2025 年 AI Coding 工具的最新实践，随着技术快速演进，部分细节可能变化，但"文档驱动"的核心逻辑将持续适用。