設計原則
1. ファイルがAPI
各フェーズはワークスペースディレクトリ内のMarkdownファイルに出力を書き込みます。後続のフェーズはそれらのファイルのみを読み取り、会話履歴は参照しません。
これにより：
- 各サブエージェントがクリーンなコンテキストウィンドウで開始
- オーケストレーターが大きなコードブロックを蓄積しない
- すべての進捗がディスク上にあるため、中断と再開が可能
.specs/20260320-fix-auth/
├── request.md ← ユーザー入力
├── analysis.md ← Phase 1 出力
├── investigation.md ← Phase 2 出力
├── design.md ← Phase 3 出力
├── review-design.md ← Phase 3b 出力
├── tasks.md ← Phase 4 出力
├── review-tasks.md ← Phase 4b 出力
├── impl-1.md ← Phase 5 出力（タスク1）
├── review-1.md ← Phase 6 出力（タスク1）
├── comprehensive-review.md ← Phase 7 出力
├── summary.md ← final-summary フェーズ出力
└── state.json ← パイプライン状態
final-verificationやpr-creationフェーズではアーティファクトファイルは作成されません — コードベースとgitに直接作用します。
2. 関心の分離
オーケストレーターは {workspace}、{N}、{spec-name} などのみを渡します。エージェントは自身の定義から読むべきファイルと出力フォーマットを知っています。
この分離により：
- エージェントの命令は自己完結 — SKILL.mdでの重複なし
- オーケストレーターは軽量を維持 — ソースコードを読まない
- エージェントはオーケストレーターに触れずに独立してアップグレード可能
3. ディスク上の状態、メモリではない
state.json がパイプライン進捗の唯一の情報源です。以下の問題を解決します：
- コンテキスト圧縮 — Claudeが会話履歴を圧縮しても、状態は残る
- セッション再起動 — ワークスペースパスでスキルを再呼び出しして再開
- フック連携 — フックがstate.jsonを読んでアクティブなフェーズを把握
4. 二層コンプライアンス
重要な不変条件は、エージェント命令（確率的）とフックスクリプト（決定論的）の両方で強制されます：
| 不変条件 | プロンプト（確率的） | フック（決定論的） |
|---|---|---|
| Phase 1-2 読み取り専用 | agent.mdの「ファイルを書くな」 | PreToolUseがEdit/Writeをブロック |
| 並列git commitなし | agent.mdの「コミットするな」 | PreToolUseがgit commitをブロック |
| 完了前のチェックポイント | SKILL.mdの「checkpointを呼べ」 | MCPハンドラーがphase_completeをブロック |
| 進行前のアーティファクト | SKILL.mdの「アーティファクトを書け」 | MCPハンドラーがphase_completeをブロック |
| パイプライン完了 | SKILL.mdの「summary.mdを書け」 | Stopフックが途中終了をブロック |
プロンプト命令よりも決定論的な強制を優先する。 パイプラインの動作を追加する際は、まずフックスクリプトで強制できるか検討してください。
5. フェイルオープンフック
すべてのフックはフェイルオープン：jqが欠落しているかstate.jsonが読めない場合、アクションは許可されます。これにより、フックがパイプライン外の作業を妨げることを防ぎます。
6. ユーザー制御によるエージェントモデル選択
エージェントはデフォルトでユーザーが設定したモデルを継承します — エージェントフロントマターに model: キーは設定されていません。これにより、パイプラインがモデルを上書きするのではなく、ユーザーが Claude Code の設定を通じてモデルの選択を制御できます。必要に応じてフロントマターに model: <name> を追加することで、個別のエージェントを特定のモデルに固定できます。