はじめに
この記事は、私が最近Claude Codeを中心としたAIワークフローを設計を考えていく上で意識していることを言語化したものです。
前提として、実装前に「正解」が定義されているSDD(仕様駆動開発)やIssueドリブン開発の環境を想定しています。
まず、正解となるソースが明確にある以上、AIとのラリーは本来削れるはずのコストだと考えています。
「1回(1-pass)」完遂は簡単ではありませんが、あえて「通らないのは自分の仕込みが甘いだけ」と割り切り、AIを自律走行させる「仕組み」として捉え直す。そこからがスタートだと考えています。
1. AIとのやり取りをコストとして捉え直す
インプットを正としてワークフローを組む以上、「指示からPR作成までを、いかに1回目の実行で完遂させるか」を追い求めることは、仕様の言語化がどこまで徹底できているかの良い指標になります。
- 人間の介入を「コスト」と知る
エージェントが完結すべき工程で人間が微調整を繰り返すのは、プロセスのどこかに「準備の甘さ」があるからです。
- 事前の「仕込み」を徹底する
手直しが発生したなら、それはエージェントの能力不足だけではなく、「指示が仕様として成立するレベルに達していない」のが原因。動かす前に「これなら1回で通る」という確信が持てるまで情報を整える。このAI時代の前から当たり前の「仕込み(設計)」への注力こそが、効率化の要だと思っています。
2. 開発プロセスの3ステップ：観測・仕込み・自走
具体的にどう「仕込み」の精度を上げ、個人の試行錯誤をチームの仕組みへと昇華させていくのか。私はそのプロセスを、「観測・仕込み・自走」の3ステップで整理しています。
【観測】 境界線を引き、AI担当領域をあぶり出す
まずは全体のワークフローを俯瞰し、どこを人間が担い、どこをAIに任せるかの境界線を引くことから始めます。
その上で、AIが担当する領域においてClaude CodeなどのCLIツールで自律的なワークフローを組んでみて回し、人間がどのタイミングで、なぜ口を出さざるを得なかったのかを執拗に観察します。
人間がAIに修正を指示したその瞬間、それは現状のインプットが、プロジェクトの仕様として不十分であることの証拠です。
【仕込み】 プロジェクトの「型」を磨き上げる
「観測」で得られた対話ログや失敗パターンをAI自体に分析させ、「なぜ1回で完遂できなかったのか」の傾向を抽出します。
その分析結果をもとに、CLAUDE.mdへの明文化やSkillsの定義、Subagentsへの切り出しなどを行い、「誰が指示しても迷わず正解に近づける環境」を理想として、型を磨き上げます。
【自走】 リモート環境への解放と並列化
ローカルで極限まで高めた精度を、リモート環境でも再現可能にします。その手法として、Claude Agent SDKやclaude-code-actionによる連携などが挙げられます。
- 「独立した実験場」としてのリモート
リモート実行は既存フローから切り離された環境として構築できるため、まずは一人で壊しながら「型」を試行錯誤するのに最適です。ただし、従量課金APIを利用する場合は相応のコストがかかるため、プロジェクトや予算に応じて導入を判断してください。
- Lane 1: 人間(ローカルでの
Claude Codeによる実装と仕様作成)
不確実性の高いコア領域の実装に加え、リモートのエージェントを迷わせないための「仕様の正解(インプット)」の作成・修正に集中します。手元でClaude Codeを使いながら、「これなら1回で通る」という確信が持てるレベルまで情報を研ぎ澄ませます。
- Lane 2: エージェント(リモートでの自律実行)
Lane 1で磨き上げた「仕様の正解(GitHub Issueやドキュメントなど)」を元に、定型作業、リファクタ、検証、PR作成までをリモート環境で黙々と完走させます。もちろん自律実行中にミスが出ることもありますが、その修正対応すらも「次回の仕様を磨くためのフィードバック」として活用します。
3. 「1回」の精度は、情報の集約と失敗の分析で決まる
ワークフロー全体をいきなり最適化するのは難しいですが、まずは個別最適としての「1回（1-pass）」を目指します。
その個別最適の積み重ねが、やがて全体最適としての精度を1回に近づけていくからです。
個別最適において「1回で通す」ためにやるべきことは、「情報の整理」と「失敗した理由の特定」が主だと思っています。
探索させないための「マッピング」をIssueに仕込む
ただ情報を羅列するだけでは、コンテキストの肥大を招き、エージェントの判断を鈍らせるだけです。
大事なのは、タスクの起点となるIssueの段階で、どのファイルのどのロジックを触るべきかの「マッピング」を明確にしておくことです。
エージェントに「正解のコード」を自分で探させるのではなく、あらかじめ「ここを見て、このパターンで書いて」という道標を置いておく。この情報の密度と的確な誘導が、自律走行の鍵になります。
「なぜズレたのか」を徹底的に潰す
エージェントが1回で正解を出せなかった場合、その場でのコード修正で満足せず、「なぜ出力がズレたのか」の原因を掘り下げます。
この「情報の整理」と「失敗した理由の特定」を泥臭く繰り返すことで、個々のタスクの精度が上がり、やがてプロジェクト全体にも最適化されていきます。
最後に
AIエージェントを導入する本当の目的は、単にAIに指示を投げることだけではないはずです。
AIが迷わず完走できる「準備」を整えて、人間が「作業」ではなく「意思決定」に集中できる状態を作ること。
「コンテキストエンジニアリング」と聞くと難しく感じるかもしれませんが、要は今回触れたような「小さな仕込みの積み重ね」なのかなと思っています。
最初から100%完璧なコンテキストを与えるのは難しくても、失敗した時にプロンプトをいじるのではなく「情報の欠落」と捉えて、GitHub Issueやドキュメントを改善していく。その繰り返しが、結果的にコンテキストエンジニアリングの追求に繋がっていく気がしています。
この泥臭い積み上げの先に、人間が実作業を手放して、より面白い設計や判断に専念できるようになると信じています。
そのために、今回述べたような意識を常に持って、これからも開発を進めていこうと思います。
Discussion