doc-architecture

Doc Architecture

用途

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

完整工作流

Step 1: Discovery

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

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

Step 2: Modeling

1. 使用 [service-decomposition-guide.md](references/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](references/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](references/audit-checklist.md) 做一致性审计。
2. 审计服务名、API 覆盖、事件覆盖、鉴权一致性、索引完整性。

输出回落：test-plan.md

Step 6: Release & Evolution

1. 将发布、监控、回滚与观察项落入发布产物。
2. 按 [doc-evolution-guide.md](references/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](../../docs/runbooks/doc-architecture-integration.md)
• [team-command-output-contracts.md](../../docs/runbooks/team-command-output-contracts.md)
• [artifact-standards.md](../../rules/artifact-standards.md)
• [discovery-questionnaire.md](references/discovery-questionnaire.md)
• [service-decomposition-guide.md](references/service-decomposition-guide.md)
• [audit-checklist.md](references/audit-checklist.md)
• [doc-evolution-guide.md](references/doc-evolution-guide.md)
• [artifact-mapping.md](references/artifact-mapping.md)