ddd-architecture-doc

DDD 架构文档

生成全面的 DDD 架构文档：C4 模型图（L1-L4）、ADR、领域模型文档、API 文档、决策日志和团队沟通模板。

工作流

生成架构文档时，请遵循以下 5 步工作流：

Step 1: Understand Context — Project size, team, tech stack, domain
Step 2: Identify Audiences — Business / dev / ops
Step 3: Select C4 Level — L1 for business, L2 for ops, L3 for dev team
Step 4: Check Decisions — Any existing ADRs? Need to create new ones?
Step 5: Generate Output — Combine diagrams + ADRs + templates into one doc

信息不足时：先基于常见模式（例如电商）给出一个尽可能合理的版本，并列出仍需哪些具体信息。绝不要只说“请提供更多信息”。

适用范围

✅ 擅长处理

1. C4 模型图生成 — L1 系统上下文 / L2 容器 / L3 组件 / L4 代码（Mermaid）
2. ADR 架构决策记录 — 模板 + 索引 + 状态追踪
3. 领域模型文档 — 聚合描述 + 实体/值对象/事件列表
4. API 文档 — CQRS 命令/查询分离的 API 规范

⚠️ 需要条件

1. 已有架构决策 — 需要先有决策才能记录 ADR
2. 已识别限界上下文 — 至少知道系统有哪些 BC，才能绘制 C4 L1 图
3. 技术栈已知 — 需要知道框架/数据库/中间件，才能生成 L2 容器图

❌ 超出范围（不适用场景）

1. 没有架构决策 → 先做决策再编写文档（路由到 ddd-architecture-selector）
2. 单人项目 → README + 行内注释即可
3. 需要进行架构选型 → ddd-architecture-selector
4. 需要代码审查 → ddd-code-reviewer

受众

此技能面向：后端开发者（实现 DDD 架构）、软件架构师（评估和选择模式）、技术负责人（审查团队实现）和 DDD 初学者（学习领域驱动设计基础知识）。

规则

1. 每项架构决策都必须记录为 ADR。
2. C4 图必须遵循 L1→L4 层级。
3. 领域模型文档必须引用限界上下文。
4. 所有决策日志都必须包含日期、上下文、选项和理由。

C4 模型四层

DDD → C4 映射

C4 Level     | DDD Context                   | Audience
─────────────┼───────────────────────────────┼────────────────
L1 Context   | All bounded contexts + externals | Business, Architects
L2 Container | Per-BC deployment units        | Architects, DevOps
L3 Component | BC internal layers (Adapter/App/Domain/Infra) | Dev Team
L4 Code      | Aggregate internals (entities, VOs, events) | Developers

L1：系统上下文 — 展示系统与外部的关系

graph TB
    Customer["👤 Customer"] --> BC1["Bounded Context 1"]
    Customer --> BC2["Bounded Context 2"]
    Admin["👤 Admin"] --> BC3["Bounded Context 3"]
    BC1 --> PaymentGW["💳 Payment Gateway"]

L2：容器 — 单个 BC 的部署单元

graph TB
    Web["Web App"] --> API["API (Spring Boot)"]
    API --> DB[("Database (PostgreSQL)")]
    API --> Queue["Event Queue (RabbitMQ)"]

完整的 L3/L4 Mermaid 代码示例见 references/01-c4-examples.md。

各层级的适用时机：项目启动时使用 L1，运维交接时使用 L2，日常开发参考使用 L3，仅复杂聚合使用 L4。

ADR（架构决策记录）

ADR 模板

# ADR-{NNN}: {Short Title}

## Status
{Proposed / Accepted / Deprecated / Superseded}

## Context / Decision / Alternatives / Consequences
- **Context**: Why is this decision needed?
- **Decision**: What did we decide?
- **Alternatives**: Options considered with pros/cons, mark chosen
- **Consequences**: Positive + negative impacts
- **Related**: ADR-{NNN}: {related}

ADR 状态追踪表

| ADR# | Title | Status | Date | Superseded By |
|------|-------|:------:|:----:|:----:|
| 001 | Choose COLA Architecture | Accepted | 2024-03-15 | — |
| 002 | CQRS Strategy L2 | Accepted | 2024-03-20 | — |
| 003 | MySQL over PostgreSQL | Deprecated | 2024-02-01 | ADR-005 |

领域模型文档

为每个聚合编写文档：

## Aggregate: {Name}
- **Root**: {ClassName} | **Id**: {IdType}
- **Entities**: Table of entity / owner / lifecycle
- **Value Objects**: Table of VO / fields / immutable
- **Domain Events**: Table of event / trigger / consumer
- **Invariants**: 1. {Invariant 1}
- **State Machine**: ```mermaid stateDiagram-v2```

API 文档 — CQRS 命令/查询分离

API 类型	方法	示例	CQRS 模型
命令	POST/PUT/DELETE	POST /orders	命令模型
查询	GET	GET /orders?status=PAID	查询模型

命令 API：触发领域行为、发布领域事件，并且必须提供幂等键。 查询 API：从查询模型读取数据（可能使用单独的读数据库），没有副作用。

架构决策日志

维护一个中央索引：

docs/adrs/
├── README.md          ← Auto-generated ADL index
├── ADR-001-title.md
└── ...

最佳实践：一个 ADR 文件对应一项决策；ADR 与代码存放在同一个仓库；CI 自动生成索引。

文档维护策略

策略	频率	谁负责
PR 时同步更新 ADR + 图	每次代码变更	开发者
C4 图季度审计	每季度	架构师
ADL 索引自动生成	每次 ADR 变更	CI
全量架构文档审查	每月	架构组

黄金规则：如果代码改变了架构，就必须在同一个 PR 中更新文档。

注意事项 — 常见问题

1. 混淆 C4 层级 — 每层都有明确定义，不要混用。
2. ADR 写得太晚 — 决策时同步记录，哪怕只写一句话。
3. 文档与代码不同步 — 每次架构变更后都必须更新。
4. 只画图，不写决策理由 — C4 展示“是什么”，ADR 解释“为什么”。
5. 图过于复杂 — 每张图最多包含 5-7 个节点。
6. 文档过多 — 聚焦于“别人需要知道什么才能开发”。
7. ADR 不写备选方案 — 必须记录为什么没有选择其他方案。
8. 忽略受众 — 不同受众应使用不同的 C4 级别。

常见问题

Q1：文档应该使用什么工具？ 先用 Mermaid，复杂度增加后再考虑 Structurizr。

Q2：需要绘制哪些 C4 层级？ L1 + L2 是必需的，L3 视团队规模而定（团队人数 >5 时推荐）。

Q3：如何确保文档不过期？ 使用 PR 勾选框 + CI 检查 ADR 一致性 + 每月审查。

Q4：遗留系统没有文档怎么办？ 先绘制 AS-IS 的 L1 图 → 记录关键 ADR → 每个 sprint 完善一个 BC。

Q5：ADR 需要写得多详细？ 至少包含背景、决策、备选方案（≥2 个）和影响。

Q6：多人同时修改同一个 BC 的文档怎么办？ 使用 Git 冲突解决机制即可，并在 PR 审查时同步审查文档。

安全性

此技能仅用于编写文档。它不收集用户数据、不访问外部服务或网络，也不包含可执行脚本。

关键词

• 关键词：架构文档、架构文档、ADR、C4 图、C4 模型、架构决策记录、架构决策记录、领域模型文档、领域模型文档、技术文档、架构图、系统上下文、容器图、组件图、代码图、架构评审、文档模板、架构决策日志

参考资料

文件	内容	何时参考
references/01-c4-examples.md	电商场景的完整 C4 L1-L4 Mermaid 示例	需要可直接复制粘贴的完整 C4 图
references/02-adr-templates.md	3 种 ADR 模板变体（标准版、轻量版、技术版）	需要编写新的 ADR
references/03-doc-templates.md	3 种架构文档模板（完整版、轻量版、入门版）	需要从某种文档结构开始编写
references/04-toolchain.md	工具推荐（Structurizr、Mermaid、PlantUML、ArchUnit）	询问工具或自动化相关问题
references/05-team-templates.md	团队沟通模板（评审请求、变更通知）	需要通知团队或与团队进行评审
references/06-arch-decision-log.md	ADL 索引格式 + CI 自动化	需要维护 ADR 跟踪记录或将其自动化
references/07-domain-model-doc.md	聚合/BC 文档模式	需要编写领域模型文档
references/08-api-doc-patterns.md	CQRS API 文档模式 + OpenAPI 规范	需要编写采用 CQRS 的 API 文档
references/09-trace-anti-patterns.md	架构文档反模式（5 类）	需要避免常见的文档错误
references/10-faq-deep.md	深入 FAQ（微服务 ADR、遗留系统、安全）	有进阶问题或边缘情况问题

相关技能

• ddd-architecture-selector — 架构选型（先做决策，再编写文档）。安装：npx skills add full-stack-skills/ddd-skills --skill ddd-architecture-selector。
• ddd-architecture-evaluator — 定期检查架构健康状况。安装：npx skills add full-stack-skills/ddd-skills --skill ddd-architecture-evaluator。
• ddd-code-reviewer — 检查代码层面的 DDD 合规性。安装：npx skills add full-stack-skills/ddd-skills --skill ddd-code-reviewer。
• ddd-cqrs-architecture — API 文档所需的 CQRS 细节。安装：npx skills add full-stack-skills/ddd-skills --skill ddd-cqrs-architecture。
• ddd-architecture-awesome — DDD 概念概览。安装：npx skills add full-stack-skills/ddd-skills --skill ddd-architecture-awesome。