開発者が並列Claudeコードセッションのために仕様書から提案書へ切り替え

仕様書ファースト・アプローチの問題点

開発者は、詳細な仕様書を事前に作成すると、AIが生成するコードが技術的には正しいものの文脈的に間違ったものになるという問題に直面しました。仕様書には「認証エンドポイントにレート制限を追加する」と書かれていても、以前に却下されたアプローチ（トークンバケットなど）や実装上の決定（ステージング環境でCloudflareではなくRedisを選択するなど）に関する文脈が含まれていませんでした。これにより、AIが合理的な選択をして、すでに決定済みの事項を再び議論の場に戻す状況が生まれました。

仕様書の更新自体が小さなプロジェクトのようになり、更新された仕様書がレビューされる頃には、コードベースはすでに元の仕様から乖離していました。仕様書は「何を」行うかを記録していましたが、「なぜ」そうするのかという理由、検討された代替案、決定のタイミングといった情報が欠落していました。

提案書ファーストという代替案

事前に仕様書を作成してそれに合わせてコーディングする代わりに、開発者は提案書を作成します。提案書は、なぜ変更が行われるのか、何が検討され却下されたのか、何が範囲内で何が範囲外なのかを記録した短い文書です。仕様書は、実際に構築された内容を反映するために、コードが完成した後に更新されます。

比較例：

• 仕様書では：「システムはレート制限をサポートするものとする。」
• 提案書では：「本番環境でブルートフォース攻撃が検出されました。スライディングウィンドウ＋Redisによるレート制限を追加します（ステージング環境ではCloudflareが利用できません）。バーストトラフィックの問題のため、トークンバケット方式は却下しました。範囲：ログインとパスワードリセットのみ。」

提案書は、AI（および将来の開発者）に全体像を提供します。

並行提案書ワークフロー

開発者は複数のClaude Codeセッションを同時に実行し、それぞれが異なる提案書に取り組みます。時には、同じ問題を異なる角度から解決する競合する提案書を作成することもあります。

典型的なワークフロー：

• 2〜3つの機能/バグ/課題に同時に取り組む
• 課題ごとに異なるアプローチの提案書を1つまたは2つ作成する
• 各提案書に対してClaude Codeセッションを立ち上げ、並行して実行する
• 各セッションがGitHub PRを生成する
• GitHub PRが提案書のレビュープラットフォームとして機能する
• アプローチとコードを一緒にレビューする
• 2つの提案書が同じ問題に異なる方法で取り組んでいる場合、より良い方を選び、もう一方を閉じる
• 承認されたPRがマージされたら、Claudeに提案書を実装するよう指示する
• 将来の提案書で素早く参照できるよう、コード変更を反映して仕様書を更新する

仕様書は、初日から乖離する理想的な文書ではなく、常に現実と一致する生きた文書になります。

PACEサイクル

開発者はこのサイクルをPACE（手順を覚えるため）と呼んでいます：

• 提案（Propose）：文脈と理由を含む短い提案書を作成する
• 承認（Approve）：GitHub PRでレビューし、アプローチを評価する（承認、修正、却下）
• コーディング（Code）：AIが提案された内容を正確に実装する（それ以上は行わない）
• 進化（Evolve）：新しい現実を反映するよう仕様書を更新する