コーディングエージェントを用いた開発（2026下期ver)

気が付けば 10 月も後半 (しかも会社は期末) ということで、コーディングエージェントを使った開発の振り返りをまとめてみます。

本格的にコーディングエージェントで開発を始めたのは今年の 2 月ごろなので、だいたい半年ちょっとです。まだまだ模索中なので、「今の時点ではこうしている」という記録として読んでもらえればと思います。（ちょっと長いです）

契約と役割

• なんだかんだで、主のコーディングエージェントは Claude のままで、一度も乗り換えていません。
  • 正直、微妙だなと思う場面 (特に Opus 4.8 を使っていたころ) はちょこちょこありました。「Codex 最高！」というタイムラインを横目に、乗り換えたい気持ちをぐっと抑えていた時期もあります。
  • Fable の利用延長や、Anthropic の夏のリセット祭りがあってからは、乗り換えたいとはあまり思わなくなりました。気が付けば週の利用枠が足りなくなり、枠を増やしていたくらいです。
• 2 台のマシンは、どちらも Ubuntu 24.04 LTS です。それでも「WSL」「Ubuntu」と名前を分けて呼び、それぞれの責任範囲を Claude に理解させています。セッションの最初に「ここはどちらのマシンか」を確かめさせるのがポイントです。
• Codex は主にレビュー用です。Claude の側から、ちょっとしたことでもすぐにセカンドオピニオンを取れるように、Codex CLI を呼ぶスキルを作っています。

情報の共有と開発フロー

GitHub のリポジトリは 3 つに分けています。製品のコードを置く開発用、メモリ管理用、ドキュメント管理用 (設計や実装の詳細) です。ここでは、メモリ管理とドキュメント管理の 2 つを紹介します。

2 台の Claude が 3 つのリポジトリを共有し、Codex がレビューに入る

メモリ管理リポジトリ

• MEMORY.md と、タスクやルールに関するメモリをリポジトリに出してメンテしています。
  • プライベートとはいえ、秘匿性の高い情報や機密情報を上げるわけにはいきません。細かい決まりと機械的なチェックを用意して、上げるときは必ずそれを通すようにしています (ドキュメントも同じです)。
  • 起動時や節目に hook を用意して、相手の端末に情報を送るように明示しています。
  • MEMORY.md の読み込みの上限 (先頭 200 行か 25KB の、先に達した方) がどこまで厳密かは調べていません。ただ、ルールをあまり置いていなかった最初のころは、2 台が平気でどんどん情報を積んでいきました。索引の MEMORY.md が 34KB まで育ち、後ろの方が読まれていない疑いが出たこともあります。今は索引を「1 行 = 1 メモリの見出しだけ」にし、進行中の作業は端末ごとの索引に分けています。ルールを決めた後でも、定期的な棚卸しは必要です。
  • メモリに残してくれるのはありがたいのですが、「ほぼ終わっているタスク」や「私としては終わったつもりのもの」にも、細かい残作業やちょっとした補足を書き残しがちです。「不要」「完了したら捨てる」と明示するのが大事です。
• メモリだけで済ませるか、Issue に起票するかを分けています。
  • 最初は狭い範囲しか考えていなかったので、「とりあえず備忘も兼ねて、これまでどおり起票だ！」と思っていました。でも開発が深くなると、実際に扱うのは人ではなく AI で、状態もどんどん変わります。コメントを追記していく形だと、文脈が無駄に長くなり、不要なことも増えます。
  • そこで、状態は基本メモリに書き、決定事項・共有事項と、人として残しておきたい視点を Issue に残すようにしました。軽い対応や、ほかに影響しない単発のものはメモリだけで済ませ、決定事項はドキュメントの決定記録に残す形も試しています。
  • ちなみに Claude は放っておくと、気になったことを次々と新しい Issue にします。今は「新しく起票する前に、既存の Issue か PR に含められないかを考える」をルールにしています。
  • (正直、Issue 自体がちょっと形骸化していて、「今日はたくさん片付けたな」という満足感を得るためのものになっている気がしてなりません)

ドキュメント管理リポジトリ

• 開発のリポジトリが汚れるのを防ぐために分けました。
  • 皆さんあるあるだと思いますが、生成 AI はすぐにドキュメントを書いて残してくれます。そしてこれまでではありえなかったことに、その量に溺れます。 機能ごとの資料 (設計書・プラン)、開発全般の資料、オンボーディングや手順書などで、気が付けばとんでもない量の文字がリポジトリを埋め尽くします。
  • さらに生成 AI は「裁定」「正本」「PR #○○」のような開発の固い言葉が好きで、指定しないとコードのコメントにも山ほど書き込みます。実際、コメントを横断で整理したときは、ある範囲 (約 300 ファイル) だけでコメントが 4 割近く減りました。
  • そこで、開発のリポジトリには対応中の機能のドキュメントだけを置き、終わったものはすべてアーカイブ (後から探せることが目的) に移すようにしました。移動の手間はかかりますが (移す作業はスクリプトにしています)、開発のリポジトリには「決定事項だけを短く書いた設計ドキュメント」と「全体のドキュメント (バックエンド・データベース・ERD などの括り)」だけを残し、そのメンテと参照に絞っています。
• 本当に必要な場面でだけ、ドキュメントを調べに行かせます。
  • 今のモデルは賢いので、情報が「それなりに」揃ったところで調べるのを切り上げてくれます。それでも、コンテキストを拾いすぎると利用枠を圧迫するだけです。新しいセッションを始めて、数回の調査を挟んだ時点でコンテキストが 15% を超えていたら取りすぎ、というのが私の感覚です (モデルや effort にもよります)。
  • 毎回広く深く理解してもらう必要はないので、深い調査は自分から頼んだときだけにするべきです。ドキュメントをリポジトリ間で移し、適宜まとめ直す運用は手間がかかりますが、整理も依頼もスムーズになったと感じています。

開発

superpowers と 3 つの進め方

開発には、引き続き superpowers を使っています。

superpowers を使った開発は、今は大きく 3 つの進め方に落ち着いています。私がやり取りするメインのセッション (ここでは「コントローラー」と呼びます) が全体を仕切り、実際の実装を誰にどうやらせるかが進め方ごとに違います。

• SDD (サブエージェント駆動): 設計書とプラン (実装計画書) を書かせ、Task ごとに新しいサブエージェントに実装させます。基本は仕様書どおりに進めます。
• パッチ方式: プランを書く前に、別の作業場所で一度丸ごと試作させます。その差分を Task ごとのパッチに切り分け、本番の実装では「パッチを当てて確かめる」だけにします。
• ダイレクト: 設計書もプランも作らず、コントローラーがそのまま実装します。ただし、テストを先に書くこと (TDD) と Codex のレビューは省きません。省くのは書類とサブエージェントだけです。

3 つの進め方は「誰が実装するか」が違い、私が止める所は同じ

どの進め方でも、設計・プランの承認と、追加レビュー・実機での確認・マージは私がやります (ダイレクトは設計を飛ばすので、止めるのは後ろの 1 か所だけです)。

使い分け

どの進め方にするかは、仕事の中身を見て最後は私が決めています。以前は Claude に任せていたのですが、後で書く大きな失敗があってから、プランを作り始める前に Claude から提案させて私が選ぶ形にしました。

役割ごとのモデル

どの進め方でも、役割ごとのモデルは決めています。コントローラーはいちばん賢い Fable にして、その分の枠を判断に残すのが狙いです。

ポイントは、レビューを作った側と別のモデルにすることです。同じモデルだと、同じ見落としを共有してしまいます。実際、同じ変更を Codex と Fable にレビューさせたら、指摘が 1 件も重ならなかったこともあります。

うまくいったこと

パッチ方式がいちばんハマったのは、挙動を変えない大きなリファクタでした。正しさを「既存のテストが全部通ったままか」で測れるので、試作の段階で全体のテスト (今は約 7,700 件程度) を通しておけば、本番の実装は「パッチが当たって、件数が合うか」を確かめるだけになります。

• ある機能では数千行あった 1 つのページのファイルを、2 回に分けて40%ほど割りました。2 回目は Task ごとのレビュー 8 回がすべて一発で通り、重い指摘は 0 件でした。
• DB の接続まわりの改修 (並行処理が絡む、動かさないと確かめられない種類のもの) では、22 Task を 1 セッションで終え、直しの往復は 1 回だけでした。
• 別の機能では、パッチを当てる作業そのものは 10 分で全 Task が通りました (ただしこの回は、全体としては失敗です。後で書きます)。

SDD は、コンテキストの使い方を詰めてから安定しました。

• サブエージェントの報告を「状態・件数・懸念」の 5 行にして詳細はファイルに逃がすようにし、1 つの PR を 1 つのセッションで終えるようにしたところ、Task あたりのコンテキストが 108K から 67K まで減りました。
• 最後に設計書と実装を 1 項目ずつ突き合わせるようにしてからは、PR を出す前に私がdev実機で退行を見つけた件数が 0 件の回も出ています。
• コード全体のコメント整理のような「量が多くて機械的な横展開」も、約 300 ファイルを 11 Task に分けてやりきれました。ただこのあたりは早くやっておくべきでしたね、、

ダイレクトは、小さな不具合の修正・置き換えが済んだコードの削除・重複した処理の共通化を、設計書なしで 3 本まとめて出し、本番まで出せました。細かい修正を軽く回せるのがいちばんの利点です。

失敗したこと

パッチ方式: AI が勝手に進め方を変えた回

いちばん大きな失敗は、主機能の開発で起きました。

• Claude が私に確認しないまま、プランを書いている途中でパッチ方式に切り替えていました。
• しかも試作をコントローラーの Fable 自身がやったので、プラン作成だけで約 10 時間かかり、Fable の枠が一気に減りました (927 ターン、出力だけで 173 万トークン)。
• パッチを当てる作業は 10 分で終わったものの、その後のレビューと実機確認で 25 件の直しが入りました。試作の段階で回した Codex の 3 巡は、早く見つけることにはつながらず、レビューを二重にやっただけでした。
• 振り返ってみると、悪かったのは方式そのものではなく、「誰が試作したか」と「レビューをどこに置いたか」でした。ここから前に書いたモデルの分担を決め、「進め方を変えるときは、変える前に費用と時間の見込みを出して私に確認する」をルールにしました。

本番の実装が速くても、前の段に重い作業を抱えたら全体では負けます。

細かいところでは、次のようなつまずきもありました。

• 同じファイルを複数のパッチが変える Task をまとめて当てたら、途中の commit を切れなくなった (→ パッチごとに commit する)
• 試作の報告に書かれた件数の範囲があいまいで、プランの期待値が 4 か所ずれた (→ 対象のファイルの一覧と件数を一緒に書く)
• 挙動を変える部分だけは、試作の段階でももう 1 巡レビューが要った

SDD: サブエージェントを信じすぎた

SDD の失敗は、ほとんどが「報告をそのまま信じた」か「確かめる所を飛ばした」のどちらかでした。

ダイレクト: 小さく見えるのが落とし穴

• 「ファイルを動かすだけ」の小さい commit を 2 つ、Codex を通さずに積まれていました。後から通すと中程度の指摘が 2 件出ました。小さく見える変更ほど、レビューを飛ばしがちです。
• 例えばアップロードされた PDF を読むコードは、小さい修正のつもりが Codex のレビューが 4 巡続きました (処理時間・メモリ・例外の漏れ)。攻撃者が作れる入力を読むコードは、見た目が小さくてもダイレクトに向きません。
• 逆方向の失敗もあります。製品の外の道具 (後で書くデモ動画) に、製品と同じ重い進め方をそのまま当てられ、「動画を撮ってほしいのに、なぜテストのステップが要るの？」と突っ込む羽目になりました。

コードの大きさの管理

先に断っておくと、行数を管理すること自体は本質ではありません。一緒に置く理由があれば 1 つのモジュールが大きくなってもよいですし、無理に割ると、かえって同時に読まなければいけない範囲が広がることもあります。それでも行数の決まりを入れたのには、2 つの理由があります。

AI が書くコードは、指定しないと線形に大きくなる

AI は新しい処理を、いちばん近くにある大きいファイルの末尾に足しがちです。主機能の編集画面のファイルは、機能を足すたびに伸び、2 か月で 10 倍以上までほぼ一直線に大きくなりました。

実は結構最近までの話です

「なぜ大きいのか」を毎回確かめるのが大変

大きいファイルに手を入れるたびに、「この大きさには理由があるのか」を確かめるには、全体の設計書や機能ごとの設計書を読み直させるか、私が答えるしかありません。どちらも、コンテキストと私の時間を食います。

行数を「話し合うきっかけ」にする

そこで、行数を縛りではなく「理由を確かめる合図」として使う決まりを作りました。しきい値は 2 段です。下記は例です。

• 目安を超えたら、設計書の「置き場所と大きさ」の節 (設計書を作らない小さな変更なら PR の説明) に、なぜ大きくてよいのかを書かせます。
• 原則分割を超えたら、「基準表」に 1 件ずつ載っていないと、大きさを測るテストが CI で落ちます。基準表には、区分・理由・見直す条件・上限を書きます。
  • 維持: 一緒に置く理由がある。例えば「この順番で登録しないと参照が壊れるので、分けると依存が循環する」のように、共有している約束と、分けたときに増える負担を書く
  • 分割予定: 割ると決めた。ここには新しい処理を足さない
• 基準表を緩める方向に変えるとき (新しく載せる・上限を上げる・見直す条件を緩める・「維持」に変える) だけ、私の承認が要ります。行を消す・上限を下げるのは、AI だけで進めて構いません。

つまり、私と話し合うのは 「行数を超えたときすべて」ではなく、「大きいまま残すと決めるとき」だけ です。そして一度話し合った理由は、基準表の 1 行としてコードのすぐ隣に残ります。次にそのファイルを触る AI は、設計書を読み直さなくても、その 1 行で「なぜ大きいのか」「何が来たら見直すのか」を知ることができます。

うまくいっている点

• 理由を探しに行かなくてよい。基準表の 1 行で済むので、設計書を掘り返す往復が減りました。
• 「分割予定」が追記先にならない。AI がそこに処理を足そうとするとテストが落ちるので、自然と新しいモジュールや hook を作る方向に向かいます。
• 割って縮んだら上限も下げる。上限を大きく下回るとテストが落ちるので、空いた分がまた追記の余地になりません。上の編集画面も、割るたびに上限を下げてきました。
• 私が呼ばれるのは、判断が要るときだけ。「目安を少し超えたファイルをどう扱うか」「今回の変更で、別のファイルの見直す条件に当たったので仕分け直したい」のように、論点が絞られた形で相談が来ます。
• 行数以外の変化も拾える。見直す条件には「同じ流れの処理がもう 1 本増えたら共通化する」のような書き方をするので、行数が増えない変更でも判断し直すきっかけになります。

改善点・気を付けていること

• 行数だけ減らす「ずる」をしがち。コメントを消す・改行を詰める・意味の無い小さな関数に分ける、などです。決まりで禁じていますが機械では止めきれないので、レビューで見ています。数字が減ったことは、責務の問題が解けた証明にはなりません。
• 見直す条件は機械では拾えない。別のファイルへの変更で条件に当たることもあるので、設計とレビューで「変更していない対象」も見るように頼んでいます。
• 決まりを作る途中で、大事な項目が落ちた。最初に私に見せた案には「縮んだら上限を下げさせる」があったのに、Codex の意見で設計を書き直す間に消えていました。私が「件数は都度更新する形？」と聞いて気付き、後から足しました。設計を書き直したときは、書き直す前の案と突き合わせるようにしています。
• まだ仕分けていない既存のコードが残っている。決まりを入れた時点で既に大きかったものは「既存・未仕分け」として置いてあり、次に手を入れるときに「維持」か「分割予定」に仕分けます。大きなファイルの分割も、まだ段取りの途中です。このあたりは正直難しいところです。

開発のまとめ

結果を左右したのは、方式の良し悪しよりも「誰に何をやらせるか」の配置でした。

1. 方式より配置が効く。パッチ方式の失敗は、いちばん高いモデルに試作をやらせたことと、レビューを前倒しで二重にしたことが原因でした
2. パッチ方式は「動かさないと確かめられない設計」と「挙動を変えないリファクタ」に強い。試作で全体のテストを通しておけば、本番の実装は 10 分で済みます
3. SDD はサブエージェントの報告を信じすぎない。git はコントローラーだけが触り、報告は裏を取り、最後に設計書と突き合わせます
4. ダイレクトは「小さく見える」ことが落とし穴。レビューを飛ばしたり、攻撃されうる入力を甘く見たりしがちです
5. レビューは系統を 2 つにする。Claude と Codex では、見つけるものが実際に違います
6. 進め方を変えるのは、人が承認してから。方式を変えると、どのモデルの枠を使うかと時間が変わります
7. 進め方の重さは、作るものに合わせる。製品のルールを、製品の外の道具にそのまま持ち込まない

デザイン

アーティファクトの活用

画面を変える機能は、実装の前に Claude のアーティファクト (claude.ai 上に公開される HTML のページ) でモックを作らせ、見た目を決めてから実装に入っています。一度 OK を出したモックが「見た目の正」で、設計書はモックから書き写させます。

ここを曖昧にすると、実装・レビュー・スクショの確認を全部通っても「モックと違う」で戻ります。実際、設計書に「ヘッダーは現行どおり」と書かれてモックの並びが落ち、ボタンを逆の順番で実装されたことがあります。

どれぐらいこだわって依頼するか

結論から言うと、開発環境で動いている本物の画面を土台にさせるのがいちばん効きました。

• 最初は部品だけのモックを作らせていました。でも、実際の画面に置いたときの見え方が分からず、ある機能では 7 往復しました。「実際の画面ベースで」と頼んでからは、開発環境の画面を Playwright で取り込み (描画後の HTML と CSS を保存)、そこに要素を足す形になりました。
• 依頼文は「要件ごと」ではなく「画面ごと」にまとめます。要件ごとに頼んだら、2 つの要件が同じ場所に別々の枠を置いて衝突しました。
• 「利用者がその画面に着いたときの状態」で撮らせます。パネルの幅などは操作の経路で決まるので、画面を直接開くと違う見え方になります。
• 依頼文の先頭に「利用者向けの言葉 / 運営向けの言葉」の表を置きます。AI は「弊社」や設計書の節の番号を平気で画面に出しますし、絵文字と枠線で安っぽくしがちです。
• 放っておくと、文字だらけの画面になります (私の感想は「とりあえず表示している、AI で作ったサービス感」)。判定・件数・状態を先に見た目で表し、文章は補助に回すように頼んでいます。私が文言の案を渡したときも、そのまま貼らずに推敲させます。

初期のアーティファクトの使い方

中期以降のアーティファクトで細かく見る使い方、ほぼ画面の再現

最近の巡りにめぐって最終的にFigmaやCanvas型

どこまで、どのモデルで確認させるか

実装した後の確認は、「機械に数字で測らせる所」と「人の目で見る所」を分けています。

この分け方になるまでには、いくつか痛い目を見ています。

• 「寸法が合った = 完成」ではありません。ボタンの文字が左に寄っている、1 ステップ目に押せない「戻る」がある、といったことを私が指摘してから直したことがあります。今は「ボタンの文字は中央か・その操作は必要か・同じ種類の要素は揃っているか」を要素ごとに見るチェックリストを持たせています。
• 狭い幅だけ見て渡され、広い幅では要素が右端に押し出されていたことがあります。画面のテスト (jsdom) は配置を計算しないので、幅の確認はテストでは代わりになりません。
• 逆に、コントローラーがスクショを読みすぎるとコンテキストを食います (1 つの PR で 17 枚読んだことも)。判定は数字で、目で見るのは代表だけ、という線引きに落ち着きました。

モックを先に作る良さは、合意が目に見える形で残り、実装した後の「思っていたのと違う」が減ることです。一方で、モックの往復そのものに時間がかかるので、最初の 1 枚目から本物の画面を土台にするのがいちばんの節約です。

デモ動画

機能紹介のデモ動画も、Claude と一緒に作っています。これまでに 5 本 (文書のレビュー、記入欄の入力、白紙からの文書作成、カスタムプロバイダー、推論の深さの比較) を公開しました。

使っている道具とモデル

実物の サービス の画面を 4K で録画し、あとから字幕・ズーム・赤枠・カーソルを重ねて 1 本の動画にしています。

どんなステップで作っているか

私が確認するのは 4 回だけで、それ以外は Claude に進めてもらいます。素材と試走の結果は、アーティファクトの確認ページにしてもらって見ています。

動画を作るうえで大事にしていることは、次の 3 つです。

• 本物の AI で試走してから撮る。AI の出力は毎回変わるので、何度か回して「拾われる仕込み」「モデルで差が出る所」を確かめ、いちばん多かった形を使います
• 字幕は画面で実際に起きたことだけ。数字は撮った回の画面の値に合わせ、制度名や法令は事実を確かめます
• 試走で製品の不具合を見つけたら、製品を直してから撮る。動画のために素材を曲げません

撮影そのものは約 25 分ですが、このサービスでは試走に 2〜3 時間はかかります。時間の多くは「何を見せるか」を詰める部分に使っています。

うまくいかなかったこと

初回の後に、この流れを手順書とスキル (/demo-video) にまとめさせました。それ以降は、「デモ動画を作って」と頼むだけで同じ流れが始まり、毎回の振り返りもそこに積まれていきます。

最後に

手戻りをさせないために

半年ほどやってみて、いちばん効いたのは「同じことを 2 回言わない仕組み」でした。私が指摘したことは、その場で直して終わりにせず、「何が起きたか・なぜ駄目か・次からどうするか」の形でメモリに残させています。進め方についての指摘だけで、今数えてみると約70 件ほどあります。

続けていること (うまくいっているやり方)

• 設計 → プラン → 実装の境目は、必ず私が承認する。「続きを進めて」は白紙委任ではなく、「進めて」はマージの承認でもない
• 進め方を変えたいときは、変える前に「今のやり方 / 変えたいやり方 / 理由 / 費用と時間」を出させる
• 確認したいことは、最後の 1 通にまとめさせる (途中の報告に質問が混ざると、私が見落とす)
• 「完了しました」と言う前に、利用者の流れを入口ごとに自分で通させる
• サブエージェントには git を触らせず、報告は必ず裏を取る

続けて直していかないといけないこと

• 1 つの PR が終わるたびに、集計のスクリプトでコンテキストの使い方を種類別に数え、「Task あたり」「報告 1 通あたり」で前回と比べています。品質の側は、「PR の前に私が実機で見つけた退行の数」を見ています
• まだ直りきっていないものもあります。実装の報告は 5 行を守れるようになったのに、レビューの報告は平均 5,000 字ほどに膨らみます。画面の変更があるとスクショを読みすぎますし、コマンドの呼び出し回数も減りきっていません
• 2 台のマシンで別々に試したやり方は、表にして突き合わせ、「続ける / 試し続ける / 外す」を決めています。片方で効いたものをもう片方にも入れる、という流れです

AI に任せる範囲はどんどん広がっていますが、「どこで人が止めるか」と「指摘をどう残すか」を決めておくほど、安心して任せられるようになってきたと感じています。引き続き試行錯誤しながら、また機会をもって振り返れればと思います。