Back to Details

diagram

Compare original and translation side by side

🇺🇸

Original

English
🇨🇳

Translation

Chinese

Diagram Driven Development (DDD) Skill

Diagram Driven Development (DDD) 技能

Maintain the 
ai/diagrams
directory as the single source of truth for system understanding. All diagrams follow DDD principles, connecting Front-Stage (user experience) to Back-Stage (technical implementation) with clear impact annotations.
将
ai/diagrams
目录作为系统认知的唯一可信数据源进行维护。所有图表均遵循DDD原则，通过清晰的影响注释将前端（用户体验）与后端（技术实现）关联起来。

Capabilities

能力

  1. Create Diagrams - Generate new diagrams for features, architectures, journeys, tests, and refactorings
  2. Update Diagrams - Synchronize existing diagrams with code changes
  3. Audit Diagrams - Identify outdated, missing, or low-quality diagrams
  4. Organize Diagrams - Maintain consistent structure and naming conventions
  5. Index Management - Keep README.md index up-to-date with all diagrams
  6. Quality Validation - Ensure all diagrams follow DDD principles
  1. 创建图表 - 为功能、架构、用户旅程、测试和重构生成新图表
  2. 更新图表 - 使现有图表与代码变更保持同步
  3. 审计图表 - 识别过时、缺失或低质量的图表
  4. 整理图表 - 保持一致的结构和命名规范
  5. 索引管理 - 维护README.md索引，使其包含所有图表
  6. 质量验证 - 确保所有图表遵循DDD原则

Quick Reference

快速参考

For detailed instructions on each operation, see:
  • CREATE.md - Creating new diagrams
  • UPDATE.md - Updating existing diagrams
  • AUDIT.md - Auditing diagram quality and coverage
  • ORGANIZE.md - Directory structure and naming
  • DDD_PRINCIPLES.md - Diagram Driven Development methodology
  • MERMAID_GUIDE.md - Mermaid syntax patterns
有关各项操作的详细说明，请参阅：
  • CREATE.md - 创建新图表
  • UPDATE.md - 更新现有图表
  • AUDIT.md - 审计图表质量与覆盖范围
  • ORGANIZE.md - 目录结构与命名规则
  • DDD_PRINCIPLES.md - Diagram Driven Development方法论
  • MERMAID_GUIDE.md - Mermaid语法规范

Directory Structure

目录结构

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
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

Common Workflows

常见工作流

Initial Setup Workflow

初始设置工作流

  1. User starts new project or adds DDD to existing project
  2. Create 
    ai/diagrams/
    directory structure
  3. Generate initial system architecture diagram
  4. Create README.md index
  5. Document key user journeys
  1. 用户启动新项目或在现有项目中引入DDD
  2. 创建
    ai/diagrams/
    目录结构
  3. 生成初始系统架构图表
  4. 创建README.md索引
  5. 记录关键用户旅程

New Feature Workflow

新功能工作流

  1. User requests new feature
  2. Create feature diagram showing user value
  3. Connect Front-Stage (UX) to Back-Stage (implementation)
  4. Document related files and components
  5. Update README.md index
  1. 用户提出新功能需求
  2. 创建展示用户价值的功能图表
  3. 关联前端（UX）与后端（实现）
  4. 记录相关文件和组件
  5. 更新README.md索引

Code Change Workflow

代码变更工作流

  1. Code is modified (new features, refactoring, etc.)
  2. Identify affected diagrams
  3. Update diagrams to reflect changes
  4. Update "Last Updated" dates
  5. Add change history entries
  1. 代码被修改（新功能、重构等）
  2. 识别受影响的图表
  3. 更新图表以反映变更
  4. 更新“最后更新”日期
  5. 添加变更历史条目

Audit Workflow

审计工作流

  1. User requests diagram audit
  2. Scan all diagrams in 
    ai/diagrams/
  3. Check for outdated diagrams (compare dates with git)
  4. Identify missing diagrams (features without diagrams)
  5. Validate DDD quality (Front-Stage/Back-Stage, impact annotations)
  6. Report findings and recommendations
  1. 用户请求图表审计
  2. 扫描
    ai/diagrams/
    下的所有图表
  3. 检查过时图表（与git日期对比）
  4. 识别缺失的图表（无对应图表的功能）
  5. 验证DDD质量（前端/后端关联、影响注释）
  6. 提交审计结果与建议

Refactoring Documentation Workflow

重构文档工作流

  1. User plans code refactoring
  2. Create "Before" diagram showing current state
  3. Create "After" diagram showing improved state (highlight changes in #90EE90)
  4. Add impact annotations explaining user benefits
  5. Store in 
    refactoring/
    directory
  1. 用户计划代码重构
  2. 创建展示当前状态的“重构前”图表
  3. 创建展示改进后状态的“重构后”图表（用#90EE90高亮变更）
  4. 添加解释用户收益的影响注释
  5. 存储在
    refactoring/
    目录下

Critical Instructions

关键说明

REQUIRED: Before performing ANY diagram operations, you MUST load the relevant reference file(s) using the Read tool. These references contain essential DDD principles, quality standards, and operational procedures that are NOT included in this overview.
When the user asks to work with diagrams:
  1. Identify the operation they want to perform (create, update, audit, organize)
  2. MANDATORY: Load the relevant reference file(s) using the Read tool BEFORE executing any operations:
    • Creating diagrams → Read 
      references/CREATE.md
      AND 
      references/DDD_PRINCIPLES.md
      FIRST
    • Updating diagrams → Read 
      references/UPDATE.md
      AND 
      references/DDD_PRINCIPLES.md
      FIRST
    • Auditing diagrams → Read 
      references/AUDIT.md
      FIRST
    • Organizing/restructuring → Read 
      references/ORGANIZE.md
      FIRST
    • Understanding DDD → Read 
      references/DDD_PRINCIPLES.md
      FIRST
    • Mermaid syntax help → Read 
      references/MERMAID_GUIDE.md
      FIRST
  3. Execute diagram operations following the exact patterns and quality standards from the loaded references
  4. Validate quality using DDD principles checklist
  5. Update index in README.md to reflect changes
  6. Confirm actions and show diagram preview when possible
DO NOT attempt to create or modify diagrams without first loading and reading the relevant reference documentation, especially DDD_PRINCIPLES.md.
强制要求：在执行任何图表操作之前，必须使用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 Core Principles (Brief)

DDD核心原则（摘要）

Every diagram MUST include:
  • ✅ Front-Stage (user experience) AND Back-Stage (implementation)
  • ✅ Impact Annotations explaining user value of technical components
  • ✅ User Actions as entry/exit points
  • ✅ Error Paths and recovery options
  • ✅ Related Files documentation
  • ❌ NO custom fill colors (except 
    #90EE90
    for Before/After changes)
  • ❌ NO purely technical diagrams without user context
每个图表必须包含：
  • ✅ 前端（用户体验）和后端（实现）
  • ✅ 影响注释：解释技术组件的用户价值
  • ✅ 用户操作作为入口/出口点
  • ✅ 错误路径和恢复选项
  • ✅ 相关文件文档
  • ❌ 禁止自定义填充颜色（除了用于“重构前/后”对比的
    #90EE90
    ）
  • ❌ 禁止无用户上下文的纯技术图表

Naming Conventions

命名规范

File Names

文件名

  • Descriptive lowercase with hyphens
  • Include diagram type prefix
  • Format: 
    {type}-{descriptive-name}.md
Examples:
  • feature-user-checkout-flow.md
  • sequence-authentication-journey.md
  • arch-system-overview.md
  • flow-payment-processing.md
  • 描述性小写，使用连字符分隔
  • 包含图表类型前缀
  • 格式：
    {type}-{descriptive-name}.md
示例：
  • feature-user-checkout-flow.md
  • sequence-authentication-journey.md
  • arch-system-overview.md
  • flow-payment-processing.md

Type Prefixes

类型前缀

  • feature-
    - Feature-specific diagrams
  • sequence-
    - Sequence/journey diagrams
  • arch-
    - Architecture diagrams
  • flow-
    - Flow/process diagrams
  • test-
    - Test coverage diagrams
  • feature-
    - 功能相关图表
  • sequence-
    - 序列/用户旅程图表
  • arch-
    - 架构图表
  • flow-
    - 流程/流转图表
  • test-
    - 测试覆盖图表

Diagram File Structure

图表文件结构

markdown
undefined
markdown
undefined

[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
类型： [功能图表 | 序列图表 | 架构图表 | 其他] 最后更新： [YYYY-MM-DD] 相关文件：
  • path/to/implementation.ts
  • path/to/component.tsx

Purpose

目的

[1-2 sentence description of what user value this diagram illustrates]
[1-2句话说明此图表展示的用户价值]

Diagram

图表

```mermaid [Mermaid diagram code following DDD principles] ```
mermaid
[遵循DDD原则的Mermaid图表代码]

Key Insights

关键要点

  • [User impact point 1]
  • [User impact point 2]
  • [Technical enabler point 1]
  • [用户影响点1]
  • [用户影响点2]
  • [技术支撑点1]

Change History

变更历史

  • YYYY-MM-DD: [Description of change]
undefined
  • YYYY-MM-DD： [变更描述]
undefined

Quality Checklist

质量检查表

Before storing any diagram, verify:
  • Shows both Front-Stage (user experience) AND Back-Stage (implementation)
  • Impact annotations explain user value
  • User actions are clearly visible
  • Error paths shown
  • NO custom fill colors (except #90EE90 for changes)
  • Related code files documented
  • Last updated date is current
  • Key insights explain user impact
  • Mermaid syntax is valid
在存储任何图表之前，请验证：
  • 同时展示前端（用户体验）和后端（实现）
  • 影响注释解释了用户价值
  • 用户操作清晰可见
  • 展示了错误路径
  • 无自定义填充颜色（除了用于变更的#90EE90）
  • 记录了相关代码文件
  • 最后更新日期为当前日期
  • 关键要点解释了用户影响
  • Mermaid语法有效

Best Practices

最佳实践

  1. Keep diagrams synchronized - Outdated diagrams are worse than no diagrams
  2. Follow DDD principles - Every diagram connects user value to implementation
  3. Use subdirectories - Organize by type to prevent chaos
  4. Maintain the index - README.md is the entry point
  5. Document changes - Update change history when modifying
  6. Validate quality - Run through DDD checklist before saving
  7. Reference code files - Link diagrams to actual implementation
  8. Show error paths - Don't just show happy paths
  9. Use consistent naming - Predictable names enable navigation
  10. Update after code changes - Diagrams must reflect current state
  1. 保持图表同步 - 过时的图表不如没有图表
  2. 遵循DDD原则 - 每个图表都要关联用户价值与实现
  3. 使用子目录 - 按类型组织以避免混乱
  4. 维护索引 - README.md是入口点
  5. 记录变更 - 修改时更新变更历史
  6. 验证质量 - 保存前通过DDD检查表
  7. 关联代码文件 - 将图表链接到实际实现
  8. 展示错误路径 - 不要只展示正常流程
  9. 使用一致命名 - 可预测的命名便于导航
  10. 代码变更后更新 - 图表必须反映当前状态

Integration with Other Skills

与其他Skill的集成

  • review - Reference diagrams during code reviews to explain impact
  • github - Link diagrams in issue descriptions for context
  • chrome-devtools - Use diagrams to plan testing flows
  • review - 代码评审时参考图表解释影响
  • github - 在Issue描述中链接图表以提供上下文
  • chrome-devtools - 使用图表规划测试流程

Examples

示例

Create feature diagram

创建功能图表

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: "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

Update after refactoring

重构后更新图表

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: "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

Audit all diagrams

审计所有图表

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
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

Critical Rules

关键规则

  1. Diagrams MUST stay synchronized with code - Check git history vs diagram dates
  2. Every diagram MUST follow DDD principles - No purely technical diagrams
  3. Organization is critical - Use subdirectories consistently
  4. Index MUST be maintained - README.md reflects all diagrams
  5. File naming MUST be consistent - Follow type-name pattern
  6. Quality over quantity - Better to have 5 great diagrams than 20 poor ones
  7. User value is paramount - Every technical detail must connect to user impact
  8. Always load references first - DDD principles are not negotiable
  1. 图表必须与代码保持同步 - 对比git历史与图表日期
  2. 每个图表必须遵循DDD原则 - 禁止纯技术图表
  3. 组织至关重要 - 持续使用子目录
  4. 必须维护索引 - README.md需包含所有图表
  5. 文件名必须一致 - 遵循类型-名称模式
  6. 质量优先于数量 - 5个优质图表胜过20个劣质图表
  7. 用户价值至上 - 每个技术细节都必须关联用户影响
  8. 始终先加载参考文件 - DDD原则不可协商

Workflow Integration

工作流集成

This skill integrates with development workflow:
  1. Before Code Changes - Review existing diagrams to understand system
  2. During Planning - Create proposal diagrams showing planned changes
  3. During Implementation - Reference diagrams to maintain alignment
  4. After Implementation - Update diagrams to reflect changes
  5. During Review - Use diagrams to explain impact and context
  6. During Onboarding - Diagrams serve as documentation for new team members
此Skill可集成到开发工作流中：
  1. 代码变更前 - 查看现有图表以理解系统
  2. 规划阶段 - 创建展示计划变更的提案图表
  3. 实现阶段 - 参考图表以保持一致性
  4. 实现后 - 更新图表以反映变更
  5. 评审阶段 - 使用图表解释影响和上下文
  6. 入职阶段 - 图表作为新团队成员的文档资料