文档架构生成Skill doc-architecture

---

名称: 文档架构生成 描述: 使用arc42或C4模型生成架构文档。用于创建系统上下文、容器和组件图以及叙述。 允许工具: 读取、全局搜索、grep、写入、技能 参数提示: <主题> [–格式 arc42|c4|两者] [–级别 上下文|容器|组件]

生成架构文档

为系统或组件创建全面的架构文档。

过程

1. 解析参数

从用户输入中提取：

• 主题: 要记录的系统/组件（必需）
• 格式: arc42、c4 或 两者（默认：c4）
• 级别: 对于C4 - 上下文、容器 或 组件（默认：容器）

2. 分析系统

探索代码库以理解：

1. 系统边界: 范围是什么？
2. 外部依赖: 与哪些系统交互？
3. 内部结构: 如何组织？
4. 技术栈: 使用哪些技术？
5. 关键流程: 重要场景是什么？

使用文件探索收集信息：

• 解决方案/项目文件以了解结构
• 配置文件以了解依赖
• 入口点以获取架构线索
• 现有文档

3. 生成文档

基于格式参数：

如果格式 = c4:

1. 加载 c4-文档 技能
2. 在请求的级别生成图：
   • 上下文: 系统与用户和外部系统
   • 容器: 内部应用程序和数据存储
   • 组件: 容器的内部结构
3. 每个图包含叙述描述

如果格式 = arc42:

1. 加载 arc42-文档 技能
2. 生成相关部分：
   • 介绍和目标
   • 架构约束
   • 系统范围和环境
   • 解决方案策略
   • 构建块视图
   • 运行时视图（关键场景）
   • 部署视图
   • 横切概念

如果格式 = 两者:

1. 生成arc42文档
2. 在适当部分嵌入C4图

4. 输出结构

创建文档文件：

对于C4:
docs/architecture/
└── {主题}-c4-{级别}.md

对于arc42:
docs/architecture/
└── {主题}-arc42.md

对于两者:
docs/architecture/
├── {主题}-架构.md  # arc42带嵌入C4
└── diagrams/
    ├── 上下文.mmd
    ├── 容器.mmd
    └── 组件.mmd

5. 包含在输出中

每个生成的文档应包含：

1. 带元数据的页眉

   • 标题
   • 最后更新日期
   • 作者（如果已知）
   • 版本

2. 图（Mermaid格式）

   • 正确格式化的C4图
   • 如果需要，包括图例

3. 叙述

   • 环境和目的
   • 关键决策和理由
   • 技术选择
   • 承认的权衡

4. 参考文献

   • 链接到相关文档
   • 外部资源
   • 如果适用，包括ADR

示例调用

/文档架构生成 "订单服务"
→ 为订单服务生成C4容器图

/文档架构生成 "支付网关" 格式=arc42
→ 生成完整的arc42文档

/文档架构生成 "API网关" 格式=c4 级别=组件
→ 生成C4组件图

/文档架构生成 "整个系统" 格式=两者 级别=上下文
→ 生成带嵌入C4上下文图的arc42文档

质量标准

生成的文档必须：

• [ ] 准确反映系统结构
• [ ] 使用一致的术语
• [ ] 包含有效的Mermaid/PlantUML语法
• [ ] 解释“为什么”而不仅仅是“什么”
• [ ] 对读者可操作
• [ ] 遵循项目文档约定