# Docs as Code 生命周期手册 本手册是团队的“文档型项目经理”。当一个需求从想法进入团队协作后， 必须用文档记录它的编号、讨论、需求、设计、决策、开发进度、测试结果和最终状态。 本手册的目标不是增加形式负担，而是在缺少专职产品、项目经理、设计和测试角色时， 用可版本化、可追溯、可被 Agent 阅读的文档补齐流程。 ## 适用场景 以下场景必须先阅读本手册，再决定下一步产出： - 新需求、新专题、新模块、新接口开始前 - 用户问“下一步该做什么” - 用户要求补需求、补设计、补 ADR、补测试记录 - 准备进入编码，但需求或设计文档不完整 - 准备验收、上线或归档 - Agent 不确定某个需求当前处于哪个阶段 ## 核心原则 1. 一个需求只有一个主线编号：`feature_id` 2. 每一篇正式文档都有唯一编号：`doc_id` 3. 同一需求的所有阶段文档放在同一个专题目录下 4. 文档状态必须显式记录，不能只靠文件名判断 5. 允许跳过低价值文档，但必须在专题索引中写明原因 6. 进入编码前，至少要有需求边界、设计边界和验收口径 7. 涉及架构取舍、模块边界、接口契约、安全合规时，必须留痕 ## 目录入口 新需求、项目、专题统一放入： ```text docs/initiatives// ``` `feature_id` 格式： ```text FEAT-YYYYMM-NNN-short-name ``` 示例： ```text docs/initiatives/FEAT-202606-001-unified-entry-client/ ``` 专题目录推荐结构： ```text README.md # 专题索引和当前状态 intake.md # 需求录入和初步判断 prd.md # 需求文档 outline-design.md # 概要设计 detailed-design.md # 详细设计 api.md # 接口说明或 OpenAPI 链接 dev-progress.md # 开发进度和阶段记录 test-plan.md # 测试计划和验收方案 test-result.md # 测试结果和遗留问题 meeting-notes/ # 会议纪要 assets/ # 专题私有图片和附件 ``` 不是每个需求都必须拥有所有文档。缺省规则是：**可以裁剪，但必须说明裁剪原因**。 ## 编号规则 `feature_id` 是需求主线编号： ```text FEAT-YYYYMM-NNN-short-name ``` `doc_id` 是单篇文档编号： ```text -YYYYMM-NNN ``` 常用类型： | type | 编号前缀 | 文档 | |---|---:|---| | `intake` | `INT` | 需求录入 | | `prd` | `PRD` | 需求文档 | | `outline-design` | `ODS` | 概要设计 | | `detailed-design` | `DDS` | 详细设计 | | `design` | `DES` | 通用技术设计 | | `api` | `API` | 接口说明 | | `adr` | `ADR` | 架构决策记录 | | `dev-progress` | `DEV` | 开发进度 | | `test-plan` | `TST` | 测试计划 | | `test-result` | `TRS` | 测试结果 | | `meeting` | `MTG` | 会议纪要 | | `standard` | `STD` | 工程规约 | | `runbook` | `RUN` | 运维手册 | | `research` | `RSH` | 调研材料 | | `prompt` | `PMT` | AI Prompt 或智能体配置 | ## 元数据 正式文档必须包含 Front Matter： ```yaml --- doc_id: PRD-202606-001 feature_id: FEAT-202606-001-unified-entry-client type: prd title: 统一入口客户端需求说明 status: draft owner: 张三 created_at: 2026-06-16 updated_at: 2026-06-16 reviewers: [] related_docs: - INT-202606-001 related_modules: - emoon-openplatform - emoon-admin tags: - 统一入口 - 终端客户端 --- ``` 状态取值： | status | 含义 | |---|---| | `draft` | 草稿 | | `reviewing` | 评审中 | | `approved` | 已确认 | | `implemented` | 已实现或已落地 | | `deprecated` | 已废弃 | | `superseded` | 已被其他文档替代 | 更完整的分类和元数据规则见： - [文档分类](governance/doc-taxonomy.md) - [元数据规范](governance/doc-metadata.md) - [生命周期流程](governance/doc-lifecycle.md) ## 生命周期阶段 ### 0. 需求录入 目标：把“想做什么”变成可追踪的需求主线。 必须产出： - `feature_id` - `docs/initiatives//README.md` - `intake.md` `intake.md` 至少回答： - 问题来源是什么 - 谁会使用 - 触发场景是什么 - 预期收益是什么 - 是否有明确截止时间 - 是否涉及外部系统、硬件、医院现场或第三方 阶段门禁： - 没有 `feature_id`，不得创建后续正式文档 - 没有 `intake.md`，不得直接进入详细设计或编码 Agent 下一步判断： - 如果只有口头想法，先创建 `feature_id` 和 `intake.md` - 如果已有历史文档，先为历史文档补 `doc_id` 和 `feature_id` ### 1. 需求澄清 目标：把需求边界说清楚，避免直接用代码表达模糊需求。 必须产出： - `prd.md` `prd.md` 至少回答： - 背景和目标 - 用户与场景 - 功能需求 - 非功能需求 - 非目标 - 验收标准 - 风险和依赖 阶段门禁： - 没有验收标准，不得进入编码 - 没有非目标，需求容易失控，必须警示 - 涉及接口或外部系统时，必须标记后续需要 `api.md` Agent 下一步判断： - 如果 `prd.md` 不存在，先引导补 PRD - 如果 PRD 没有验收标准，先补验收标准 - 如果 PRD 有争议，先产出会议纪要或待确认问题，不急于编码 ### 2. 概要设计 目标：说明“用什么整体方案解决”，先定边界，再定细节。 建议产出： - `outline-design.md` 必须覆盖： - 总体方案 - 模块边界 - 主调用链路 - 数据流 - 外部系统依赖 - 关键风险 阶段门禁： - 修改模块职责、跨模块依赖或公共能力时，必须补概要设计 - 涉及重大架构取舍时，必须创建 ADR Agent 下一步判断： - 如果需求影响多个模块，先补概要设计 - 如果只是小范围修复，可以在专题 `README.md` 说明跳过概要设计的原因 ### 3. 详细设计 目标：把概要方案细化到开发可执行的程度。 建议产出： - `detailed-design.md` 必须覆盖： - 数据表和字段 - 状态机 - 接口入参出参 - 领域对象和服务职责 - 异常、幂等、重试、降级 - 鉴权、权限、脱敏、日志 - 测试策略 阶段门禁： - 涉及数据模型变更时，必须补详细设计 - 涉及鉴权、脱敏、密钥、日志时，必须补安全说明 - 涉及对外接口时，必须补 `api.md` 或 OpenAPI Agent 下一步判断： - 如果设计缺少异常和安全章节，要先警示 - 如果实现方案会改变工程约束，先补 ADR 或工程规约说明 ### 4. 架构决策 目标：记录不可轻易逆转的技术选择。 触发 ADR 的条件： - 改变模块边界或依赖方向 - 引入新中间件、新协议、新外部系统 - 改变对外接口长期契约 - 在多个可行方案中选择其一 - 为性能、安全、可维护性做重要取舍 产出位置： ```text docs/adr/ADR-YYYYMM-NNN-short-title.md ``` 阶段门禁： - 命中 ADR 条件但没有 ADR 时，Agent 必须警示 - ADR 不替代设计文档，只记录决策、备选方案和后果 ### 5. 接口契约 目标：让前后端、外部系统和 Agent 都能按同一契约协作。 建议产出： - `api.md` - `docs/api/openapi/.openapi.yaml` 必须覆盖： - 接口路径和方法 - 鉴权方式 - 请求和响应 Schema - 错误码 - 幂等和重试约定 - 联调记录 阶段门禁： - 只改代码不改接口文档，属于流程缺口 - OpenAPI 和说明文档冲突时，以 OpenAPI 为准，并修正文档 ### 6. 开发进度 目标：记录实现过程中的范围变化、阶段结果和遗留问题。 建议产出： - `dev-progress.md` 必须记录： - 开发任务拆分 - 已完成内容 - 未完成内容 - 范围变更 - 阻塞项 - 关联 PR 或提交 阶段门禁： - 需求范围变化时，必须同步更新 PRD 或记录变更原因 - 设计和实现不一致时，必须更新设计文档或记录偏差 ### 7. 测试计划 目标：在验收前明确“怎样算通过”。 必须产出： - `test-plan.md` 必须覆盖： - 验收范围 - 测试环境 - 测试数据 - 用例列表 - 回归范围 - 不覆盖风险 阶段门禁： - 没有 `test-plan.md`，不得宣称需求完成 - 没有回归范围，不能进入上线判断 ### 8. 测试结果 目标：记录真实验证结果，而不是只说“已测”。 必须产出： - `test-result.md` 必须记录： - 执行时间 - 执行人或 Agent - 环境和版本 - 通过项 - 失败项 - 遗留问题 - 最终结论 阶段门禁： - 测试失败项未关闭时，专题状态不得标记为 `implemented` - 自动化测试无法运行时，必须记录原因和人工替代验证 ### 9. 上线和归档 目标：让需求最终状态可追踪。 必须更新： - 专题 `README.md` - `dev-progress.md` - `test-result.md` - 相关 ADR、接口、工程规约 归档要求： - 专题 `README.md` 写明最终状态 - 关联文档状态更新为 `implemented`、`deprecated` 或 `superseded` - 遗留问题进入 `.scratch//` 或后续 `feature_id` ## Agent 工作方式 当用户要求推进某个需求时，Agent 必须按以下顺序检查： 1. 是否提供或能识别 `feature_id` 2. 是否存在 `docs/initiatives//README.md` 3. 当前已有哪几类文档 4. 每篇文档的 `status` 是否允许进入下一阶段 5. 是否命中 ADR、接口、安全、测试等强制产物条件 6. 下一步应该产出哪一篇文档 7. 如果用户要求跳过，是否需要警示并记录跳过原因 Agent 回复建议格式： ```text 当前阶段：需求澄清 已有文档：README.md、intake.md 缺口：prd.md 缺失，无法进入概要设计 下一步：产出 prd.md 建议动作：先补背景、目标、非目标、验收标准 警示：如果直接写设计或代码，需求边界不可追踪 ``` ## 跳过规则 允许跳过某些阶段，但必须满足： - 在专题 `README.md` 的“流程裁剪”部分写明原因 - 说明风险 - 说明由哪个文档替代 - 说明是否需要后补 示例： ```markdown ## 流程裁剪 | 阶段 | 是否跳过 | 原因 | 风险 | 替代记录 | |---|---|---|---|---| | 概要设计 | 是 | 单模块文案修复 | 低 | PRD 验收标准 | ``` ## 模板 - [专题索引模板](templates/initiative-readme-template.md) - [需求录入模板](templates/intake-template.md) - [需求文档模板](templates/prd-template.md) - [概要设计模板](templates/outline-design-template.md) - [详细设计模板](templates/detailed-design-template.md) - [接口说明模板](templates/api-template.md) - [开发进度模板](templates/dev-progress-template.md) - [测试验收模板](templates/test-plan-template.md) - [测试结果模板](templates/test-result-template.md) - [会议纪要模板](templates/meeting-note-template.md) ## 历史文档 现有历史文档暂不强制移动。新文档必须按本规范创建；历史文档在发生实质修改、 被新需求引用、或进入归档整理时，逐步补充 Front Matter 并迁移到合适位置。