機能プロセス
基本原則: エージェントが自ら下す決定が少なければ少ないほど、結果は安定する。 各フェーズは docs/features/<slug>/ 内の成果物と確認（「ゲート」）で終了する。注記がある場合、次のフェーズへの移行は人間の確認後にのみ行われる。
コードの書き方 → fsd-frontend; ゴミコードのチェック → anti-slop-review; ログインとセッション → frontend-auth-session。
1. フェーズ
| # | フェーズ | 成果物 | 承認者 | ゲート |
|---|---|---|---|---|
| 0 | 準備 | ブランチ | — | ワークツリーがクリーン; 依存関係のインストールとマイグレーション後は /clear |
| 1 | PRD | prd.md | 人間 | Non-Goals が記入されている; 基準が検証可能; 技術的解決策がない |
| 2 | 仕様書 | spec.md（最大150行） | 人間 | PRDの全基準をカバーし、それ以上は含まない |
| 3 | タスク | tasks.md | 人間 | 1タスク＝1コミット; 最初のタスクはトレーサー・ブレット |
| 4 | 調査 | tasks.md 内のログ | — | 読み取りのみ; 再利用すべき既存コードを発見 |
| 5 | トレーサー・ブレット | コミット | — | 1つのシナリオがエンドツーエンドで動作し、ブラウザで確認できる |
| 6 | ビルド | タスクごとのコミット | — | ロジックはテストファースト; pnpm check がグリーン |
| 7 | レビュー | reviewer のレポート | 人間（指摘事項に関して） | 確認済みの指摘が修正されている |
| 8 | ブラウザ | クリティカルパスのe2e | — | PRDのシナリオがコンソールエラーなくパスする |
小規模なタスク（1コミット、ユーザーにとって新しい動作がないもの）はフェーズ1～3をスキップできるが、Non-Goals はタスクの説明に必ず記録する。フェーズのスキップは黙って行うのではなく、明示的に宣言する。
2. PRD
テンプレート → docs/features/_template/prd.md。
- エージェントはリクエストからドラフトを作成し、続行に不可欠な質問のみを行う。それ以外は「未解決の質問」に仮定として記載し、人間が承認時に確認する。
- Non-Goals は必須。 エージェントが「ついでに」やりたくなること（新しいサイズへの対応、アニメーション、i18n、キャッシュ、管理画面、隣接コードのリファクタリングなど）を列挙する。このリストがないと機能が肥大化する。
- 完了基準は検証可能であること：「Given / When / Then」形式で記述し、「使いやすい」「高速」などの主観的な表現は避ける。
- ライブラリ、ファイル、スキームは記載しない：「何をなぜ」を問うものであり、「どのように」ではない。
3. 仕様書
テンプレート → docs/features/_template/spec.md。
- 最大150行。エージェントが作成し、人間が承認する。長大な自動生成仕様書は、コンテキストを圧迫し決定を曖昧にするため、ないより悪い。
- 作成前に、影響を受けるレイヤーを短く読み取り専用で調査する：既存コード、再利用可能なもの。
- 以下の内容を含む：コードの配置場所（レイヤー、スライス）、データの契約（zodスキーマ、DTOマッピング）、API（入力、出力、エラー →
kind）、UIの状態、境界ケース、テストレベルを含む受け入れシナリオ。 - 仕様書はコードとともに生きる。 動作が変更された場合は、同じコミットで
spec.mdを修正する。仕様書と矛盾するコードは、どちらかの欠陥である。
4. タスク
テンプレート → docs/features/_template/tasks.md。
- 1タスク＝1コミット。コミット後、プロジェクトがビルドされチェックがパスする。エージェントが行き詰まった場合、前のコミットにロールバックする方が、モデルと議論するより安価である。
- タスクは1セッションに収まること。各タスクに「完了条件」を設定する。
- 最初のタスクはトレーサー・ブレット、その後は状態、境界ケース、ポリッシュ。
5. 調査（読み取りのみ）
各タスクの前に、ファイルを編集せずに以下を確認する：
- 影響を受けるフォルダの
AGENTS.md; - 類似の処理を行う既存コード（
rgで名前と契約を検索）; - タスクが依存する契約と型。
後で必要になる情報があれば、tasks.md のログに2～3行記録する。
6. トレーサー・ブレット
1つのシナリオをエンドツーエンドで実装する：ルート → ページ → 機能またはエンティティ → request() → ルートハンドラーまたはバックエンド → 画面に結果を表示。
- これはプロトタイプではなくプロダクションコード：適切なレイヤー、仕様書に基づく実際の契約を使用する。
- 意図的に省略するもの：詳細なバリデーション、ローディング状態とエラー状態のポリッシュ、スタイル、境界ケース。
- バックエンドが準備できていない場合：MSWハンドラーまたはルートハンドラーを使用し、仕様書の契約に従ったデータを返す。これは
tasks.mdに記録する。 - 確認はブラウザで行う：シナリオがパスし、コンソールにエラーがないこと。
7. ビルド
- ロジックはテストファースト： 純粋関数、ストア、レスポンスマッピング、分岐のあるフック。テストは期待される理由で失敗し、その後コードを実装する。コードの後に書かれたテストは、要求された動作ではなく、コードの実際の動作を検証する傾向がある。
- マークアップとスタイルは事前テストなし： ブラウザ（フェーズ8）で確認し、クリティカルパスはe2eでカバーする。
- タスク後：
pnpm check、コミット（lint-staged が変更ファイルをチェックする）。 - 停止条件： 同じ問題を3回修正しようとして失敗した場合、作業を停止する。試したことと仮説を人間に説明する。テストをコードに合わせて調整したり、リンタールールを無効にしたり、型を弱めたりしない。
- タスクの範囲外のものは「後で」ログに記録し、このコミットには含めない。
8. レビュー
- サブエージェント
reviewer（.claude/agents/reviewer.md）をクリーンなコンテキストで使用する：prd.mdとspec.mdのパス、およびコミット範囲を渡す。差分はエージェント自身が読み取る。コード作成者は自分のエラーを見つけるのが苦手である（作成者のコンテキストには「なぜその解決策が正しいか」という論拠が含まれるため）。 - 確認された指摘は修正し、議論のあるものは人間が判断する。
- セキュリティは人間も確認する： ログイン、セッション、リダイレクト、Cookie、HTMLへのユーザー入力。自動チェックがパスしてもこれらは保証されない。実際に、オープンリダイレクトがテストをパスし、エラーページがリンターをパスした事例がある。
9. ブラウザ
- Next.js：
next-dev-loopスキルとagent-browserがインストールされていればそれを使用し、そうでなければ Playwright または Chrome DevTools MCP を使用する。 - ネガティブシナリオを含むPRDのシナリオを実行する：空データ、ネットワークエラー、再送信。コンソールとリクエストステータスを確認する。
- UIはライトテーマとダークテーマ、電話幅で確認する。
- クリティカルパスは
e2e/にe2eテストを作成する。 - 完了条件： すべてのPRD基準が確認されていること。最終メッセージには、各基準とその確認方法のリストを含める。
10. コンテキスト
- 作業の状態はチャットではなく
docs/features/<slug>/に保存する。新しいセッションはprd.md、spec.md、tasks.mdを読むことから始める。 - ノイズの多いステップ（インストール、マイグレーション、長いログ）の後は
/clearを実行する。 - 並行実験は
git worktreeを使用し、作業ブランチでは行わない。
11. やってはいけないこと
- 無限に続く質問：ブロッカーとなる質問のみ行い、残りはPRDに仮定として記載する。
- 多数のエージェントによるオーケストレーション：実行者とレビューアで十分。
- 誰も承認せず読まない仕様書やドキュメント。
- フェーズの黙ったスキップや「ついでに修正」。