- Claude Codeを最初に使ったときは、単純にプロンプトによる指示と修正の反復という形で取り組んでいたが、複雑な作業では会話履歴への依存とコンテキストの限界という問題に直面した
- これを解決するため、機能実装の前に計画書（plan document）を作成させ、これを新しいセッションにおける単一の**信頼できる情報源（SSOT）**として扱うようにした
- 計画書には、要件の整理、実装詳細の説明、コード品質を確認するコマンドなどを含め、実装中も**生きた文書（living document）**として継続的に更新される
- こうすることで文脈喪失の問題が解消され、新しいセッションでも単一の文書だけでプロジェクトを継続できる
- 結果としてAIは単なる実行ツールではなく、開発者が設計をより深く考え、記録するよう促す協調的なデザインパートナーの役割を果たすようになる
問題意識: 単純な会話方式の限界
- Claude Codeと対話型で作業を進める場合、簡単な作業には向いているが、複雑な作業が大きくなるにつれていくつもの重大な限界が生じる
- 会話が唯一の真実の情報源になってしまい、新しいメッセージが以前の指示を簡単に上書きでき、その瞬間を明確に認識しにくい
- AIのコンテキストサイズの限界により、会話が長くなるほど先行する情報が抜け落ちる可能性がある
- Claude Codeには会話圧縮機能があるが、この限界を完全に解消するわけではない
計画書中心の方式の実験
- こうした問題を解決するため、計画書ベースのアプローチを試した
- 開始時に、Claude Codeに対して実装する機能や修正すべきバグなどをできるだけ詳しく説明する
- 参照できる既存のソースファイルや以前に作成した計画書についても言及する
- 過度に具体的な実装指示は避け、AIが設計提案を行う役割を発揮できるようにする
- 計画書の内容に十分満足できたら、会話履歴を消去し、その計画だけをコンテキストとして新しく開始する
- 計画には、機能の要約、実装計画、コードおよび擬似コード、型チェック／lint／テストのコマンドなどが含まれる
協調的な設計プロセス
- AIが提案した設計が気に入らないときは、具体的なフィードバックを与えて修正されたアプローチへ導く
- 議論の過程で、AIの最初の提案のほうが適切だったと気づくこともあり、自分だけの設計でコーディングを進めるより効率的である
- 体系的な会話は、同僚の開発者と計画を議論しているのに近い体験を提供する
- AIが単独でまったく異なるアプローチを提示するわけではないが、尋ねれば別の代替案を提案することもある
生きた文書（Living Document）方式
- 計画書は一度作って終わりにせず、機能実装の途中でも継続的に更新させる
- 実装過程や型チェック、lint、テストの過程で明らかになった変更点をリアルタイムで反映する
- コードをコミットするたびに、計画の最新状態を確認するよう求める習慣をつける
- 常に最新の計画が維持されることで、新しい会話セッションでも計画だけを添付すれば文脈を失わずそのまま継続できる
コードレビューと開発習慣の変化
- 実装が始まった後は定期的に変更点を確認し、満足できればAIの作業をより信頼するようにもなる
- 最終的なコードレビューでは、更新された計画書が技術的な意思決定の根拠を把握するのに役立つ
- 事前に緻密な計画を立てて文書化することで、より良い開発者へ成長しているという実感が得られる
- AIに説明する必要があるため、自分の意思決定プロセスを明確に整理するようになる
混沌から体系へ
- この方法は、計画書を単一の信頼できる情報源にし、文脈喪失の問題を解消し、アーキテクチャ思考を促進する
- 計画書には仕様と実装ログの両方が含まれ、「何を」だけでなく「なぜ」「どのように」まで記録する
- 最終的な結果は、計画的で、十分に文書化され、信頼性の高い開発プロセスである
- AIは単なる実装者ではなく、協調的な設計パートナーとして位置づけられる
まだコメントはありません。