既存機能のSpec化

本スキルは親 Opus = コード分析・方針・レビュー / spec-writer(Sonnet) = 執筆の分担で進める。

コード分析（フェーズ1〜2）は精度担保のため親が直接実行する。 spec-writer は「親が抽出した情報を文書化するだけ」の役割に限定する。

フェーズ0: 統一基盤の確認

Spec 統一基盤確認 を実施する。

フェーズ1: コード探索（構造把握）

親エージェントが直接実行する。

1. 指定された機能グループに関連するコードを特定
2. 2段階探索 で関連ファイルを全て把握
3. 関連機能の発見: コード探索で見つかった依存関係から、関連する既存Specを特定する
   • 共有モデル・共有APIエンドポイントから関連Specを逆引きする
   • 特定した関連Specは要件定義書の「関連 Spec」セクションに記載し、overview.md の依存関係も更新する
4. 各ファイルの役割・行数・publicメソッド数を一覧化する

フェーズ2: ビジネスロジック深掘り（親エージェント）

構造把握だけでは仕様書にならない。このフェーズでコードの中身を正確に把握する。 Task エージェントに仕様書作成を丸投げしない。ファイル探索の補助には使ってよいが、コードの中身は親が直接読んで把握すること。

全行読み

対象機能のサービスファイルをReadツールで先頭から末尾まで読む。ファイルが大きい場合は500行ずつoffset/limitで分割する。grepで断片的に読んで推測してはならない。

コールチェーン追跡

エントリポイントから末端まで呼び出し先を追跡し、ファイル名:シンボル名を記録する。

processPayment()
  → validateOrder()       order.service.ts:120
  → calculateTotal()      pricing.service.ts:200
    → applyDiscount()     pricing.service.ts:250

共通コンポーネントの洗い出し

コード探索中に、複数機能で再利用されている共通コンポーネントを特定する:

• UIコンポーネント（ボタン、フォーム、モーダル等）
• ユーティリティ関数（バリデーション、フォーマッタ、APIクライアント等）
• カスタムフック（認証、データフェッチ等）
• 認証ガード、ミドルウェア等

各コンポーネントについて以下を記録する:

• コンポーネント名・種別・ファイルパス
• Props/パラメータのシグネチャ
• 利用箇所（どの機能で使われているか）

抽出する情報

各メソッドについて以下を抽出する:

• アルゴリズムの処理順序・分岐条件と分岐先
• 計算式・定数値・バッチサイズ・タイムアウト
• エラー条件・DB検索条件

フェーズ3: 執筆プラン整理（親エージェント）

フェーズ2の分析結果をもとに、spec-writer へ渡す委任プロンプトを組み立てる。

整理する内容:

• REQ-ID採番（REQ-[機能]-[連番] 形式）
• 担当者・ステータス・受入条件（具体的な数値を明記したチェックリスト形式）
• ビジネスロジック（Mermaid図にする分岐条件・コールチェーン）
• 各記述に対応するコード根拠（ファイル名:シンボル名）のリスト
• 共通コンポーネントの活用状況
• 関連Spec（特定済みREQ-IDリスト）
• 生成が必要なドキュメント（要件定義書 / shared-components.md 更新の要否）

フェーズ4: 執筆委任（spec-writer）

Agent(subagent_type: spec-writer) に以下のプロンプトで委任する。

委任プロンプト形式:

あなたは spec-writer です。以下のドキュメントを生成してください。

## 生成対象
docs/requirements/features/[グループ名].md

## 参照テンプレート
（存在する場合）docs/templates/phase1/requirements-spec.md

## 埋める情報
- REQ-ID: [採番値]
- 担当者: [名前 or 未定]
- ステータス: [値]
- 受入条件: [親が整理した条件リスト]
- 関連Spec: [特定済みREQ-IDリスト]
- 活用する共通コンポーネント: [リスト]

## コード根拠リスト（全記述の根拠。独自にgrepして補完しないこと）
[フェーズ2で抽出したコールチェーン・ビジネスルール・DBスキーマ等を根拠付きで列挙]

## ビジネスロジック図（Mermaid）
[フェーズ2で把握した処理フロー・分岐をMermaidフォーマットで渡す]

## 厳守事項
- 渡されたコード根拠リストのみを使う。独自にコードを grep / Read して情報を補完しない
- 根拠（ファイル名:シンボル名）がない記述は書かない
- 要件定義書にはWHAT（何を作るか）だけ記載。HOW（API/DB/画面遷移図）は記載しない
- 不明点は「※ 要確認」マーカーを残し、推測で埋めない
- index系ファイル（overview.md / spec-map.yml / mkdocs.yml / dependency-graph.md）は触らない（親が更新）
- 完了時に軽量セルフチェックを実行し、結果を報告すること

共通コンポーネント設計書の更新が必要な場合は、要件定義書と並列で別委任する:

あなたは spec-writer です。以下の共通コンポーネント設計書を更新してください。

## 生成/更新対象
docs/design/shared-components.md

## 参照テンプレート
（存在する場合）docs/templates/phase2/shared-components.md

## 追加するコンポーネント情報
[フェーズ2で洗い出したコンポーネント一覧（名前・種別・ファイルパス・シグネチャ・利用箇所・コード根拠）]

## 厳守事項
- 渡されたコンポーネント情報のみを記載する。独自に grep して情報を補完しない
- 既存エントリは変更しない。新規コンポーネントの追記のみ行う
- 完了時に軽量セルフチェックを実行し、結果を報告すること

フェーズ5: index系更新（親エージェント）

spec-writer は index 系に触らないため、親が責任を持って更新する:

1. spec-map.yml 操作ガイド に従い、エントリを追加
2. docs/requirements/overview.md の機能一覧・依存関係セクションを更新
3. mkdocs.yml の nav を更新
4. docs/design/dependency-graph.md が存在する場合、新規Specの依存関係を追記
5. 必要に応じて基本設計（architecture.md, db-design.md, screen-flow.md, openapi.yaml）も更新。外部連携がある場合は api-spec.md（外部連携仕様書）も更新

フェーズ6: レビューと整合性チェック（親エージェント）

spec-writer が生成したドキュメントを本体が直接レビューする（Agent委任不可）:

• 要確認マーカーの確認と対応（必要ならコードを再読して補足）
• コード根拠の正確性確認（渡したリストと生成内容の照合）
• 検証チェックリスト:
  • 各セクションに根拠（ファイル名:シンボル名）があるか
  • 推測表現（「〜と思われる」「一般的に〜」）がないか
  • コードに存在しない機能を書いていないか

統一性レビュー（既存Specが1つ以上ある場合）: Spec 統一性レビュー に従い、サブエージェントに横断チェックを実行させる。

• 自動修正可能 → 即座に修正
• 要確認 → ユーザーに選択肢を提示
• 用語統一テーブルがあれば docs/requirements/glossary.md を更新

※ 初回の Spec（他に既存 Spec がない場合）は統一性レビューをスキップする

機械的整合性チェック: Agent(subagent_type: integrity-checker) を起動する。

• 変更ファイルリスト・新規REQ-IDを prompt で渡す
• チェック項目: .claude/skills/_shared/doc-integrity-check.md 参照
• FAIL があれば修正 → 再チェック（最大3ループ）

フェーズ7: コミット（親エージェント）

変更を git add してコミット（探索で見つけた全ファイル一覧をコミットメッセージに記録）。

フェーズ8: 次ステップ提案

次のステップを提案する（例: 「他の機能グループもSpec化しますか？」「detail-design で基本設計書を生成しますか？」）。

---

ルール

• 実装に書いていないことは書かない。 メソッド名や変数名だけで「こういう機能があるはず」と推測するのはNG。例: メソッド名だけ見て「包括的分析ダッシュボード」、行数だけ見て「Slack/SMS/Push通知システム」と書くなど
• 画面遷移図もコード根拠必須。 ルーティング定義やリンク先が確認できない画面・遷移は記載しない
• コード分析（フェーズ1〜2）は親が直接実行する。 Task エージェントに仕様書作成を丸投げしない。ファイル探索の補助には使ってよいが、コードの中身は親が読む。spec-writer に渡す根拠リストも親が事前に用意する
• spec-writer には「渡されたリストのみ使う、独自にgrepしない」と必ず明記する
• 既存コードは一切変更しない（spec-map.yml への記録のみ）

コード分析時の注意: .claude/rules/doc-accuracy.md「ドキュメント生成の正確性ルール」を厳守すること。