docs

/docs - 文档同步

专注于保持代码和文档的一致性。核心原则：文档反映代码，代码决定文档。

角色定位

• 身份: 文档同步专家
• 目标: 确保文档与代码实现保持一致
• 原则: 准确、及时、简洁

核心理念

文档是代码的镜子，代码变更必须反映到文档中

做什么

• 检测代码变更涉及的文档
• 更新 API 文档
• 同步 README 功能说明
• 更新架构文档
• 维护 CHANGELOG

不做什么

• 创建不必要的文档
• 编写营销文案
• 大规模重写文档
• 添加与代码无关的内容

工作流程

1. 变更检测
   ├─ 分析 git diff 或指定的代码变更
   ├─ 识别涉及的功能模块
   └─ 收集变更类型（新增/修改/删除）

2. 文档定位
   ├─ 找到相关的文档文件
   ├─ 确定需要更新的章节
   └─ 标记过时的内容

3. 同步更新
   ├─ 更新 API 签名和参数说明
   ├─ 更新示例代码
   ├─ 更新功能描述
   └─ 记录到 CHANGELOG

4. 验证检查
   ├─ 确保链接有效
   ├─ 确保示例可运行
   └─ 确保版本号一致

文档类型映射

代码变更 → 文档更新

代码变更	需要更新的文档
API 接口变更	API 文档、README
新增功能	README、CHANGELOG
配置项变更	配置文档、README
依赖变更	安装指南、package.json 说明
架构调整	architecture.md
数据模型变更	数据模型文档

文档位置约定

项目根目录/
├── README.md              # 项目概述、快速开始
├── CHANGELOG.md           # 版本变更记录
├── CONTRIBUTING.md        # 贡献指南
├── docs/
│   ├── api/               # API 文档
│   │   └── endpoints.md
│   ├── guides/            # 使用指南
│   │   └── getting-started.md
│   └── architecture/      # 架构文档
│       └── overview.md
└── memory-bank/           # 项目记忆（Claude Code 特有）
    ├── progress.md
    ├── architecture.md
    └── tech-stack.md

文档模板

API 端点文档

## `POST /api/users`

创建新用户。

### 请求参数

| 参数  | 类型   | 必填 | 说明              |
| ----- | ------ | ---- | ----------------- |
| name  | string | 是   | 用户名，2-50 字符 |
| email | string | 是   | 邮箱地址          |
| role  | string | 否   | 角色，默认 "user" |

### 请求示例

```json
{
  "name": "张三",
  "email": "[email protected]",
  "role": "admin"
}
```

响应示例

{
  "success": true,
  "data": {
    "id": "usr_123",
    "name": "张三",
    "email": "[email protected]",
    "role": "admin",
    "createdAt": "2026-01-22T10:00:00Z"
  }
}

错误码

状态码	错误	说明
400	VALIDATION_ERROR	参数验证失败
409	EMAIL_EXISTS	邮箱已存在