doc-architecture

Doc Architecture

用途

• 将文档能力拆入现有 team-skills 主链，不新增并行文档体系。
• 统一 Discovery、Service Decomposition、NFR、Audit 的输入输出结构。
• 保证文档可追溯落盘到 docs/artifacts/、docs/adr/ 与 docs/memory/。

完整工作流

Step 1: Discovery

1. 使用 discovery-questionnaire.md 收集项目背景、技术栈、架构风格与约束。
2. 若是既有项目（brownfield），先补做现状扫描：盘点现有模块、入口、外部依赖、关键数据流和历史包袱；必要时借助 /update-codemaps 生成 token-lean 结构快照。
3. 形成 Project Profile Card。
4. 按 tech-stack-profiles.md 锁定文档术语风格。

输出回落：prd.md、delivery-plan.md

Step 2: Modeling

1. 使用 service-decomposition-guide.md 识别领域与服务边界。
2. 产出 Service Catalog 与 Communication Matrix。
3. 收集 NFR（可用性、性能、安全、可观测性）。

输出回落：arch-design.md、api-contract.md

Step 3: Generation Mapping

1. 按 artifact-mapping.md 将文档输出映射到 artifacts。
2. 参考 references/templates/ 选择章节结构。
3. 若属于 brownfield 任务，把现状扫描结果回落为 brownfield context snapshot，写入 delivery-plan.md / arch-design.md，不要新建平行事实源。
4. 对缺失信息使用 <!-- TODO: ... --> 标记，不虚构业务事实。

输出回落：delivery-plan.md、arch-design.md、api-contract.md

Step 4: Execute Backfill

1. 在执行阶段记录实现偏差、接口漂移、事件变更。
2. 关键取舍进入 ADR，轻量决策进入 decisions。

输出回落：execute-log.md、docs/adr/*.md、docs/memory/decisions.md

Step 5: Consistency Audit

1. 使用 audit-checklist.md 做一致性审计。
2. 审计服务名、API 覆盖、事件覆盖、鉴权一致性、索引完整性。

输出回落：test-plan.md

Step 6: Release & Evolution

1. 将发布、监控、回滚与观察项落入发布产物。
2. 按 doc-evolution-guide.md 做增量演进。

输出回落：release-plan.md、docs/memory/sessions/*.md

最小产物清单

1. docs/artifacts/{date}-{slug}/prd.md
2. docs/artifacts/{date}-{slug}/delivery-plan.md
3. docs/artifacts/{date}-{slug}/arch-design.md
4. docs/artifacts/{date}-{slug}/api-contract.md（按需）
5. docs/artifacts/{date}-{slug}/execute-log.md
6. docs/artifacts/{date}-{slug}/test-plan.md
7. docs/artifacts/{date}-{slug}/release-plan.md
8. docs/adr/ADR-{NNN}-{slug}.md（按需）
9. docs/memory/project-context.md、docs/memory/decisions.md、docs/memory/lessons-learned.md、docs/memory/sessions/*.md

何时优先调用

• tech-lead 需要把架构文档能力并入主链而不新增命令时。
• architect 需要在 arch-design.md 与 api-contract.md 形成可执行契约时。
• qa-engineer 需要把文档一致性纳入放行证据时。

参考资料

• doc-architecture-integration.md
• team-command-output-contracts.md
• artifact-standards.md
• discovery-questionnaire.md
• service-decomposition-guide.md
• audit-checklist.md
• doc-evolution-guide.md
• artifact-mapping.md