yodogawa 2.0.0 → 2.1.0

package/skills/a-012-define-api-spec/SKILL.md

@@ -1,132 +1,108 @@
----
-name: a-012-define-api-spec
-description: データモデルと画面設計からAPI仕様を定義し、認証方式、エンドポイント一覧、共通レスポンス形式を明確化するワークフロー
----
-
-# DefineAPISpec (a-012)
-
-## 目的
-
-- データモデルと画面設計を基に、API仕様の基本設計を定義する。
-- API設計スタイル（REST、GraphQL、gRPC、tRPC）を決定する。
-- 認証・認可方式を明確化する。
-- エンドポイント一覧（メソッド、パス、説明、認証要否）を定義する。
-- 共通レスポンス形式（成功/エラー）を定義する。
-
-## 前提
-
-- `docs/project/design/01-tech-stack.md` が作成されていること（APIスタイル選定済み）。
-- `docs/project/design/05-data-model.md` が作成されていること。
-- `docs/project/design/03-screen-design.md` が作成されていること。
-- `docs/project/design/` ディレクトリが存在すること。
-
-## 手順
-
-### 1. ドキュメントと前提条件の確認
-
-- 必要なドキュメントを読み込む：
-  - `docs/project/design/01-tech-stack.md`
-  - `docs/project/design/05-data-model.md`
-  - `docs/project/design/03-screen-design.md`
-
-- ドキュメントが不足している場合、対応するワークフローの実行を促す。
-
-### 2. テンプレートの準備
-
-- テンプレートをコピーして作業用ファイルを作成する：
-
-  ```bash
-  SCRIPT_DIR=$(for d in .agent .cursor .claude .codex; do [ -d "$d" ] && echo "$d" && break; done)
-  cp "$SCRIPT_DIR/templates/project/04-design/06-api-spec.md" "docs/project/design/06-api-spec.md"
-  ```
-
-### 3. APIスタイルの確認と提案
-
-- 技術スタック（01-tech-stack.md）で選定されたAPIスタイル（REST, GraphQL等）を確認する。
-- データモデル（05-data-model.md）と画面設計（03-screen-design.md）から、必要なリソースと操作を抽出する。
-- **エンドポイント案の提示**:
-  - 「以下のリソースに対するエンドポイントを定義します：」
-  - 「Users: 一覧, 詳細, 作成, 更新, 削除」
-  - 「Auth: ログイン, 登録, リフレッシュ」
-
-### 4. 詳細定義（インタビュー）
-
-ユーザーからのフィードバックを受け、詳細を定義する。
-
-#### 4.1 認証・認可
-
-- 認証方式（JWT, OAuth等）、トークンの扱い（Cookie vs Header）
-- 認可スコープやロールの定義
-
-#### 4.2 エンドポイント詳細
-
-- 各リソースのパス設計（RESTful原則の適用）
-- 認証の要否（Public vs Private）
-- CRUD以外の特殊なアクション（`/cancel`, `/publish` 等）
-
-#### 4.3 共通レスポンス形式
-
-- 成功時のレスポンス構造（`{ data: ... }` ラップの有無）
-- エラー時のレスポンス構造（`{ error: { code, message } }` 等）
-- ページネーションの仕様
-
-### 5. ドキュメント作成
-
-- `docs/project/design/06-api-spec.md` に決定事項を記入する。
-- **必須項目**:
-  - 認証・認可仕様
-  - エンドポイント一覧（リソース別）
-  - 共通レスポンス形式
-
-### 6. 完了条件と構造の確認
-
-- 以下の完了条件を満たしているか、コマンドとチェックリストで確認してください：
-  1. **構造確認**:
-
-     ```bash
-     # 認証セクションの確認
-     grep "## 認証・認可" docs/project/design/06-api-spec.md && echo "OK" || echo "MISSING: Auth section"
-     # エンドポイント一覧の確認
-     grep "## エンドポイント一覧" docs/project/design/06-api-spec.md && echo "OK" || echo "MISSING: Endpoints"
-     # レスポンス形式の確認
-     grep "## 共通レスポンス形式" docs/project/design/06-api-spec.md && echo "OK" || echo "MISSING: Response format"
-     ```
-
-  2. **チェックリスト**:
-     - [ ] `docs/project/design/06-api-spec.md` が作成されている
-     - [ ] 認証方式が明確に定義されている
-     - [ ] 主要なリソースのCRUDエンドポイントが網羅されている
-
-### 7. Git への追加（オプション）
-
-- ユーザーに確認：「作成したAPI仕様ドキュメントを Git に追加しますか？」
-- 「はい」の場合、以下を実行：
-
-  ```bash
-  git add docs/project/design/06-api-spec.md
-  git status
-  ```
-
-- 推奨コミットメッセージ：
-
-  ```
-  docs: API仕様（基本設計）の作成
-
-  - 認証・認可方式の定義
-  - エンドポイント一覧と共通レスポンス形式を定義
-  ```
-
-## 完了条件
-
-- `docs/project/design/06-api-spec.md` が作成されている。
-- 認証・認可の仕組みが定義されている。
-- エンドポイント一覧（メソッド、パス、認証要否）が定義されている。
-- 共通レスポンス形式（成功/エラー）が定義されている。
-- ユーザーが内容を承認している。
-
-## エスカレーション
-
-- APIスタイル（REST/GraphQL）が未定の場合：
-  - 「APIスタイルが未定です。`DefineTechStack` (a-007) に戻って選定してください。」
-- データモデルとの不整合がある場合：
-  - 「データモデルに存在しないリソースのエンドポイントが要求されています。データモデルを見直すか、APIだけの概念として定義するか確認してください。」
+---
+name: a-012-define-api-spec
+description: データモデルと画面設計から API 仕様（認証方式・エンドポイント一覧・共通レスポンス形式）を定義する。データモデル確定後、フロント/バック間のインターフェースを固める際に使用。
+disable-model-invocation: true
+allowed-tools: Read, Write, Edit, Bash, Grep, Glob
+---
+
+# DefineAPISpec (a-012)
+
+## 目的
+
+- データモデルと画面設計を基に、API 仕様の基本設計を定義する。
+- API 設計スタイル（REST、GraphQL、gRPC、tRPC）を決定する。
+- 認証・認可方式を明確化する。
+- エンドポイント一覧（メソッド、パス、説明、認証要否）を定義する。
+- 共通レスポンス形式（成功/エラー）を定義する。
+
+## 前提
+
+- `docs/project/design/01-tech-stack.md` が作成されていること（API スタイル選定済み）。
+- `docs/project/design/05-data-model.md` が作成されていること。
+- `docs/project/design/03-screen-design.md` が作成されていること。
+- `docs/project/design/` ディレクトリが存在すること。
+
+## 手順
+
+### 1. ドキュメントと前提条件の確認
+
+以下を読み込む:
+
+- `docs/project/design/01-tech-stack.md`
+- `docs/project/design/05-data-model.md`
+- `docs/project/design/03-screen-design.md`
+
+不足があれば対応スキルの実行を促す。
+
+### 2. テンプレートの準備
+
+```bash
+SCRIPT_DIR=$(for d in .agent .cursor .claude .codex; do [ -d "$d" ] && echo "$d" && break; done)
+cp "$SCRIPT_DIR/templates/project/04-design/06-api-spec.md" "docs/project/design/06-api-spec.md"
+```
+
+### 3. API スタイルの確認と提案
+
+技術スタックで選定された API スタイル（REST, GraphQL 等）を確認し、データモデルと画面設計から必要なリソースと操作を抽出する。スタイル別の特徴は [examples/api-templates.md](examples/api-templates.md#api-スタイル別の特徴) を参照。
+
+- 「Users: 一覧, 詳細, 作成, 更新, 削除」
+- 「Auth: ログイン, 登録, リフレッシュ」
+
+### 4. 詳細定義（インタビュー）
+
+#### 4.1 認証・認可
+
+認証方式（JWT / OAuth 等）、トークンの保存先（Cookie vs Header）、ロール・スコープ定義。テンプレートは [examples/api-templates.md](examples/api-templates.md#認証認可仕様のテンプレート) を参照。
+
+#### 4.2 エンドポイント詳細
+
+各リソースのパス設計（RESTful 原則）、認証の要否、特殊アクション（`/cancel`, `/publish` 等）。一覧テーブルとパス設計原則は [examples/api-templates.md](examples/api-templates.md#エンドポイント一覧テーブル) を参照。
+
+#### 4.3 共通レスポンス形式
+
+成功・エラー構造、ページネーション、エラーコード体系。JSON サンプルは [examples/api-templates.md](examples/api-templates.md#共通レスポンス形式) を参照。
+
+### 5. ドキュメント作成
+
+`docs/project/design/06-api-spec.md` に以下を記入する:
+
+- 認証・認可仕様
+- エンドポイント一覧（リソース別）
+- 共通レスポンス形式
+- エラーコード体系
+
+### 6. 構造チェック
+
+```bash
+grep "## 認証・認可" docs/project/design/06-api-spec.md \
+  && grep "## エンドポイント一覧" docs/project/design/06-api-spec.md \
+  && grep "## 共通レスポンス形式" docs/project/design/06-api-spec.md \
+  && echo "OK" || echo "MISSING SECTION"
+```
+
+詳細チェックリストは [reference/structure-check.md](reference/structure-check.md#チェックリスト) を参照。
+
+### 7. Git への追加（任意）
+
+```bash
+git add docs/project/design/06-api-spec.md
+git commit -m "docs: API 仕様（基本設計）の作成"
+```
+
+## 完了条件
+
+- `docs/project/design/06-api-spec.md` が作成されている。
+- 認証・認可の仕組みが定義されている。
+- エンドポイント一覧（メソッド、パス、認証要否）が定義されている。
+- 共通レスポンス形式（成功/エラー）が定義されている。
+- ユーザーが内容を承認している。
+
+## エスカレーション
+
+- **API スタイルが未定**: 「`/a-007-define-tech-stack` に戻って選定してください。」
+- **データモデルとの不整合**: 「データモデルに存在しないリソースのエンドポイントが要求されています。データモデルを見直すか、API だけの概念として定義するか確認してください。」
+
+## 参考
+
+- [examples/api-templates.md](examples/api-templates.md) — API スタイル比較、認証・認可テンプレート、エンドポイント一覧、共通レスポンス、エラーコード体系
+- [reference/structure-check.md](reference/structure-check.md) — 構造確認コマンド、チェックリスト、レビュー質問、Git 追加例

package/skills/a-012-define-api-spec/examples/api-templates.md

@@ -0,0 +1,117 @@
+# API 仕様のテンプレート
+
+SKILL.md 手順3〜5 で使用するエンドポイント・認証・共通レスポンスのサンプル。
+
+## API スタイル別の特徴
+
+| スタイル | 特徴 | 適合シーン |
+|:--|:--|:--|
+| REST | シンプル、キャッシュ活用、HTTP 標準 | CRUD 中心の Web/モバイル API |
+| GraphQL | クライアント駆動、過剰取得回避 | 複雑な集約、多様なクライアント |
+| gRPC | 高速、強い型、ストリーム | 内部 Microservice 通信 |
+| tRPC | TS で型共有、開発高速 | TypeScript フルスタック |
+
+## 認証・認可仕様のテンプレート
+
+```markdown
+### 認証方式
+
+- プロトコル: JWT（HS256）
+- トークン種別: Access Token（15 分）+ Refresh Token（14 日）
+- 保存先: Access = Memory, Refresh = HttpOnly Secure Cookie
+- ログインエンドポイント: `POST /api/auth/login`
+- リフレッシュ: `POST /api/auth/refresh`
+
+### 認可
+
+- ロール: `admin`, `staff`, `user`
+- スコープ: `orders:read`, `orders:write`, `users:admin`
+- Guard 方針: ロール + 所有者確認（例: `/orders/:id` は本人 or admin のみ）
+```
+
+## エンドポイント一覧テーブル
+
+| メソッド | パス | 説明 | 認証 | 認可 |
+|:--|:--|:--|:--|:--|
+| POST | `/api/auth/login` | ログイン | 不要 | - |
+| POST | `/api/auth/refresh` | トークン更新 | Refresh | - |
+| POST | `/api/auth/logout` | ログアウト | Access | - |
+| GET | `/api/users/me` | 自身のプロフィール取得 | Access | user |
+| GET | `/api/users` | ユーザー一覧 | Access | admin |
+| GET | `/api/orders` | 注文一覧 | Access | user（自分の注文） |
+| POST | `/api/orders` | 注文作成 | Access | user |
+| GET | `/api/orders/:id` | 注文詳細 | Access | 本人 or admin |
+| POST | `/api/orders/:id/cancel` | 注文取消 | Access | 本人 or admin |
+
+### RESTful パス設計の原則
+
+- リソースは複数形の名詞（`/users`, `/orders`）
+- 動作は HTTP メソッドで表現（GET / POST / PATCH / DELETE）
+- 動詞が必要な特殊アクションは `/resource/:id/action` 形式（`/orders/:id/cancel`）
+
+## 共通レスポンス形式
+
+### 成功レスポンス
+
+```json
+{
+  "data": {
+    "id": "ord_01HXXXXX",
+    "status": "confirmed",
+    "total": 12800
+  },
+  "meta": {
+    "requestId": "req_01HXXXXX"
+  }
+}
+```
+
+### エラーレスポンス
+
+```json
+{
+  "error": {
+    "code": "VALIDATION_ERROR",
+    "message": "入力値に誤りがあります",
+    "details": [
+      { "field": "email", "message": "メール形式が不正です" }
+    ]
+  },
+  "meta": {
+    "requestId": "req_01HXXXXX"
+  }
+}
+```
+
+### ページネーション（Cursor 方式）
+
+```json
+{
+  "data": [ { "id": "ord_01" }, { "id": "ord_02" } ],
+  "pageInfo": {
+    "hasNextPage": true,
+    "endCursor": "eyJpZCI6Im9yZF8wMiJ9"
+  }
+}
+```
+
+## エラーコード体系の例
+
+| HTTP | code | 用途 |
+|:--|:--|:--|
+| 400 | VALIDATION_ERROR | 入力値不正 |
+| 401 | UNAUTHENTICATED | 未認証 |
+| 403 | FORBIDDEN | 権限不足 |
+| 404 | NOT_FOUND | リソース未存在 |
+| 409 | CONFLICT | 競合（重複登録等） |
+| 429 | RATE_LIMITED | レート制限 |
+| 500 | INTERNAL_ERROR | サーバー内部エラー |
+
+## コミットメッセージ例
+
+```text
+docs: API 仕様（基本設計）の作成
+
+- 認証・認可方式の定義
+- エンドポイント一覧と共通レスポンス形式を定義
+```

package/skills/a-012-define-api-spec/reference/structure-check.md

@@ -0,0 +1,49 @@
+# 構造チェックとレビュー観点
+
+SKILL.md 手順6〜7 で使う確認コマンドとレビュー観点。
+
+## セクション存在確認
+
+```bash
+# 認証セクションの確認
+grep "## 認証・認可" docs/project/design/06-api-spec.md && echo "OK" || echo "MISSING: Auth section"
+# エンドポイント一覧の確認
+grep "## エンドポイント一覧" docs/project/design/06-api-spec.md && echo "OK" || echo "MISSING: Endpoints"
+# レスポンス形式の確認
+grep "## 共通レスポンス形式" docs/project/design/06-api-spec.md && echo "OK" || echo "MISSING: Response format"
+```
+
+## チェックリスト
+
+- [ ] `docs/project/design/06-api-spec.md` が作成されている
+- [ ] 認証方式（JWT / OAuth 等）が明確に定義されている
+- [ ] トークンの保存先（Cookie / Header）が決まっている
+- [ ] ロール・スコープが定義されている
+- [ ] 主要リソースの CRUD エンドポイントが網羅されている
+- [ ] 特殊アクション（cancel, publish 等）が適切な命名で定義されている
+- [ ] 成功時・エラー時の共通レスポンス形式が定義されている
+- [ ] ページネーション方式（Offset / Cursor）が決まっている
+- [ ] エラーコード体系が定義されている
+
+## レビュー確認質問
+
+- 「データモデルのエンティティすべてに必要な API が揃っていますか？」
+- 「画面設計で必要なデータ取得に対応するエンドポイントはありますか？」
+- 「認証・認可のフローにセキュリティリスクはありませんか？」
+- 「エラー応答のフォーマットはクライアントで扱いやすいですか？」
+
+## Git への追加（任意）
+
+```bash
+git add docs/project/design/06-api-spec.md
+git status
+```
+
+推奨コミットメッセージ:
+
+```text
+docs: API 仕様（基本設計）の作成
+
+- 認証・認可方式の定義
+- エンドポイント一覧と共通レスポンス形式を定義
+```

package/skills/a-013-define-architecture/SKILL.md

@@ -1,128 +1,101 @@
----
-name: a-013-define-architecture
-description: 技術スタック、リポジトリ構造、データモデル、API仕様を統合し、システム全体のアーキテクチャ設計とADRを定義するワークフロー
----
-
-# DefineArchitecture (a-013)
-
-## 目的
-
-- これまでに定義された設計（技術スタック、リポジトリ構造、データモデル、API仕様）を統合する。
-- システム全体の構造をMermaid図で視覚化する。
-- 採用したアーキテクチャパターン（レイヤード、クリーンアーキテクチャなど）を明確化する。
-- 重要なアーキテクチャ決定（ADR: Architecture Decision Record）を記録する。
-
-## 前提
-
-- `docs/project/design/01-tech-stack.md` が作成されていること。
-- `docs/project/design/02-repository-structure.md` が作成されていること。
-- `docs/project/design/05-data-model.md` が作成されていること。
-- `docs/project/design/06-api-spec.md` が作成されていること。
-- `docs/project/design/` ディレクトリが存在すること。
-
-## 手順
-
-### 1. ドキュメントと前提条件の確認
-
-- 必要なドキュメントを読み込む：
-  - `docs/project/design/01-tech-stack.md`
-  - `docs/project/design/02-repository-structure.md`
-  - `docs/project/design/05-data-model.md`
-  - `docs/project/design/06-api-spec.md`
-
-- ドキュメントが不足している場合、対応するワークフローの実行を促す。
-
-### 2. テンプレートの準備
-
-- テンプレートをコピーして作業用ファイルを作成する：
-
-  ```bash
-  SCRIPT_DIR=$(for d in .agent .cursor .claude .codex; do [ -d "$d" ] && echo "$d" && break; done)
-  cp "$SCRIPT_DIR/templates/project/04-design/07-architecture.md" "docs/project/design/07-architecture.md"
-  ```
-
-### 3. アーキテクチャの提案
-
-- 技術スタックとリポジトリ構造から、システムの主要コンポーネント（クライアント、API、DB、外部サービス）を抽出する。
-- **システム全体図の構成案を提示**:
-  - 「以下のコンポーネントとデータフローを図示します：」
-  - 「[Web] -> [API Server] -> [DB]」
-  - 「[API Server] -> [External Service]」
-
-### 4. 詳細定義（インタビュー）
-
-ユーザーからのフィードバックを受け、詳細を定義する。
-
-#### 4.1 システムアーキテクチャ図
-
-- コンポーネント間の接続、プロトコル（HTTP/gRPC）、データフローをMermaid図で表現する。
-- スケーラビリティや冗長化構成（ロードバランサー、レプリカDB）を反映する。
-
-#### 4.2 アーキテクチャパターン
-
-- 採用したパターン（レイヤード、クリーン、マイクロサービス等）とその選定理由を明確にする。
-
-#### 4.3 ADR (Architecture Decision Records)
-
-- 重要な技術的決定（DB選定、認証方式、フレームワーク選定など）を抽出する。
-- 各決定について、背景・代替案・決定理由・影響を記録する。
-
-### 5. ドキュメント作成
-
-- `docs/project/design/07-architecture.md` に決定事項を記入する。
-- **必須項目**:
-  - システムアーキテクチャ図 (Mermaid)
-  - 採用アーキテクチャパターンの説明
-  - ADR一覧
-
-### 6. 完了条件と構造の確認
-
-- 以下の完了条件を満たしているか、コマンドとチェックリストで確認してください：
-  1. **構造確認**:
-
-     ```bash
-     # アーキテクチャ図の確認
-     grep "\`\`\`mermaid" docs/project/design/07-architecture.md && echo "OK" || echo "MISSING: Architecture Diagram"
-     # パターン定義の確認
-     grep "## 採用アーキテクチャパターン" docs/project/design/07-architecture.md && echo "OK" || echo "MISSING: Pattern definition"
-     # ADRセクションの確認
-     grep "## ADR" docs/project/design/07-architecture.md && echo "OK" || echo "MISSING: ADR section"
-     ```
-
-  2. **チェックリスト**:
-     - [ ] `docs/project/design/07-architecture.md` が作成されている
-     - [ ] システム全体像が視覚化されている
-     - [ ] 重要な技術選定の理由（ADR）が記録されている
-
-### 7. Git への追加（オプション）
-
-- ユーザーに確認：「作成したアーキテクチャ設計ドキュメントを Git に追加しますか？」
-- 「はい」の場合、以下を実行：
-
-  ```bash
-  git add docs/project/design/07-architecture.md
-  git status
-  ```
-
-- 推奨コミットメッセージ：
-
-  ```
-  docs: アーキテクチャ設計の定義
-
-  - システム全体図（Mermaid）の作成
-  - アーキテクチャパターンとADRの記録
-  ```
-
-## 完了条件
-
-- `docs/project/design/07-architecture.md` が作成されている。
-- システム全体の構成要素と関係性が可視化されている。
-- 技術選定の背景（ADR）が文書化され、将来の参照用に残されている。
-- ユーザーが内容を承認している。
-
-## エスカレーション
-
-- アーキテクチャが複雑すぎる場合：
-  - 「コンポーネント数が多すぎます。概要図と詳細図に分割するか、主要なフローに絞って図示することを検討しましょう。」と提案する。
-- 決定理由が不明確な場合：
-  - 「[技術名]の選定理由が曖昧です。後で振り返れるよう、比較検討した代替案も含めてADRに記録しましょう。」と促す。
+---
+name: a-013-define-architecture
+description: 技術スタック・リポジトリ構造・データモデル・API 仕様を統合し、システムアーキテクチャと ADR を定義する。各設計ドキュメント確定後、全体像と意思決定を文書化する際に使用。
+disable-model-invocation: true
+allowed-tools: Read, Write, Edit, Bash, Grep, Glob
+---
+
+# DefineArchitecture (a-013)
+
+## 目的
+
+- これまでに定義された設計（技術スタック、リポジトリ構造、データモデル、API 仕様）を統合する。
+- システム全体の構造を Mermaid 図で視覚化する。
+- 採用したアーキテクチャパターン（レイヤード、クリーンアーキテクチャなど）を明確化する。
+- 重要なアーキテクチャ決定（ADR: Architecture Decision Record）を記録する。
+
+## 前提
+
+- 以下が作成されていること:
+  - `docs/project/design/01-tech-stack.md`
+  - `docs/project/design/02-repository-structure.md`
+  - `docs/project/design/05-data-model.md`
+  - `docs/project/design/06-api-spec.md`
+- `docs/project/design/` ディレクトリが存在すること。
+
+## 手順
+
+### 1. ドキュメントと前提条件の確認
+
+上記 4 ドキュメントを読み込む。不足があれば対応スキル（`/a-007`, `/a-008`, `/a-011`, `/a-012`）の実行を促す。
+
+### 2. テンプレートの準備
+
+```bash
+SCRIPT_DIR=$(for d in .agent .cursor .claude .codex; do [ -d "$d" ] && echo "$d" && break; done)
+cp "$SCRIPT_DIR/templates/project/04-design/07-architecture.md" "docs/project/design/07-architecture.md"
+```
+
+### 3. アーキテクチャの提案
+
+技術スタックとリポジトリ構造からシステムの主要コンポーネント（クライアント、API、DB、外部サービス）を抽出し、全体図の構成案を提示する。
+
+- 「[Web] -> [API Server] -> [DB]」
+- 「[API Server] -> [External Service]」
+
+### 4. 詳細定義（インタビュー）
+
+#### 4.1 システムアーキテクチャ図
+
+コンポーネント間の接続、プロトコル（HTTP/gRPC）、データフロー、スケーラビリティ構成（LB、Replica）を Mermaid 図で表現する。記述例は [examples/architecture-templates.md](examples/architecture-templates.md#システムアーキテクチャ図mermaid) を参照。
+
+#### 4.2 アーキテクチャパターン
+
+採用パターン（レイヤード、クリーン、マイクロサービス等）と選定理由を明確にする。選定ガイドは [examples/architecture-templates.md](examples/architecture-templates.md#アーキテクチャパターン選定ガイド) を参照。
+
+#### 4.3 ADR (Architecture Decision Records)
+
+重要な技術的決定（DB 選定、認証方式、フレームワーク選定など）を背景・代替案・決定理由・影響の形で記録する。テンプレートは [examples/architecture-templates.md](examples/architecture-templates.md#adrarchitecture-decision-recordテンプレート) を参照。ADR 記録の基準は [reference/structure-check.md](reference/structure-check.md#adr-記録の基準) を参照。
+
+### 5. ドキュメント作成
+
+`docs/project/design/07-architecture.md` に以下を記入する:
+
+- システムアーキテクチャ図（Mermaid）
+- 採用アーキテクチャパターンの説明
+- ADR 一覧
+
+### 6. 構造チェック
+
+```bash
+grep "\`\`\`mermaid" docs/project/design/07-architecture.md \
+  && grep "## 採用アーキテクチャパターン" docs/project/design/07-architecture.md \
+  && grep "## ADR" docs/project/design/07-architecture.md \
+  && echo "OK" || echo "MISSING SECTION"
+```
+
+詳細チェックリストは [reference/structure-check.md](reference/structure-check.md#チェックリスト) を参照。
+
+### 7. Git への追加（任意）
+
+```bash
+git add docs/project/design/07-architecture.md
+git commit -m "docs: アーキテクチャ設計の定義"
+```
+
+## 完了条件
+
+- `docs/project/design/07-architecture.md` が作成されている。
+- システム全体の構成要素と関係性が可視化されている。
+- 技術選定の背景（ADR）が文書化され、将来の参照用に残されている。
+- ユーザーが内容を承認している。
+
+## エスカレーション
+
+- **アーキテクチャが複雑すぎる**: 「コンポーネント数が多すぎます。概要図と詳細図に分割するか、主要フローに絞って図示することを検討しましょう。」
+- **決定理由が不明確**: 「[技術名] の選定理由が曖昧です。後で振り返れるよう、比較検討した代替案も含めて ADR に記録しましょう。」
+
+## 参考
+
+- [examples/architecture-templates.md](examples/architecture-templates.md) — システム全体図、冗長化構成、パターン選定ガイド、ADR テンプレート、ADR の典型例
+- [reference/structure-check.md](reference/structure-check.md) — 構造確認コマンド、チェックリスト、レビュー質問、ADR 記録基準