diagram

图表驱动开发（DDD）技能

将 ai/diagrams 目录维护为系统理解的唯一事实来源。所有图表均遵循 DDD 原则，通过清晰的影响说明将前台（用户体验）与后台（技术实现）连接起来。

功能

1. 创建图表 - 为功能、架构、用户旅程、测试和重构生成新图表
2. 更新图表 - 根据代码变更同步现有图表
3. 审查图表 - 找出过时、缺失或质量低下的图表
4. 整理图表 - 维护一致的结构和命名约定
5. 索引管理 - 确保 README.md 索引包含所有图表且保持最新
6. 质量验证 - 确保所有图表均遵循 DDD 原则

快速参考

有关各项操作的详细说明，请参阅：

• CREATE.md - 创建新图表
• UPDATE.md - 更新现有图表
• AUDIT.md - 审查图表质量和覆盖范围
• ORGANIZE.md - 目录结构和命名
• DDD_PRINCIPLES.md - 图表驱动开发方法
• MERMAID_GUIDE.md - Mermaid 语法模式

目录结构

ai/diagrams/
├── README.md                    # Index of all diagrams
├── features/                    # Feature-specific diagrams
├── architecture/                # System architecture diagrams
├── journeys/                    # User journey diagrams
├── tests/                       # Test coverage diagrams
└── refactoring/                 # Before/After improvement diagrams

常见工作流

初始设置工作流

1. 用户启动新项目，或为现有项目添加 DDD
2. 创建 ai/diagrams/ 目录结构
3. 生成初始系统架构图
4. 创建 README.md 索引
5. 记录关键用户旅程

新功能工作流

1. 用户提出新功能需求
2. 创建展示用户价值的功能图
3. 将前台（UX）与后台（实现）连接起来
4. 记录相关文件和组件
5. 更新 README.md 索引

代码变更工作流

1. 修改代码（新增功能、重构等）
2. 确定受影响的图表
3. 更新图表以反映变更
4. 更新“最后更新”日期
5. 添加变更历史记录

审查工作流

1. 用户请求审查图表
2. 扫描 ai/diagrams/ 中的所有图表
3. 检查是否存在过时图表（将日期与 git 中的日期进行比较）
4. 找出缺失的图表（有功能却没有对应图表）
5. 验证 DDD 质量（前台/后台、影响说明）
6. 报告发现和建议

重构文档工作流

1. 用户计划重构代码
2. 创建展示当前状态的“之前”图表
3. 创建展示改进后状态的“之后”图表（使用 #90EE90 突出变更）
4. 添加影响说明，解释用户将获得的好处
5. 保存到 refactoring/ 目录

关键指示

必须遵守：执行任何图表操作之前，必须先使用 Read 工具加载相关参考文件。这些参考文件包含本概览中未包含的关键 DDD 原则、质量标准和操作流程。

当用户要求处理图表时：

1. 确定用户想要执行的操作（创建、更新、审计、整理）
2. 必须遵守：在执行任何操作之前，使用 Read 工具加载相关参考文件：
   • 创建图表 → 首先读取 references/CREATE.md 和 references/DDD_PRINCIPLES.md
   • 更新图表 → 首先读取 references/UPDATE.md 和 references/DDD_PRINCIPLES.md
   • 审计图表 → 首先读取 references/AUDIT.md
   • 整理／重构 → 首先读取 references/ORGANIZE.md
   • 理解 DDD → 首先读取 references/DDD_PRINCIPLES.md
   • Mermaid 语法帮助 → 首先读取 references/MERMAID_GUIDE.md
3. 按照已加载参考文件中的确切模式和质量标准执行图表操作
4. 使用 DDD 原则检查清单验证质量
5. 更新 README.md 中的索引以反映更改
6. 确认已执行的操作，并尽可能展示图表预览

未先加载并阅读相关参考文档时，切勿尝试创建或修改图表，尤其是 DDD_PRINCIPLES.md。

DDD 核心原则（简述）

每张图表都必须包含：

• ✅ 前台（用户体验）和后台（实现）
• ✅ 影响说明，解释技术组件为用户带来的价值
• ✅ 用户操作作为入口／出口点
• ✅ 错误路径和恢复选项
• ✅ 相关文件文档
• ❌ 不得使用自定义填充颜色（#90EE90 用于前后对比更改时除外）
• ❌ 不得绘制缺少用户上下文的纯技术图表

命名约定

文件名

• 使用描述性小写词语，以连字符分隔
• 包含图表类型前缀
• 格式：{type}-{descriptive-name}.md

示例：

• feature-user-checkout-flow.md
• sequence-authentication-journey.md
• arch-system-overview.md
• flow-payment-processing.md

类型前缀

• feature- - 特性专用图表
• sequence- - 序列／旅程图
• arch- - 架构图
• flow- - 流程／过程图
• test- - 测试覆盖图

图表文件结构

# [Diagram Title]

**Type:** [Feature Diagram | Sequence Diagram | Architecture Diagram | etc.]
**Last Updated:** [YYYY-MM-DD]
**Related Files:**
- `path/to/implementation.ts`
- `path/to/component.tsx`

## Purpose

[1-2 sentence description of what user value this diagram illustrates]

## Diagram

\`\`\`mermaid
[Mermaid diagram code following DDD principles]
\`\`\`

## Key Insights

- [User impact point 1]
- [User impact point 2]
- [Technical enabler point 1]

## Change History

- **YYYY-MM-DD:** [Description of change]

质量检查清单

保存任何图表之前，请确认：

• 同时展示前台（用户体验）和后台（实现）
• 影响说明阐明用户价值
• 清晰展示用户操作
• 展示错误路径
• 不得使用自定义填充颜色（更改时使用 #90EE90 除外）
• 记录相关代码文件
• 最近更新日期为当前日期
• 关键见解阐明对用户的影响
• Mermaid 语法有效

最佳实践

1. 保持图表同步 - 过时的图表比没有图表更糟
2. 遵循 DDD 原则 - 每张图表都将用户价值与实现关联起来
3. 使用子目录 - 按类型整理，避免混乱
4. 维护索引 - README.md 是入口
5. 记录更改 - 修改时更新更改历史
6. 验证质量 - 保存前按照 DDD 检查清单逐项检查
7. 引用代码文件 - 将图表链接到实际实现
8. 展示错误路径 - 不要只展示顺利路径
9. 使用一致的命名 - 使用可预测的名称，便于导航
10. 代码更改后及时更新 - 图表必须反映当前状态

与其他技能集成

• review - 在代码审查期间引用图表，以说明影响
• github - 在问题描述中链接图表，提供上下文
• chrome-devtools - 使用图表规划测试流程

示例

创建特性图表

User: "Create a diagram for the new notification system"
Agent:
1. Reads references/CREATE.md and references/DDD_PRINCIPLES.md
2. Analyzes notification feature code
3. Creates feature-notification-system.md in features/
4. Includes user journey and technical implementation
5. Adds impact annotations
6. Updates README.md index

重构后更新

User: "We just refactored the auth flow, update the diagram"
Agent:
1. Reads references/UPDATE.md
2. Finds sequence-authentication-journey.md
3. Compares with new code
4. Updates diagram with changes
5. Updates "Last Updated" date
6. Adds change history entry

审计所有图表

User: "Audit our diagrams"
Agent:
1. Reads references/AUDIT.md and references/DDD_PRINCIPLES.md
2. Scans ai/diagrams/ directory
3. Checks each diagram against DDD checklist
4. Compares diagram dates with git history
5. Identifies missing diagrams
6. Reports findings with recommendations

核心规则

1. 图表必须与代码保持同步 —— 对照图表日期检查 Git 历史记录
2. 每张图表都必须遵循 DDD 原则 —— 不得绘制纯技术图表
3. 组织方式至关重要 —— 一贯使用子目录
4. 必须维护索引 —— README.md 应反映所有图表
5. 文件命名必须一致 —— 遵循类型-名称模式
6. 质量重于数量 —— 与其有 20 张质量欠佳的图表，不如有 5 张出色的图表
7. 用户价值至关重要 —— 每个技术细节都必须与用户影响相关
8. 始终先加载参考资料 —— DDD 原则不容妥协

工作流集成

此技能集成到开发工作流中：

1. 代码变更前 —— 查看现有图表以了解系统
2. 规划期间 —— 创建展示计划变更的提案图表
3. 实施期间 —— 参考图表以保持一致
4. 实施后 —— 更新图表以反映变更
5. 评审期间 —— 使用图表说明影响和背景
6. 入职培训期间 —— 图表可作为新团队成员的文档