产品开发全过程文件管理 v3.1

快速决策树

触发性问题：文档初始化 检查文档完整性 该写什么文档 文档放哪里

项目复杂度？
├── 简单（1-3人，单仓库，无微服务）→ 最小集：README + CHANGELOG + 01 + 04
├── 中等（3-8人，前后端分离，≤2子项目）→ 标准集：最小集 + 02 + 05 + 06
└── 复杂（8+人，微服务/多仓库，≥3子项目）→ 完整集：标准集 + 03 + 07 + 子项目文档

有终端用户（有 UI/面向非开发者）？
├── 是 → 建议建 08-user-guide（中等/复杂必建，简单可选）
└── 否（纯API/后台/库）→ 不建 08-user-guide

项目当前阶段？
├── 立项/初始化 → 只建 README + CHANGELOG + DOCUMENTATION_INDEX
├── 需求确定 → +01-requirements
├── 架构确定 → +02-architecture（+03-database 如用数据库）
├── API 设计完成 → +04-api
├── 首个功能完成 → +05-feature-guide
├── 首次部署 → +06-deployment
└── 首次发布 → +07-release-notes

原则：文档跟随代码进度，不提前建空文档。

一、项目复杂度分级（决定最小文档集）

子项目判断（满足任一定为子项目，需独立文档）：

• 独立部署单元 / 独立代码库 → 完整子项目文档集
• 独立团队负责 → 至少 01 + 02
• 纯前端模块 → 至少 02 + 04 + 05

二、分阶段渐进式文档建设

文档随项目推进逐步建立，禁止在项目初期创建空文档占位。

三、目录结构与命名规范

{project-root}/
├── README.md
├── CHANGELOG.md
├── docs/
│   ├── DOCUMENTATION_INDEX.md
│   ├── api/
│   │   └── openapi.yaml          ← 推荐，与 04-api.md 同步
│   ├── core/                     ← 核心文档（文件名固定，无版本号）
│   │   ├── 01-requirements.md
│   │   ├── 02-architecture.md
│   │   ├── 03-database.md      ← 用数据库时必建
│   │   ├── 04-api.md
│   │   ├── 05-feature-guide.md
│   │   ├── 06-deployment.md
│   │   ├── 07-release-notes.md
│   │   └── 08-user-guide.md   ← 有终端用户时建（见§产品使用说明）
│   └── {subproject}/            ← 子项目文档
│       ├── {sp}-01-requirements.md
│       ├── {sp}-02-architecture.md
│       └── ...
└── .workbuddy/memory/           ← AI Agent 工作记忆（人类不读）

命名规则（强制执行）：

• 所有文件名：kebab-case，全小写 + 连字符
• 核心文档：{序号}-{英文名}.md（无版本号）
• 子项目文档：{子项目ID}-{序号}-{英文名}.md
• 版本号在文件内容头部维护，不出现在文件名中

四、核心文档清单与内容边界

详细规范见 references/doc-spec.md，模板见 references/templates.md。

✅=必须 △=按需（有终端用户时建） - =不需要

五、触发时机（创建与更新）

创建触发

更新触发（强制同步）

> 规则：代码变更与文档更新在同一 commit / PR 中完成。

六、子项目文档规范

判断是否需要子项目文档

子项目文档命名

{子项目ID}-{两位序号}-{英文名}.md
例：admin-01-requirements.md  ai-services-04-api.md

子项目内部序号映射：01=requirements, 02=architecture, 03=data-model, 04=api, 05=feature-guide, 06=ui-design, 07=deployment

微服务子项目专属章节（02-architecture 必须包含）

服务发现与注册 / 服务间通信 / 数据一致性策略 / 容错与降级 / 服务依赖拓扑

微服务架构文档补充章节模板（写入 {sp}-02-architecture.md）：

## 7. 服务发现与注册

| 配置项 | 值 | 说明 |
|--------|------|------|
| 注册中心 | {Nacos/Consul/etcd} | {版本} |
| 服务名 | {service-name} | 注册中心的名称 |
| 健康检查 | {HTTP/TCP} | {路径/端口} |

## 8. 服务间通信

### 同步调用
| 调用目标 | 协议 | 用途 | 超时 |
|---------|------|------|------|
| {service-A} | gRPC/HTTP | {用途} | {N}ms |

### 异步通信（消息队列）
| Topic/Queue | 生产/消费 | 用途 | 消费者组 |
|-------------|---------|------|---------|
| {topic} | 生产者 | {事件} | {group} |

## 9. 数据一致性

### 策略选择
- 核心链路：{Saga / TCC / 本地事务}
- 非核心链路：{最终一致性 / 异步补偿}

| 跨服务场景 | 一致性策略 | 补偿方式 |
|-----------|----------|---------|
| {场景} | {策略} | {补偿方式} |

## 10. 容错与降级

| 机制 | 配置 | 说明 |
|------|------|------|
| 熔断 | 阈值 {N}，窗口 {N}s | {触发条件} |
| 限流 | {N} QPS / 每实例 | {策略} |
| 降级 | 降级为 {降级方案} | {触发条件} |
| 重试 | 最大 {N} 次，间隔 {N}ms | 仅对 {场景} 启用 |

## 11. 服务依赖拓扑

（依赖关系图，Mermaid 或 ASCII）

子项目生命周期

子项目经历五个阶段，各阶段文档操作不同：

创建 ──→ 开发 ──→ 冻结 ──→ 归档 ──→ 废弃

状态流转规则：

• 草稿 → 开发中：需求评审通过
• 开发中 → 已冻结：文档完整、功能验收通过
• 已冻结 → 归档：不再需要活跃维护
• 归档 → 废弃：确认彻底下线
• 禁止：开发中直接跳到归档/废弃

详细检查清单见 references/doc-spec.md 子项目生命周期章节。

七、AI Agent 协作规则

读取优先级（上下文加载）

1. README.md → 2. 02-architecture → 3. 04-api → 4. 03-database → 5. 子项目文档按需

写入规则

• 修改代码后同一 turn 更新对应文档（先 Read 再 Edit，禁止直接覆写）
• 文档版本号、日期字段必须同步更新
• 工作记忆（.workbuddy/memory/）不替代正式文档
• 子项目文档使用作用域编号（{sp}-{NN}-{type}.md）

检查文档完整性（接手新项目时）

1. 列出 docs/ 目录结构
2. 对照当前复杂度级别的最小集，报告缺失文档
3. 询问用户是否立即创建（不自动创建）

八、执行规则

必须遵守：

1. CHANGELOG.md 的 [Unreleased] 段落在开发过程中持续积累，发布前归档
2. 版本号所有核心文档同步（禁止只改 README）
3. 旧版文档移入 docs/_archived/，不删除
4. 跨文档不复制内容，使用相对路径引用

禁止行为：

• ❌ 在项目初期创建空文档占位
• ❌ 简单项目强制要求完整 7 份文档
• ❌ 文档版本号落后于代码版本号
• ❌ 跨文档复制内容而非引用

九、参考资料

十、何时不触发本 Skill

以下场景不触发（节省 AI 上下文）：

• 纯代码问题（无文档管理意图）
• 项目为一次性脚本 / 个人工具（无需协作文档）
• 用户明确说"不需要文档"
• 只问单个文档的内容（直接读文件即可，不需加载本 skill）