C4 架构文档工作流

要解决什么问题

现有仓库往往只有零散 README 或局部注释，缺少与 C4 模型 对齐、能从代码一路追到部署与业务上下文的文档。手工补全四层图（Context、Container、Component、Code）成本高，且容易在「先画高层图、细节对不上代码」上翻车。

工作流如何运作

本技能采用自底向上路径：从仓库最深子目录开始，逐层向上综合，保证高层抽象建立在已记录的代码元素之上。协调四个专门子代理（c4-code、c4-component、c4-container、c4-context），产出写入仓库根目录 C4-Documentation/。

• 代码层：遍历子目录（排除 node_modules、.git、build 等），为每个目录生成 c4-code-*.md，含函数/类签名、依赖与可选 Mermaid 关系图。
• 组件层：按领域/技术边界合并代码文档，产出 c4-component-*.md 与主索引 c4-component.md。
• 容器层：结合 Dockerfile、K8s、Compose 等部署定义，映射组件到运行单元，并可为 API 生成 OpenAPI 规范（默认 apis/*.yaml）。
• 上下文层：结合 README、需求与测试等行为线索，写角色画像、用户旅程与 C4Context 风格的系统上下文图（c4-context.md）。

可配置 target_directory、exclude_patterns、output_directory、include_tests、api_format 等。

适用边界

任务与 C4 架构文档生成无关时不必启用。官方 C4 也指出：多数团队上下文图 + 容器图已够用；本工作流为完整性会生成四层，你可只选用需要的层级。文档质量仍依赖仓库结构清晰度与现有系统文档是否齐全。