update-design

Issue番号: $ARGUMENTS GitHub Issueの内容を解析し、該当する設計書（設計ハブ `docs/design-hub.md` から辿れるもの）を自律的に更新してください。 更新後のレビューは `/doc-review` と人間が実施するため、対話的な確認は最小限にし自律的に作業を完了してください。 完了したタスクは `gh issue edit` コマンドでGitHub Issueのチェックリストを更新してください。 --- ## 設計書更新の詳細手順 GitHub Issueの内容を解析し、設計書を自律的に更新する。 仕様駆動開発フローの「設計書更新」工程を支援する。 ## 実行プロセス ### Phase 1: Issue読み込みと解析 #### 1-1: Issue番号の取得 引数にIssue番号が含まれる場合はそれを使用する。 含まれない場合のみ、AskUserQuestion で1回だけ確認する。 #### 1-2: GitHub IssueのJSON取得 Bash ツールで GitHub Issue の情報を取得: ```bash gh issue view {番号} --json number,title,body,labels ``` **エラーハンドリング**: - Issue が見つからない場合 → エラーを表示して中止 #### 1-3: Issue内容の解析 取得したJSONから以下の情報を抽出する: - Issue番号: `.number` フィールド - タイトル: `.title` フィールド - ラベル: `.labels[].name` フィールド - スコープ/作業項目: body内 `## スコープ / 作業項目` セクション全文 - タスク一覧: body内 `## タスク一覧` セクションのチェックリスト（`- [ ]` 形式） - 設計書への明示的な指示: body内の設計書パス言及（例: `docs/design/{filename}.md`） ### Phase 2: 対象設計書の特定 ラベルと Issue 内容から対象設計書を**自動特定**する（ユーザー確認なし）。 **特定ロジック:** 1. Issue内の設計書パスの明示的な言及や「対象ファイル」セクションがあれば最優先で採用する 2. 明示的な言及がなければ、設計ハブ `docs/design-hub.md` を Read し、リンクされている個別設計書の一覧と概要を取得する。各設計書の概要と、Issueのラベル・タイトル・スコープを照合し、最も関連する設計書を選ぶ 3. 設計ハブが未作成、または対応する設計書が見つからない場合（新規領域でまだ設計書が存在しない等）は、AskUserQuestion で対象設計書（既存のどれか、または新規作成）を1回だけ確認する ### Phase 3: 設計書構造の解析と更新内容の決定 各対象設計書を Read で読み込み、Issueの内容から更新箇所と内容を**自律的に判断**する。 - 明示的な指示があればそれに従う - 指示がない場合は、Issue のタイトル・スコープ・作業項目から合理的に推測して決定する - 既存セクションの修正か新規セクション追加かも自律的に判断する ### Phase 4: 設計書の更新実行 **Edit ツールを優先して使用**し、変更が必要な箇所のみ差分編集する。 ファイル新規作成が必要な場合のみ Write ツールを使用する。 設計書を新規に書き起こす前に `samples/docs/design/` を Read する（構成・図の粒度・表の書きぶりの手本）。`samples/` 自体は変更しない。 **構成は基本方針・構成図の2本柱にする**（`docs/policy/design-doc-policy.md`）。新規作成時はこの2つを柱に置き、個々の設計判断は中身を名指しした `##` セクションに立てる。 - **基本方針**：冒頭にこの設計が取る考え方を1文で言い切り、続けてその考え方から出てくる方針を箇条書きで並べる（表にしない。理由は添えず冒頭の1文が兼ねる）。設計の対象が2領域にまたがるなら `###` の小節（見出しはその方針の名前）に分け、1組ずつ置く。TL;DR は置かない（基本方針が兼ねる） - **構成図**：コードから再構築するしかないもの（構成・関係・流れ）を描く。ノードには実装の固有名詞（ジョブ名・リソース名・クラス名）を書く。作図は `/design-doc-mermaid` - **個々の判断**：その判断の**中身を見出しにした `##` セクション**を1つ立てる（例：`## CI実施内容一覧`・`## 命名規約`）。「重要なポイント」のような中身を名指ししない傘セクションは作らない。1セクション1決定。書くのは構成図に描かれていない内訳（実行条件の一覧・失敗時の分岐・状態の遷移・環境ごとの差）で、図の描き直しとコードの書き写しは書かない。同じ対象の列挙を他のセクションと重ねない 書かないもの：却下案（ADR 対象の判断で、なぜBでなくAか）は ADR へ出しリンクする。まだ実装されていないものは書かない（予定は Issue に置く）。コードを読めば分かることは書かない（一覧できず集約に価値がある場合のみ、概要を表に置く）。 **更新時の注意:** - 設計書の既存構造（セクション番号・見出しレベル）を維持する - コードブロック（` ``` `）の開閉を確認する - ADRファイル（`docs/adr/`）は更新対象外 - 更新履歴セクションは追加しない（gitで管理） ### Phase 4.7: テストコードの枠生成 **「テストコードは設計書」** という考えに基づき、設計書の変更内容からテストコードの枠（空の `it()` ブロック）を生成する。 #### 実行条件 更新された設計書が**アプリケーションコード（Lambda・API・UIコンポーネント等）の仕様**を含む場合のみ実行する。CDK/インフラ構成のみを記す設計書（AWSリソース定義が中心で、関数・コンポーネント単位の振る舞い仕様を含まないもの）の更新時はスキップする。 判定に迷う場合は、更新された設計書に「関数・ハンドラー・コンポーネント名」と「入出力仕様（正常系/異常系）」が具体的に記述されているかを確認する。含まれていれば対象とする。 #### 処理手順 1. 更新された設計書を Read で読み込み、テスト対象のハンドラー/コンポーネントを特定する 2. ポリシーハブ `docs/policy-hub.md` を Read してテスト方針を定めるポリシー（例: `unit-test-policy.md`）を探し、Read で読み込んでテスト方針を確認する 3. テスト対象ごとに、設計書の仕様（正常系パス、エラーケース、バリデーション等）からテストケースを洗い出す 4. テストファイルを生成する（既存ファイルがある場合は Edit で追記） #### 生成ルール - `describe` / `it` の構造のみ生成し、テスト本体は**空**にする - テストケース名は**日本語**で記述する（テスト方針ポリシーの命名規則に準拠） - 正常系と異常系は `describe` ブロックで分離する - **ファイル配置**：既存のテストファイル（`**/*.test.ts`, `**/*.test.tsx` 等）を Glob で探し、実装ファイルとの相対配置（同階層 or `__tests__/` サブディレクトリ等）を模倣する。既存テストが1件もない場合は、実装ファイルと同階層への配置をデフォルトとする - import は検出したテストフレームワーク（`vitest` / `jest` 等。`package.json` の依存関係から判定）の `describe`, `it` のみ（`expect` 等は実装時に追加） #### 生成例 ```typescript import { describe, it } from 'vitest' describe('認可エンドポイント', () => { describe('正常系', () => { it('有効なリクエストの場合にOIDC認可URLへリダイレクトする', async () => {}) it('state・nonce・PKCEパラメータが正しく生成される', async () => {}) }) describe('異常系', () => { it('必須パラメータが欠落している場合に400を返す', async () => {}) it('不正なclient_idの場合に400を返す', async () => {}) }) }) ``` ### Phase 4.8: テストケース充足性チェック Phase 4.7 で生成/更新したテストケースが設計書の仕様を十分にカバーしているか検証し、過不足があれば修正する。 #### 処理手順 1. Phase 4.7 で生成/更新したテストファイルを Read で読み込む 2. 更新された設計書の仕様（API仕様、画面仕様、ビジネスロジック等）と照合する 3. Phase 4.7 で特定したテスト方針ポリシーのテスト対象判断基準に基づき過不足をチェックする 4. 不足があればテストケースを Edit で追加、不要なものがあれば削除する #### チェック観点 - **網羅性**: 設計書に記載された正常系パスすべてにテストケースがあるか - **異常系**: エラーケース・バリデーションルールにテストケースがあるか - **除外確認**: テスト方針ポリシーの「テスト対象としないもの」に該当するケースが含まれていないか（privateメソッド、単純な委譲、診断ログ等） - **分離基準**: テスト方針ポリシーのテストケース分離基準に従っているか（仕様上の条件が異なるケースが適切に分離されているか） - **命名**: テストケース名がメソッド名を含まず、振る舞いを示す日本語で記述されているか #### 修正後の確認 修正を行った場合は、修正内容（追加/削除したテストケース）を記録し、Phase 5 の報告に含める。 ### Phase 5: GitHub Issueの更新と結果報告 #### ステップ 5-1: GitHub Issueのタスクチェックリスト更新 Phase 1-3 で抽出したタスク一覧から、設計書更新に関連するタスクを特定し、 Bash ツールで完了マークに更新する: ```bash BODY=$(gh issue view {番号} --json body --jq '.body') # 設計書更新・設計書変更に関連するタスクを完了マークに更新 UPDATED_BODY=$(echo "$BODY" | sed 's/- \[ \] \(.*設計書.*\)/- [x] \1/g') gh issue edit {番号} --body "$UPDATED_BODY" ``` 設計書更新以外のタスク（例: 実装、テスト等）は更新しない。 該当するタスクが見つからない場合はスキップ（エラーにしない）。 #### ステップ 5-2: 更新結果の報告 以下の形式で結果を報告する: ``` === 設計書更新完了 === ✓ Issue #{番号} に基づいて設計書を更新しました 更新されたファイル: - {設計書名}: {更新内容の概要（追加 or 修正したセクションとその内容）} テストコードの枠: - {テストファイルパス}: {生成されたテストケース数}（正常系: X, 異常系: Y） - 充足性チェック結果: {追加/削除したテストケースがあればその内容、なければ「問題なし」} または「対象なし（インフラ設計書・IaC 設計書のみの更新）」 GitHub Issue更新: - Issue #{番号} のタスクチェックリストを更新しました Next Actions: 1. /doc-review で設計書の整合性をチェック（推奨） 2. 人間による設計書レビュー 3. レビュー完了後、/code-dev または /cdk-dev で実装開始（テストの枠が生成済み） ``` ## 制約事項 - ADRファイル（`docs/adr/`）は更新対象外 - 設計書の大幅な構造変更（セクション順序の入れ替え・番号の大規模振り直し）は手動推奨