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 の中核原則（概要）

すべての図に必ず含めるもの：

• ✅ フロントステージ（ユーザー体験）とバックステージ（実装）
• ✅ 技術コンポーネントのユーザー価値を説明する影響注釈
• ✅ 開始点／終了点となるユーザー操作
• ✅ エラーパスと復旧方法
• ✅ 関連ファイルのドキュメント
• ❌ カスタムの塗りつぶし色は使用しない（Before/After の変更を示す #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 - issue の説明に図をリンクして、背景を示します
• 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. オンボーディング中 - 図を新しいチームメンバー向けのドキュメントとして活用します