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

能力

Create Diagrams - Generate new diagrams for features, architectures, journeys, tests, and refactorings
Update Diagrams - Synchronize existing diagrams with code changes
Audit Diagrams - Identify outdated, missing, or low-quality diagrams
Organize Diagrams - Maintain consistent structure and naming conventions
Index Management - Keep README.md index up-to-date with all diagrams
Quality Validation - Ensure all diagrams follow DDD principles

创建图表 - 为功能、架构、用户旅程、测试和重构生成新图表
更新图表 - 使现有图表与代码变更保持同步
审计图表 - 识别过时、缺失或低质量的图表
整理图表 - 保持一致的结构和命名规范
索引管理 - 维护README.md索引，使其包含所有图表
质量验证 - 确保所有图表遵循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

初始设置工作流

User starts new project or adds DDD to existing project
Create
```
ai/diagrams/
```
directory structure
Generate initial system architecture diagram
Create README.md index
Document key user journeys

用户启动新项目或在现有项目中引入DDD
创建
```
ai/diagrams/
```
目录结构
生成初始系统架构图表
创建README.md索引
记录关键用户旅程

New Feature Workflow

新功能工作流

User requests new feature
Create feature diagram showing user value
Connect Front-Stage (UX) to Back-Stage (implementation)
Document related files and components
Update README.md index

用户提出新功能需求
创建展示用户价值的功能图表
关联前端（UX）与后端（实现）
记录相关文件和组件
更新README.md索引

Code Change Workflow

代码变更工作流

Code is modified (new features, refactoring, etc.)
Identify affected diagrams
Update diagrams to reflect changes
Update "Last Updated" dates
Add change history entries

代码被修改（新功能、重构等）
识别受影响的图表
更新图表以反映变更
更新“最后更新”日期
添加变更历史条目

Audit Workflow

审计工作流

User requests diagram audit
Scan all diagrams in
```
ai/diagrams/
```
Check for outdated diagrams (compare dates with git)
Identify missing diagrams (features without diagrams)
Validate DDD quality (Front-Stage/Back-Stage, impact annotations)
Report findings and recommendations

用户请求图表审计
扫描
```
ai/diagrams/
```
下的所有图表
检查过时图表（与git日期对比）
识别缺失的图表（无对应图表的功能）
验证DDD质量（前端/后端关联、影响注释）
提交审计结果与建议

Refactoring Documentation Workflow

重构文档工作流

User plans code refactoring
Create "Before" diagram showing current state
Create "After" diagram showing improved state (highlight changes in #90EE90)
Add impact annotations explaining user benefits
Store in
```
refactoring/
```
directory

用户计划代码重构
创建展示当前状态的“重构前”图表
创建展示改进后状态的“重构后”图表（用#90EE90高亮变更）
添加解释用户收益的影响注释
存储在
```
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:

Identify the operation they want to perform (create, update, audit, organize)
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
Execute diagram operations following the exact patterns and quality standards from the loaded references
Validate quality using DDD principles checklist
Update index in README.md to reflect changes
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原则、质量标准和操作流程。

当用户要求处理图表时：

识别操作类型：确定用户想要执行的操作（创建、更新、审计、整理）
强制步骤：加载相关参考文件：在执行任何操作之前，必须使用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
```
执行图表操作：严格遵循已加载参考文件中的模式和质量标准
质量验证：使用DDD原则检查表进行验证
更新索引：在README.md中更新索引以反映变更
确认操作：尽可能展示图表预览

禁止：在未加载并阅读相关参考文档（尤其是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

质量检查表

Best Practices

最佳实践

Keep diagrams synchronized - Outdated diagrams are worse than no diagrams
Follow DDD principles - Every diagram connects user value to implementation
Use subdirectories - Organize by type to prevent chaos
Maintain the index - README.md is the entry point
Document changes - Update change history when modifying
Validate quality - Run through DDD checklist before saving
Reference code files - Link diagrams to actual implementation
Show error paths - Don't just show happy paths
Use consistent naming - Predictable names enable navigation
Update after code changes - Diagrams must reflect current state

保持图表同步 - 过时的图表不如没有图表
遵循DDD原则 - 每个图表都要关联用户价值与实现
使用子目录 - 按类型组织以避免混乱
维护索引 - README.md是入口点
记录变更 - 修改时更新变更历史
验证质量 - 保存前通过DDD检查表
关联代码文件 - 将图表链接到实际实现
展示错误路径 - 不要只展示正常流程
使用一致命名 - 可预测的命名便于导航
代码变更后更新 - 图表必须反映当前状态

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

关键规则

Diagrams MUST stay synchronized with code - Check git history vs diagram dates
Every diagram MUST follow DDD principles - No purely technical diagrams
Organization is critical - Use subdirectories consistently
Index MUST be maintained - README.md reflects all diagrams
File naming MUST be consistent - Follow type-name pattern
Quality over quantity - Better to have 5 great diagrams than 20 poor ones
User value is paramount - Every technical detail must connect to user impact
Always load references first - DDD principles are not negotiable

图表必须与代码保持同步 - 对比git历史与图表日期
每个图表必须遵循DDD原则 - 禁止纯技术图表
组织至关重要 - 持续使用子目录
必须维护索引 - README.md需包含所有图表
文件名必须一致 - 遵循类型-名称模式
质量优先于数量 - 5个优质图表胜过20个劣质图表
用户价值至上 - 每个技术细节都必须关联用户影响
始终先加载参考文件 - DDD原则不可协商

Workflow Integration

工作流集成

This skill integrates with development workflow:

Before Code Changes - Review existing diagrams to understand system
During Planning - Create proposal diagrams showing planned changes
During Implementation - Reference diagrams to maintain alignment
After Implementation - Update diagrams to reflect changes
During Review - Use diagrams to explain impact and context
During Onboarding - Diagrams serve as documentation for new team members

此Skill可集成到开发工作流中：

代码变更前 - 查看现有图表以理解系统
规划阶段 - 创建展示计划变更的提案图表
实现阶段 - 参考图表以保持一致性
实现后 - 更新图表以反映变更
评审阶段 - 使用图表解释影响和上下文
入职阶段 - 图表作为新团队成员的文档资料