update-design

---

name: update-design description: 指定したIssueを元に設計書を自律的に更新する仕様駆動開発サポートコマンド。Issue番号を引数で指定可能（例: /update-design 15） argument-hint: <Issue番号>

Issue番号: $ARGUMENTS

GitHub Issueの内容を解析し、該当する docs/design/ 配下の設計書を自律的に更新してください。 更新後のレビューは /doc-review と人間が実施するため、対話的な確認は最小限にし自律的に作業を完了してください。 完了したタスクは gh issue edit コマンドでGitHub Issueのチェックリストを更新してください。

---

設計書更新の詳細手順

GitHub Issueの内容を解析し、設計書を自律的に更新する。 仕様駆動開発フローの「4. 設計書更新」ステップを支援する。

実行プロセス

Phase 1: Issue読み込みと解析

1-1: Issue番号の取得

引数にIssue番号が含まれる場合はそれを使用する。 含まれない場合のみ、AskUserQuestion で1回だけ確認する。

1-2: GitHub IssueのJSON取得

Bash ツールで GitHub Issue の情報を取得:

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 内容から対象設計書を自動特定する（ユーザー確認なし）。

ラベルマッピング:

ラベル	設計書
backend	backend-design.md
frontend	frontend-design.md
infra, cdk	infrastructure-design.md
test	test-policy.md

Issue内の docs/design/{filename}.md 言及や「対象ファイル」セクションがあれば優先する。

候補が検出できない場合（docs ラベルのみ等）は、AskUserQuestion で1回だけ確認する。

Phase 3: 設計書構造の解析と更新内容の決定

各対象設計書を Read で読み込み、Issueの内容から更新箇所と内容を自律的に判断する。

• 明示的な指示があればそれに従う
• 指示がない場合は、Issue のタイトル・スコープ・作業項目から合理的に推測して決定する
• 既存セクションの修正か新規セクション追加かも自律的に判断する

Phase 4: 設計書の更新実行

Edit ツールを優先して使用し、変更が必要な箇所のみ差分編集する。 ファイル新規作成が必要な場合のみ Write ツールを使用する。

更新時の注意:

• 設計書の既存構造（セクション番号・見出しレベル）を維持する
• コードブロック（```）の開閉を確認する
• ADRファイル（docs/adr/）は更新対象外
• 更新履歴セクションは追加しない（gitで管理）

Phase 4.5: 修正確認（変更漏れ検証）

Phase 2 で特定した対象設計書が実際に変更されているか Bash で確認する:

git diff --name-only

確認ルール:

• Phase 2 で特定した設計書が git diff --name-only に含まれているか検証する
• 含まれていない場合は、その設計書の更新が漏れている可能性があるため、 Issue の指示を再確認して再度 Edit/Write で更新し、再検証する
• 再更新後も変更が検出されない場合は AskUserQuestion でユーザーに確認する

Phase 4.7: テストコードの枠生成

「テストコードは設計書」 という考えに基づき、設計書の変更内容からテストコードの枠（空の it() ブロック）を生成する。

実行条件

バックエンドまたはフロントエンドの設計書が更新された場合のみ実行する。 git diff --name-only の結果に以下のいずれかが含まれる場合が対象:

• backend-design.md
• backend-api-specification.md
• backend-flow.md
• frontend-design.md

infrastructure-design.md や test-policy.md のみの更新時はスキップする。

処理手順

1. 更新された設計書を Read で読み込み、テスト対象のハンドラー/コンポーネントを特定する
2. docs/design/test-policy.md を Read で読み込み、テスト方針を確認する
3. テスト対象ごとに、設計書の仕様（正常系パス、エラーケース、バリデーション等）からテストケースを洗い出す
4. テストファイルを生成する（既存ファイルがある場合は Edit で追記）

生成ルール

• describe / it の構造のみ生成し、テスト本体は空にする
• テストケース名は日本語で記述する（test-policy.md セクション2.5準拠）
• 正常系と異常系は describe ブロックで分離する
• ファイル配置:
  • バックエンド: backend/src/handlers/__tests__/{ハンドラー名}.test.ts
  • フロントエンド: 各コンポーネントと同階層の __tests__/{コンポーネント名}.test.tsx
• import は vitest の describe, it のみ（expect 等は実装時に追加）

生成例

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. docs/design/test-policy.md のテスト対象判断基準（セクション2.8）に基づき過不足をチェックする
4. 不足があればテストケースを Edit で追加、不要なものがあれば削除する

チェック観点

• 網羅性: 設計書に記載された正常系パスすべてにテストケースがあるか
• 異常系: エラーケース・バリデーションルールにテストケースがあるか
• 除外確認: テスト仕様書2.8の「テスト対象としないもの」に該当するケースが含まれていないか（privateメソッド、単純な委譲、診断ログ等）
• 分離基準: テストケースの分離基準（セクション2.5）に従っているか（仕様上の条件が異なるケースが適切に分離されているか）
• 命名: テストケース名がメソッド名を含まず、振る舞いを示す日本語で記述されているか

修正後の確認

修正を行った場合は、修正内容（追加/削除したテストケース）を記録し、Phase 5 の報告に含める。

Phase 5: GitHub Issueの更新と結果報告

ステップ 5-1: GitHub Issueのタスクチェックリスト更新

Phase 1-3 で抽出したタスク一覧から、設計書更新に関連するタスクを特定し、 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）
- 充足性チェック結果: {追加/削除したテストケースがあればその内容、なければ「問題なし」}
  または「対象なし（インフラ設計書のみの更新）」

GitHub Issue更新:
- Issue #{番号} のタスクチェックリストを更新しました

Next Actions:
1. /doc-review で設計書の整合性をチェック（推奨）
2. 人間による設計書レビュー（CLAUDE.md 開発フロー Step 5）
3. レビュー完了後、/dev で実装開始（テストの枠が生成済み）

制約事項

• ADRファイル（docs/adr/）は更新対象外
• 設計書の大幅な構造変更（セクション順序の入れ替え・番号の大規模振り直し）は手動推奨