- 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は単なる実装者ではなく、協調的な設計パートナーとして位置づけられる
2件のコメント
開発者のワークフローにおいて、PMやアーキテクトの役割の比重がさらに大きくなっているようです。
Hacker Newsのコメント
この2週間、毎晩
claude codeを使ってプロジェクトを一気に完成させられる「完璧なプロンプト」を作ることにものすごく集中していた。最終的には、1つのCLAUDE.mdから、プロジェクトアーキテクチャ、モデル仕様、ビルド順序、テスト階層、シナリオなどを記した8つの異なるMarkdownファイルを参照する構成にした。このプロジェクトは Databricks Unity Catalog のモデルベースガバナンス向けで、自分には関連経験が豊富にあるものの、既存ツールは十分に柔軟だとは感じていなかった。最終的に、Databricks専門家、Pydantic専門家、プロンプト専門家の3つのサブエージェントに、実際の企画ファイル作業を支援してもらった。そのおかげで、Markdownファイルの品質は、以前の Pydantic バージョンの問題から Unity Catalog に対する自分の誤解まで、さまざまな面で大きく改善された。昨日は実際に動かしてみたが、自分が数回ツール使用を承認した以外は、2時間で大半のツールとテストが完成した。このやり方は以前とあまりに違っていて驚いたが、技術文書を丁寧に書き、全員が同じ方向を向けるようにすることに本当に未来があると感じた。コードを直接掘るより生産性が高いとも思う。ただ、コード作業では没入感が高かった一方で、複数のMarkdown文書を扱うと集中力がより散りやすいという欠点がある。本当に興味深い時代だTest-Driven Development のように、先にシステムを設計させるパターンが新たに台頭してきているのを感じる。以前はコードを書きながらシステムを段階的に形にしていったが、今回のようなAIベース開発では、領域を先に設計してマッピングすることになり、実際のコードは単に設計を実現するためのボイラープレート作業のようになる。AIはこういうボイラープレートに本当に強い
自分もまったく同じで、生産性は上がるのに集中力はもっと散るという現象に悩んでいる。何だか変だが、今のところは効果的だ。長期的には解決策を見つける必要がありそう。今いちばんしっくり来ている方法は、複数のエージェントにプロジェクト内の複数のリポジトリでそれぞれ別タスクをさせつつ、承認作業を続けること。大規模チームを率いるプロジェクトマネージャーのような感覚だ。やはり興味深い時代だ
本当に新鮮なやり方だ。実際の実験でエージェントが動いているフレームワークが何なのか気になる
最近自分も、製品のディテールやユーザージャーニーなどを音声で記録し、それをもとに技術文書化プロセスを始めている。最小限の
CLAUDE.md、ソフトウェア開発には Github ワークフローを活用しているが、良い CI ワークフローを作るのが難しい。自分のプレイブックは https://nocodo.com/playbook/ にある「まず計画を立てれば結果が良くなる」という主張にはあまりピンと来ない。自分は以前から大きな機能やプロジェクトについては当然、頭の中でも紙でも Confluence でもホワイトボードでも、あらかじめ構造と理由、方法を考えていた。ソフトウェアエンジニアリングの80%は、「何を、なぜ、どうやって」やるかを考え、固めるプロセスだ。ステークホルダーとアイデアや目的を確認し、リサーチもする。最後の20%だけが実際のコーディングだ。昔からそうだったし、ちゃんとした企画や目標定義にAIが必須なのかはわからない
大きなチームや文化が根付いた環境ではそうかもしれないが、かなり多くの開発は個人プロジェクト、小規模チーム、サイドプロジェクト、素早い POC、単発の自動化ツールなどに集中している。こうした作業は最初から文書・仕様・テストで始めるのではなく、コードと検討・実装のプロセスを混ぜながら進める。TDD が適している場面もあるが、別に必要ない場合も多い。だがAIコーディングエージェントを導入してからは、アイデアを明確に定義し、仕様として整理する過程がはるかに重要になった。自分の頭の中に浮かぶことをすべて言葉にするのが、それだけ必須になっている。最近もっともホットなプログラミング言語は英語だ
自分は開発と設計を混ぜて進めるタイプだ。とりあえずコーディングを始めて、そこから磨き込み、発展させていく。たいていの場合、おおまかな解決方法は明白なので、時間をかけて深く計画する必要はないと感じる
昔はプロンプトエンジニアリングなんて冗談の種だったが、今では本当に実感している。Claude Code を体系的に活用しようとして、10〜20分かけて綿密なプロンプトと初期計画に張り付くこともある。自分も OP と同じようにプランをファイルに保存し、新しいコンテキストで実行している。本当に欲しいのは良い CLI だ（今は charm と cc を使っている）。実装、プラン、サブエージェントごとに別モデルを使えたら最高だと思う。ローカルモデルで実装し、クラウドモデルでプランを立てたり、必要に応じて切り替えてコストを節約したりする構成だ。Charm は今まで使った中で、コンテキストを失わずに行き来できる点がよくできている。並列サブエージェント機能も
claudecodeの最高の機能の1つだ。（CCR も試したが、ベースモデル以上にはならずがっかりした）プロンプトエンジニアリングが今話題になっているのは、Twitter のホットテイクやコンテンツ生産まわりの話題性によるところが大きい。だが実際には、プロンプトエンジニアリングは昔から重要だった。GIGO（"Garbage In, Garbage Out"、ゴミを入れればゴミが出る）は、あらゆる機械学習プロジェクトで真理だ。だから同僚や友人には「自分で使ってみるべきだ」と勧め続けている。6か月前にはできなかったことが、今はできるかもしれない。実際に手に馴染ませてこそ、何が変わったのか、何ができるのかがわかる。自分は、ネガティブな話よりも実際の成功事例やブログ、gist、例のほうがずっと価値があると思う。ごく単純な計算や誤字探しではなく、自分のワークフローを改善し、助けてくれるのでなければ必要ない。プロンプトエンジニアリングは、10〜15年前に Google 検索スキルを極めることに没頭し、次々に出てくる変化や効果的なパターンを学び続けるのに似ている
AIと協業するには、プロンプトエンジニアリングが本当に核心だ
AIを使うプロジェクトは、自分がこれまで関わった中で最も文書化とテストが行き届いたプロジェクトだった。LLM から性能を引き出すには必ずコンテキストが必要なので文書化が進み、テスト生成コストが下がったことでテストも増えた。むしろコード品質が落ちるという予測とは逆に、良くなっていくと思う
正直、「プロンプトエンジニアリング」という用語は、新しいメディアを使ったアーキテクチャ設計のことだ。かつて「ダイアグラム設計」というスキルが注目されたように、今は新しい形のアーキテクチャリングなのだと思う
最近 Claude Code を少し使ってみたが、勧められたワークフローを試すつもりだ。かなり良さそうなやり方に見える。ただ、CC の利用料は思ったより高い。簡単なリファクタリングに5分作業＋15分レビューしただけで4ドルかかった。自分でやっていれば15〜20分で終わった作業だ。普通、機能1つあたり CC にどれくらい使うのか気になる。誰も価格の話をしない
サブスクなら $20〜$200 のフラット料金で、日次・週次のトークン使用量制限がある。https://support.anthropic.com/en/articles/11145838-using-claude-code-with-your-pro-or-max-plan
AI 投資家たちが望んでいる方向性は、労働市場を 15% マージンで AI が置き換える構造だ。開発者と AI の予算が1対1になる時代が来るだろう。たとえば年収10万ドルのシニア開発者1人分が、10万ドルの AI 予算に置き換わる。AI 予算は開発費から捻出され、シニアの年収は下がる可能性が高く、開発チームの規模も急激に縮小しうる。今は VC が全額補助する「陣取り」段階だが、Twitter 上の VC の空気を見るとこの段階はまもなく終わりそうだ。9か月のランウェイに5億ドルを何度も追加調達するのも限界に近づいている
Cursor から Claude Code に一部移行して以来、コストはかなり増えた。会社で主に使うので上司の説得はしやすかったが、サイドプロジェクトでは悩ましい。遊びでアプリをブートストラップするたびに20ドル払いたくはない
Sonnet（20ユーロ/月）と Opus（100ユーロ/月）の2モデルから選んでサブスクできる。自分は Sonnet を使っていて、後で Opus に切り替えた。Sonnet でも十分実用的だ。トークン上限の範囲内では、自分の用途には不足なく使えている。ただ、今後もそうかはわからない
「自分でやっても15〜20分で済んだ」と言っていたが、その15〜20分を別の作業に使えるのではないかとも思う
Visual Studio Code / ChatGPT5 プレビューの組み合わせを使うやり方が、自分のワークフローに近い{たぶん Github Copilot サブスクで支払っているが、最近はよくわからない}。非エージェント型の LLM は、コードがすぐ壊れがちだと感じる。エージェントモードを使うとコード構築が一気に変わる。自分は Python 開発者ではないが、LLM が新しいコードの塊を組み立てるのを見て、実際かなり感心した。完成後は BitGrid で小さな LLM を動かし、後からコードを完全に理解する方向で進めようと思っている。小さな探索ステップを繰り返し、全体設計を自分の望む形に保つために一部だけ修正する構造だ。LLM がプログラミングパートナーになる未来に確信を持つようになった。Visual Studio Code / ChatGPT5 の組み合わせを使っている他の人がいるのか気になる
AI ツールを最適化しようとする中で、開発者たちが「良いコミュニケーション」と「期待値設定」の価値を再発見しているように見えるのが興味深い。これまでの 10x 開発者像、つまり異邦人や変人タイプのイメージは見直す時期なのかもしれない
Replit でも似た経験がある。アプリの規模が大きくなると、設計文書がタスクと真実のソースになっていないと、すぐに崩れてしまう。OpenAI はチャットが遅くなり、すぐ動かなくなるので、文書を別に作って新しいチャットにインポートするのが役に立つ。人間レベルでも、自分たち自身そうすべきだと感じた。自分で振り返りながら文書化し、「メモリ」を設計文書に記録することで、自分たちも LLM も自由になれる
自分も最近このワークフローを見つけて、とても驚いた。重要なのは、
claudeに最小限の要求だけを与え、プランモードを自由に走らせることだ。もし営業指標レポートなら、Ultrathink relevant sales metricsとだけ言っても、さまざまな指標を提示し、優先順位を付けて絞り込めるようにしてくれる。新しい機能ごとにディレクトリを別に作り、その機能のプランをファイルとして書かせる。その後は、実装計画、必要なデータクエリ、実装、テスト、ユーザー文書作成まで段階的にやらせ、QA に回す。以前なら営業予測機能を1つ作るのに大規模チームと時間が必要だったのに、claudeは半日で Docker コンテナとして実装した。この変化でソフトウェアに対する自分の見方が変わりつつある。以前は NDA や IP などの理由で、企業はソースコードを決して外部に出さなかった。だが今では、20年かけてできた複雑な ERP システムでさえclaudeが素早く再実装し、文書やテストまで添えてくる。現実にはまだ完璧ではないが、進みは本当に速いClaude Code で良い成果を引き出すには、まずプランをきちんと書くことが核心だ。自分は最近 Cursor で GPT-5 High を使ってプランを立て、それを Claude Code に入れて実装している。コードベースのどこを変更すべきかを事前に文書化させると、さらに 15〜20% 良い結果が得られる。プラン用モデルに動作方式、アーキテクチャ、パターンを文書化させ、機能設計までそこに織り込むと成果物が良くなる。最後に、必ず文書とプランを自分でレビューし、修正することも非常に大きな助けになる
こういうプロセスにフロントエンドデザインをうまく組み込む良い方法を見つけた人がいるのか気になる。たいていはフロントエンドフレームワークへの言及か、せいぜい figma の画像レベルで終わってしまう。それでは統合的なデザインソリューションという感じがしない