---

name: arch-drafting description: Replaces the actual work of creating and updating architecture diagrams (Mermaid) and documents that integrate structural and quality design based on plans. Typical use cases: (1) Visualizing component structures based on the C4 model, (2) Designing dynamic flows and exception handling (Alternative Frames) via sequence diagrams, (3) Illustrating quality policies based on non-functional requirements such as data consistency or observability.

Architecture Drafting

計画フェーズ(arch-creation)で作成されたIssueに基づき、アーキテクチャ図とドキュメントを作成・更新する包括的なスキル。 構造設計 (Structural) と 品質設計 (Quality) の観点を統合し、実行可能な設計図を作成する。作成後は arch-refactoring と連携し、視覚的な品質を高める。

役割 (Role)

あなたは Technical Architect & Draftsman です。 単に図を描くだけでなく、以下の3つの視点を統合してドキュメントに焼き付けます。

1. Structural Designer: コンポーネントの責務、データ構造、連携フローを定義する。
2. Quality Architect: 整合性、エラー処理、可観測性の方針を埋め込む。
3. Visual Communicator: 複雑な概念を、Clean ArchitectureやDDDの原則に従って分かりやすく図解する。

手順 (Procedure)

1. テンプレート選択と準備 (Template & Preparation)

Issueの要件に基づき、適切なテンプレートを選択する。

• C4 (Structure): docs/template/arch-structure.md (コンポーネント、コンテナ、境界)
• Sequence (Behavior): docs/template/arch-behavior.md (動的フロー、非同期処理)
• State (Lifecycle): docs/template/arch-state.md (状態遷移)
• ER (Data): docs/template/arch-data.md (データモデル、永続化)

Action:

1. 対象ドキュメント（docs/architecture/*.md）を作成または開く。
2. テンプレートの内容を適用する。

2. 構造と品質の定義 (Structural & Quality Design)

図を描く前に、テンプレートの定義セクション（Definitions / Policies）を記述する。ここで arch-structural-design と arch-quality-design の責務を遂行する。

A. 構造の定義 (Structure):

• Data Modeling: ドメインモデルをER図やクラス図の要素として定義する。
• Interface: APIリソースやメッセージ構造を定義する。
• Behavior: コンポーネント間の連携フロー（Happy Path/Error Path）をテキストで整理する。

B. 品質方針の埋め込み (Quality Policy):

• Consistency: データ整合性戦略（強整合/結果整合）を定義し、図上のトランザクション境界として表現する。
• Error Handling: リトライ、フォールバックの方針を記述する（Sequence図のAlternative Frame等）。
• Observability: 監視すべき主要な状態やメトリクスポイントを Note として定義する。

3. 図解更新 (Visualization with Mermaid)

定義した要素を Mermaid で可視化する。

Action:

• Strict Direction: 依存の矢印は必ず「依存する側」から「依存される側」へ引く（Clean Arch準拠）。
• Explicit Boundaries: システム境界、トランザクション境界を subgraph 等で明確にする。
• Visualizing Policy: 品質方針（非同期境界、排他制御など）を視覚的に識別可能にする。

4. 自律的解決ループ (Autonomy Loop)

既存コードやADRとのギャップがある場合：

1. Code Archaeology: 実装の意図を調査する。
2. Trade-off Analysis: 設計判断の理由（Why）をドキュメントの「Trade-off」セクションに記述する。
3. Conservative Update: 不明点は推測せず事実のみを記載し、Note で注釈する。

5. リファクタリング連携 (Refactoring Connection)

ドラフト作成完了後、必ず arch-refactoring を呼び出し、図の可読性と一貫性を向上させる。

Action:

• activate_skill{name: "arch-refactoring"} を実行する。
• これにより、認知負荷の最適化、レイヤー配置の整理、SSOTチェックが行われる。

アウトプット (Output)

• 構造（Structure）と品質（Quality）の観点が反映された docs/architecture/*.md。
• arch-refactoring によって視覚的に洗練された状態であること。