概要
AIコーディングは生産性が大きく向上する一方で、技術負債や理解負債が蓄積しやすいという問題があります。
普段自分が実践している、できる限り技術負債や理解負債を生まないAIコーディング手法について解説します。
対象読者
この記事の対象読者は普段の開発業務でAIコーディングツールを活用しているエンジニアです。
Claude CodeやCodex CLIを使っている方のほうが理解しやすい内容になっています。
筆者のバックグラウンド
最近は主にLLMを用いたアプリケーション開発に関わっています。
2023年頃からAIによるコーディングを積極的に取り入れています。
以下のようなメジャーなAIコーディングツールは一通り使ったことがあります。
- GitHub Copilot
- Roo Code
- Cursor
- Windsurf
- Google Antigravity
- Claude Code
- Codex CLI
最近メインで使っているツールはClaude Codeです。
普段書いてる言語はTypeScriptかPythonです。
ちなみに私は現在ほぼすべてのコードをAIコーディングエージェントによって生成しています。
個人開発はもちろん、私が契約しているすべての企業のプロジェクトにおいてAIコーディングエージェントを活用しています。
技術負債と理解負債について軽く説明
技術負債とは？
技術負債は昔からよく出てくる用語なので知っている方も多いと思います。
技術負債とは、短期的な開発スピードを優先した結果、コードの品質や設計が犠牲になり将来的な変更コストが増大していく現象のことです。
AIコーディングにおいては一度に生成されるコード量が多いので技術的な負債が蓄積するスピードが人間が開発していた時代よりも圧倒的に早いです。
その為、技術的な負債に対しては従来の開発手法以上に敏感になる必要があります。
理解負債とは？
こちらも最近話題の用語なので知っている方が多いと思いますが一応解説します。
理解負債とは、コードベースに対する開発者の理解が追いつかなくなる現象のことです。自分が書いていないコードが増えるほど「このコードが何をしているのか」「なぜこの実装になっているのか」がわからなくなっていきます。
「動いているからいいや」と何も考えずにAIの出してきたコードをそのまま受け入れているだけでは理解負債が一気に蓄積してしまいます。
理解負債が蓄積すると誰もプロダクトの仕様がわからない、重要な改修を行なうことが困難な状況になってしまいます。
AIが開発するから大丈夫では？ と思うかもですが、プロダクトの仕様や構造の理解が不十分だとAIに適切なプロンプトを渡すことができないのでAIで開発する場合でも理解負債は大きな問題になります。
事前準備
この記事で紹介するAIコーディングエージェントを用いた開発手法を実践する上で必要な事前準備について説明します。
必ずやっておくこと（必須）
- Claude Code を利用可能な状態にしておく
- Codex CLI を利用可能な状態にしておく
- ghコマンド を利用可能にしておく
できればやっておいたほうが良いこと（任意）
任意としましたが、以下の3つに関しては必須寄りです。特にWebフロントエンドの開発を行なう場合は Chrome DevTools MCP はあったほうが良いですしFigmaでデザインシステムを管理している場合は Figma MCP もあったほうが良いです。
Context7 MCP はAIコーディングエージェントが公式ドキュメントにアクセスするための手段として優れているのでこちらもすべてのプロジェクトでオススメです。
- Context7 MCP の設定
- Figma MCP の設定
- Chrome DevTools MCP の設定
後は必須ではないですが、以下のMCPもあると便利です。
ちなみにここに挙げたのはMCPの設定ですが、これらのMCPは Claude Code, Codex CLI 両方で使えるようにしておくことをオススメします。
過去に自分が書いたスクラップが一定の参考になると思いますので以下も載せておきます。
具体的な実施手順
ここから具体的な進め方を実際のサンプルを交えて解説します。
ただ案件のコードをそのまま出すことはできないので個人開発で運営している以下のサービスを例に解説します。
こちらは個人開発と言っても品質管理やテストコードなどもちゃんと用意してありますし十分に参考にできるかと思います。
1. 最初にClaude Codeに実装計画作成を依頼する
まずはGitHub Issueの詳細説明に人間がやりたいことを言語化して記載します。
以下は https://lgtmeow.com/docs/how-to-use のページを実装した際のIssueです。
課題の難易度によりますが、1つの新機能や新しいページを追加する場合はこのくらいの情報量が必要だと思います。
他にも何パターンか載せておきますので参考にしていただければと思います。
すでに実装されている似たような機能がある場合は以下のようにシンプルな説明で済むケースもあります。
以下のように依頼用のプロンプトファイルをマークダウンで作成します。
自分の場合はプロジェクトのディレクトリに user-prompt/ というディレクトリを用意してその中にファイルを用意しています。
ちなみにGitの管理対象外です。 user-prompt/202601211804_issue441.md のようになります。
基本的には内容は https://github.com/nekochans/lgtm-cat-frontend/issues/441 の部分が変化するだけですべて同じです。必要な情報はすべてIssueに記載します。
実装計画作成用のプロンプトファイル例（user-prompt/202601211804_issue441.md）
# はじめに
**文章を読み飛ばさずに最後まで読んで頂きたいです。**
# 依頼内容
以下のGitHub Issueの対応をお願いします。
https://github.com/nekochans/lgtm-cat-frontend/issues/441
解決に必要な情報は全てGitHub Issueの中に含まれています。
Issue内の情報も全て `gh` コマンドで取得して読み飛ばさないように細心の注意を払って実装計画を立ててください。
# 注意事項
## 存在しないファイル等を捏造しない
存在しないファイルをimportしたり、存在しないDBのカラムを捏造したりすると重大な問題が発生しますので、そのような事はしないようにお願いします。
## 全ての関連ファイルに必ず目を通す
GitHubのIssueやプロンプトに載っている@ で提示したファイルは実装時に必ず参考にする必要がございます。
よって **全ての関連ファイルに必ず目を通して** 実装計画を作成して頂きたいです。
## 不明点は必ず確認する
**不明点は必ず私に聞いて頂きたいです。**
## ライブラリやフレームワークは常に最新の書き方を調査する
既知のライブラリでもベストプラクティスが変わっている場合や非推奨になっている機能が増えている場合がございます。
**必ず現在利用しているバージョンを調べて、そのバージョンの最適な書き方を調査してから実装計画を作成して頂きたいです。**
### 調べる際の手段
#### Context7 MCPでドキュメントを調査する
公式ドキュメントを参照する際はContext7 MCPを利用可能です。
#### next-devtools MCP
Next.jsのドキュメントを調査する際に利用可能です。
#### figma-dev-mode-mcp-server
FigmaのMCPサーバーです。Figmaのデザインを調査する際は必ずこれを利用してください。
#### Web検索
他のMCP等が利用出来ない場合はWeb検索ツールを用いてファクトチェックを実施してください。
## その他
- 品質管理の手順は必ず実装計画にのせる
- 動作確認に必要なサーバーは起動している前提で問題なし
以下のMCPサーバーを動作確認時に利用出来るので動作確認時は必ず利用するようにお願いします。
- chrome-devtools
ここまで準備ができたらClaude Codeの新しいセッションを起動して、上記のプロンプトファイルを読み込んで実装計画を依頼します。
私は毎回以下のテンプレートに従って依頼しています。
ultrathink: お願いがございます。
@user-prompt/202601211804_issue441.md を参考に `design-docs-for-ai/` にAI向けの実装計画をマークダウン形式で作成して頂きたいです。
実装計画の粒度ですが、作成した実装計画を見れば誰でも実装出来るレベルでお願いします。
実装計画の作成後はご自身で **レビューと改善を3回繰り返して頂きたいです** どうぞよろしくお願いします。
ultrathink という単語に関してはマジックワード扱いになっていて、Claude Codeに徹底的に推論してもらう効果があります。
こちら をご覧ください。
実装計画の作成時には常にこの ultrathink マジックワードを含めるようにします。
これも @user-prompt/202601211804_issue441.md の部分以外は毎回同じです。
**レビューと改善を3回繰り返して頂きたいです** という部分に関しては以下の記事を参考にしました。
実際にアウトプットの品質が上がったのでオススメできる手法だと思います。
design-docs-for-ai/issue441-github-app-documentation-page-implementation-plan.md のようなマークダウンファイルが出力されます。
ファイルの中身は以下のようなファイルです。
見てわかるとおり以下のようにこの実装計画を見れば記憶を失ったAIエージェントでも実装できるレベルで詳細に書かれています。
- 具体的にどのファイルを修正する、どのようなファイルを追加するのか具体的に記載してある
- どのような状態になったら完了なのかを示すチェックリストが記載してある
- 品質管理（動作確認も含む）の手順が記載してある
基本的にはこの計画通りに実装すれば要件を満たせるような形になっていますが、中には一度実装してみないとわからないケースが存在します。
このような場合は以下のように対応します。
- 例1: CSSのスタイリングがFigmaのデザイン通りになっているかどうかは実装してみないとわからない場合がある
- 一度完成した後に こちら のようにCSS調整用の計画を別で作成することで対応します
- 例2: LLMで何らかの成果物を生成する機能の場合、生成された成果物の品質が要件を満たしているかどうかは実装してみないとわからない
- このケースの場合は成果物の品質評価基準を計画内に明示して基準をクリアするまで修正を繰り返すような計画にします
- 品質管理の手順が複雑になりやすいので複雑な品質管理でかつ再利用を行なう場合は Agent Skills として定義しておくのがオススメです
2.1 1 で生成された実装計画をレビューする
生成された実装計画を人間がレビューします。
ただ実装計画はかなり具体的で実際にどのようなソースコードを記載するのかまで厳密に定義されています。
コード1行1行まで隅々まで見ると時間がいくらあっても足りないので以下のポイントを中心にレビューします。
- 実装計画の内容がGitHub Issueに記載したビジネス要件を満たしているか
- 重要なビジネスロジックがテスト可能な構造になっており、必要なテストケースが網羅されているか
他にも余裕があれば以下の項目も確認します。
- アーキテクチャ違反の設計を行なっていないか
- すでに存在する共通機能を利用しないで新規で作成していないか（DRY原則への違反チェック）
ただこれらの項目は後の工程で実行するCodexによるレビューで検出される可能性が高いです。
人間は人間にしかできないビジネスロジックを実現できているかと、そのために必要なテストケースが実装計画に含まれているかを中心にレビューするのが良いと思います。
それからもう1つ重要なポイントがあります。
それは不明点を徹底的に Claude Code に質問することです。
ここで徹底的に疑問点を潰しておかないと、それがそのまま理解負債の原因になってしまいます。
ただあまりにもここでレビュー指摘が多かったり、そもそもビジネス要件をAIが誤解している場合GitHub Issueに載せた情報が不十分だった、もしくは間違えている可能性が高いので 1 からやり直したほうが早かったりするケースも多いです。
2.2 Codexに 1 でClaude Codeに作成してもらった実装計画のレビューを依頼する
人間レビューが終わったらCodexに 1 でClaude Codeに作成してもらった実装計画のレビューを依頼します。
Codexのセッションを新規で作成して、以下の定型文を元にCodexにレビューを依頼します。
お願いがございます。
@user-prompt/202601211804_issue441.md を元にClaude Codeに実装計画を作って頂きました。
以下のファイルです。
@design-docs-for-ai/issue441-github-app-documentation-page-implementation-plan.md
この実装計画のレビューを行いレビュー結果を `design-docs-for-ai/` 配下にマークダウン形式で追加して頂きたいです。
レビューの際は必ず関連情報を確認してからレビューを行うようにお願い致します。
- GitHubのIssueやPRがあればghコマンドで取得
- FigmaのリンクがあればFigmaのMCPを使って取得
- 特定のライブラリの利用方法を調べる際はContext7のMCPで調べる
- その他不明点はWeb検索を行い正しい情報を調べる
必ず関連情報をこれらのツールを利用して調べた上でレビューの実施をお願い致します。
@ から始まるファイルパスの部分はそれぞれ以下のように置き換えます。
-
@user-prompt/202601211804_issue441.md-
1でClaude Codeに実装計画を作成してもらう際に利用したプロンプトファイルのパスに置き換えます。
-
-
@design-docs-for-ai/issue441-github-app-documentation-page-implementation-plan.md-
1でClaude Codeに作成してもらった実装計画のファイルパスに置き換えます。
-
私はCodexを実装計画のレビュー用AIとして利用していますが以下の部分がかなり重要です。
レビューの際は必ず関連情報を確認してからレビューを行うようにお願い致します。
- GitHubのIssueやPRがあればghコマンドで取得
- FigmaのリンクがあればFigmaのMCPを使って取得
- 特定のライブラリの利用方法を調べる際はContext7のMCPで調べる
- その他不明点はWeb検索を行い正しい情報を調べる
必ず関連情報をこれらのツールを利用して調べた上でレビューの実施をお願い致します。
このように書いておかないとCodexが関連情報を見ないでレビューを行なってしまい、的外れなレビュー結果が出力される可能性が高いです。
2.3 Codexからのレビュー結果を人間がレビューする
design-docs-for-ai/ 配下にCodexからレビュー結果がマークダウン形式で出力されます。
以下のようなファイルパスになると思います。
@design-docs-for-ai/issue441-github-app-documentation-page-implementation-plan-review.md
このファイルを初回のレビューだけで良いので人間がチェックします。
理由は以下のような問題が起きる可能性があるからです。
-
Codexが仕様の読み間違いをしていて的外れなレビューコメントを記載していることがある - 上記に似ているか、仕様を深読みしすぎていて考慮しなくて良い問題点にまで指摘をしてしまうことがある
- 素直にエラーで終了したほうがシンプルなケースでフォールバックを追加するように促すレビューコメントを追加してしまうことがある
自分の印象だと特に 2, 3 が多い印象です。
このままClaude Codeに渡すと無駄に複雑な実装計画になってしまう可能性があるので、ここで不要と思われる指摘はCodexと会話を行ない指摘を削除してもらったりします。
2.4 Claude Codeにレビュー結果を伝えて実装計画を修正してもらう
Codexが作成したレビューコメントが記載されたファイルを元にClaude Codeに実装計画の修正を依頼します。
ちなみに多くのケースでここでClaude Codeのコンテキスト使用量を使い果たしていることが多く、このままでは性能低下が免れないので、会話をリセットするかClaude Codeのセッションを新規で起動するのがオススメです。
余談ですが以下の記事のように常に残りのコンテキスト使用量を表示させておいたほうが良いです。
ultrathink マジックワードを含めて以下のように定型文で依頼します。
ultrathink: @user-prompt/202601211804_issue441.md を元にあなたに作成して頂いた以下のファイルのレビュー結果をまとめました。
@design-docs-for-ai/issue441-github-app-documentation-page-implementation-plan.md
以下がレビュー内容が記載されたファイルでございます。
@design-docs-for-ai/issue441-github-app-documentation-page-implementation-plan-review.md
レビュー内容を反映して頂きたいです。
- @design-docs-for-ai/issue441-github-app-documentation-page-implementation-plan.md
-
1でClaude Codeに作成してもらった実装計画のファイルパスに置き換えます。
-
- @design-docs-for-ai/issue441-github-app-documentation-page-implementation-plan-review.md
-
2.22.3でCodexが作成したレビュー結果のファイルパスに置き換えます。
-
2.5 Codexに 2.4 で修正してもらった実装計画のレビューを再依頼（問題がなくなるまで2.4 〜 2.5を繰り返す）
また以下のような定型文でCodexに依頼を行ないます。
@design-docs-for-ai/issue441-github-app-documentation-page-implementation-plan-review.md を参考に以下の実装計画を修正して頂きました。
@design-docs-for-ai/issue441-github-app-documentation-page-implementation-plan.md
再度 `design-docs-for-ai/` にレビュー結果を先程とは別のマークダウンファイルに追加をお願いします。
レビューの際は必ず関連情報を確認してからレビューを行うようにお願い致します。
- GitHubのIssueやPRがあればghコマンドで取得
- FigmaのリンクがあればFigmaのMCPを使って取得
- 特定のライブラリの利用方法を調べる際はContext7のMCPで調べる
- その他不明点はWeb検索を行い正しい情報を調べる
必ず関連情報をこれらのツールを利用して調べた上でレビューの実施をお願い致します。
以下のようなファイルができるので再度Claude Codeに修正を依頼します。
@design-docs-for-ai/issue441-github-app-documentation-page-implementation-plan-review-v2.md
ultrathink: @user-prompt/202601211804_issue441.md を元にあなたに作成して頂いた以下のファイルのレビュー結果をまとめました。
@design-docs-for-ai/issue441-github-app-documentation-page-implementation-plan.md
以下がレビュー内容が記載されたファイルでございます。
@design-docs-for-ai/issue441-github-app-documentation-page-implementation-plan-review-v2.md
レビュー内容を反映して頂きたいです。
Claude Codeはコンテキスト画面を使い果たしている可能性が高いので、新しいセッションを起動して上記の定型文で依頼します。
Codexに関しては3回程度ならやり取りしても問題ないことが多いですが、それ以上やり取りが続く場合は新規セッションを立ち上げて会話をリセットしたほうが安定します。
Codexが作成するレビュー結果のファイルですが最終的には以下のように指摘がない状態になります。
# Issue 383 テストコードの書き方統一 設計レビュー 再確認 5
## 結論
大きな不整合は見当たらず、この内容で実装に進める状態です。
## 確認した関連情報
- GitHub Issue #383 を確認済み(gh issue view 383 -R nekochans/lgtm-cat-frontend)
- GitHub PR は該当なし(gh pr list -R nekochans/lgtm-cat-frontend)
- Vitest ドキュメントを Context7 で確認(it.each と hooks の用途)
- Figma リンクは設計書内に見当たらず確認対象なし
## 良い点
- ネスト describe 禁止と should 必須が本文と成功基準で一致している点
- 変更内容の一覧表にコメント英語化対象が反映され、作業範囲が明確な点
- 最終確認にコメント英語化の対象ファイルが明記されている点
## 指摘事項とリスク
- 現時点で追加の指摘事項はありません。
## 質問
- 追加の修正希望があればお知らせください。
この状態になるまでひたすら実装計画のファイルの修正を行ないます。
この 1 から 2.5 までのステップが最重要です。
ここに労力の9割以上を注ぎ込むイメージです。
ちなみにレビューコメントが記載されたマークダウンファイルはGitでは管理していません。
管理すると過去のレビューコメントでコンテキストが汚れる可能性が高いので、レビューコメントはあくまで一時的なものとして扱います。
3. 新しいClaude Codeのセッションを起動して実装計画を元に実装を依頼する
新しいClaude Codeのセッションを起動して以下のように依頼します。
お願いがございます。
@design-docs-for-ai/issue441-github-app-documentation-page-implementation-plan.md の通りに実装をお願いします。
テスト実行に必要なサーバーは起動していますので、品質管理の実行までどうぞよろしくお願いします。
実装後はご自身で **レビューと改善を3回繰り返して頂きたいです** どうぞよろしくお願い致します。
実装時間は課題の難易度にもよりますが10分〜30分くらいはかかるので、私はこの間に別の課題の準備を進めていたりします。
実装計画には動作確認の手順を必ず含めるようにしています。
しかしClaude Codeが動作確認手順をスキップしてしまったり（特にPlaywright MCPなどを使ったブラウザテストがスキップされる傾向あります）することがあるので、その場合は動作確認を促します。
コンテキスト使用量がいっぱいだと予期せぬ動作をする可能性があるので、その場合は面倒でも新しいセッションを起動して動作確認を促すようにしたほうが安定します。
実装計画のマークダウンはPRを出す際にはGitの管理対象にしていますが、これも実装が完了したら過去分は定期的に削除しています。
これもコンテキストの肥大化を避けるためです。当時どのような設計にしたかはPRを見れば残っているのでそれで十分と考えます。
もちろん仕様が複雑な場合は永続的にメンテナンスを行なう仕様書を別途残します。（これが必要な場合はドキュメント作成も実装計画に含めれば問題ありません）
4. Claude CodeにPR作成を依頼
実装完了したら以下のような定型文でPR作成を依頼します。
staging ブランチの部分はメインで使っているブランチ名に置き換えてください。
PRの作成をお願いします。
コードの差分に関しては現在のブランチと `staging` ブランチの差分をご覧ください。
GitHubへのコミットとプッシュは完了しております。
以下のPRルールとPRのテンプレートご参照ください。
@CLAUDE.md
@.github/PULL_REQUEST_TEMPLATE.md
PRの説明に関しては実装計画のマークダウンファイルや解決対象のIssueを参考に何故この実装になっているのか？
という説明を重点的に記載するようにお願いします。
PRのタイトルは変更内容から適切なタイトルを作成して頂きたいです。
どうぞよろしくお願いします。
@.github/PULL_REQUEST_TEMPLATE.md が存在するかどうかはプロジェクトによると思いますので、ここは適宜読み替えてください。
過去PRは過去の状況をコンテキストとしてAIに伝える際に利用されるので、PRの説明に嘘が混ざっていると後々のトラブルの原因になります。
よってPRには人間がコーディングしていた時代と同じく最低限、実装した際の経緯や実装の概要説明等は記載しておいたほうが良いです。
PRの説明やタイトルが不適切だと感じたら、その場でClaude Codeに修正を依頼しましょう。
以下に実際に作成されたPRの例を載せておきます。
5. CodeRabbitによるPRのレビュー
私の環境だとPRが作成されOpen状態になると CodeRabbit が自動的にPRのレビューを行ないます。
ここで利用するのはCodeRabbit以外でも問題ありません。
私は使ったことはないのですが、例えば Greptile なども同じように利用可能だと思います。
これらのツールはレビューに特化したAIエージェントとして作り込まれているので開発者体験が良いです。例えば以下のような点が便利です。
- 対象のコードブロックに対してコメントを追加してくれる
- 修正後のコミットメッセージにレビューコメントを含めると自動的にレビューコメントを
resolved状態に更新してくれる（含めなくても自動で判断してくれる場合が多い） - 標準でレビュー用AIエージェントがWeb検索機能を利用可能なので、最新情報に基づいたレビューを行なってくれる
これらのレビュー用エージェントは費用が少々高いので以下のようなワークフローを用意しておいて（Codexを使った例です）レビューを行なうのも1つの手です。
name: Codex Auto Review on PR Open
on:
pull_request:
types: [opened, synchronize]
jobs:
codex:
runs-on: ubuntu-latest
concurrency:
group: ${{ github.workflow }}-${{ github.event.pull_request.number }}
cancel-in-progress: false
permissions:
contents: read
outputs:
final_message: ${{ steps.run_codex.outputs.final-message }}
steps:
- name: Checkout repository
uses: actions/checkout@v6
with:
ref: refs/pull/${{ github.event.pull_request.number }}/merge
- name: Pre-fetch base and head refs for the PR
run: |
git fetch --no-tags origin \
${{ github.event.pull_request.base.ref }} \
+refs/pull/${{ github.event.pull_request.number }}/head
- name: Install mcp-proxy for SSE bridge
run: pip install mcp-proxy
- name: Run Codex
id: run_codex
uses: openai/codex-action@v1
with:
openai-api-key: ${{ secrets.OPENAI_API_KEY }}
codex-args: |
--config mcp_servers={"lgtmeow"={"command"="mcp-proxy","args"=["https://api.lgtmeow.com/sse"]}}
prompt: |
リポジトリ: ${{ github.repository }}
PR番号: ${{ github.event.pull_request.number }}
このPRの変更内容をレビューしてください。
マージ可能な品質と判断した場合は、lgtmeow MCPサーバーの get_random_lgtm_markdown でLGTM画像を取得し、レビュー結果に含めてください。
問題がある場合は、改善点を具体的に指摘してください。
PRタイトルと本文:
----
${{ github.event.pull_request.title }}
${{ github.event.pull_request.body }}
post_feedback:
runs-on: ubuntu-latest
needs: codex
if: needs.codex.outputs.final_message != ''
permissions:
issues: write
pull-requests: write
steps:
- name: Post review comment to PR
uses: actions/github-script@v7
env:
CODEX_FINAL_MESSAGE: ${{ needs.codex.outputs.final_message }}
with:
github-token: ${{ github.token }}
script: |
await github.rest.issues.createComment({
owner: context.repo.owner,
repo: context.repo.repo,
issue_number: context.payload.pull_request.number,
body: process.env.CODEX_FINAL_MESSAGE,
});
6. 5 のCodeRabbitのレビューコメントをClaude Codeに渡して修正を依頼
Claude Codeを新規セッションで起動して以下のように修正依頼を実施します。
以下のレビューコメントの指摘内容の対応をお願いします。
https://github.com/nekochans/lgtm-cat-frontend/pull/442#discussion_r2712293897
ただこのレビューコメントの内容ですが鵜呑みにするのは危ないです。
以下のように適切ではないレビューコメントがあります。特にコンテキストを無視した一般論とWeb上のドキュメントを読み違えたことによるハルシネーションがそこそこ多いなという印象があります。
いくつか例を載せておきます。
- 現在のコンテキストを無視した一般論に基づく指摘（PRの説明をきっちり書いても残念ながらある）
- Web上のドキュメントを読み違えたことによるハルシネーション
今後改善されていく可能性は高いですが、レビューコメントを鵜呑みにするのは危険だと思います。
ちなみに実装計画のレビューを徹底的にやっているので、CodeRabbitのレビューコメントはそこまで多くならないハズです。
もしも大量のコメントがつく場合は以下のような点を見直したほうが良いです。
- 実装計画のレビューの精度
- 実装計画の粒度が大きすぎるので小さな単位に分割する
7. 最終確認とPRのマージ
すべてのレビューコメントを解決したら人間が最終確認を行ない（そこまで時間をかけずに全体をさっと見渡すで十分）問題なければPRをマージします。
以上が私が実践しているAIコーディングの手順になります。
成果物が思い通りにならない場合の対処法
思ったとおりの品質にならない場合は主に以下の内容を見直します。
実装計画の単位を分割する
実装計画の粒度が大きすぎるとAIは仕様を勘違いしたり、ミスも多くなりがちです。
その場合は実装計画の分離を行なうのが効果的です。
バックエンド、フロントエンドだと以下のような単位が目安になります。
- バックエンドは1つのAPIエンドポイントを扱うのが限界
- （例1）REST APIだと
/usersのPOSTだけ実装 + テストコードくらいが限界 - （例2）
/usersエンドポイントのCRUDをすべて実装するのは粒度が大きすぎる - （例2）仕様が複雑な場合はまずハッピーパスだけ実装、そのあとでエラーパスの実装計画を立てるなどの工夫が必要
- （例1）REST APIだと
- フロントエンドは1つの新規画面を作成だと粒度が大きい可能性が高い
- フロントエンドはコンテキストの消費が大きいことが多く、1つの画面を1つの実装計画で作成するのは粒度が大きすぎる可能性が高い
- こちらのアプリの使い方ページ のようなバックエンドへのAPI通信が発生しない場合なら1つの実装計画で作りきれる可能性がある
- バックエンドとの連携がある場合は1つの実装計画で作り切るのは難しい
- UI実装に必要なComponentを実装してStorybookで確認する計画、バックエンドとの繋ぎ込みを実装する計画、最後に2つを結合する計画のように分割するのがオススメ
以下はかなり前に私が書いた記事ですがこの部分で大きなPRを分割するための考え方が記載されています。
基本的には同じ考えでAIコーディングにおいても実装計画を分割するのが効果的です。
会話をリセットする、もしくは新規セッションで新しく開始する
AIと開発をしているとAIが出してきたアウトプットに対してさらに修正を依頼したくなることがあります。
しかし、コンテキストが肥大化していると思ったとおりのアウトプットを得られなかったり、さらに仕様の勘違いをして「何でそうなった？」と感じるアウトプットが出てくることがあります。
最近のモデルは賢いので以前よりはかなりマシになりましたが、それでもコンテキストが肥大化すると性能が低下するというのは間違いなさそうです。
よって過去の会話を引き継いだまま長期間会話するよりも、決定事項などを実装計画などのドキュメントに落とし込んで、資料を見れば会話履歴を持たないAIでも理解できる状態を作ることがベストだと思います。
Claude Codeに実装、Codexにレビューを依頼する理由
抽象的推論や数学的推論の各種評価指標ではCodexで利用される GPT-5.2-Codex がClaude Codeで利用される Claude Opus 4.5 を上回っています。一方で実世界のコーディングタスク（SWE-bench Verified等）では両者は拮抗しており、単純にどちらが上とは言い切れない状況です。
開発がスムーズにできることは評価指標の数値だけでは決まりません。
Claude CodeにはCodexと比べて以下の点で優れていると感じています。
- カスタマイズ性が高い
- 実行して欲しくないコマンドを
permissions.denyで宣言的に指定可能（Codexにも.rulesファイルによる類似機能はあるが、Claude CodeのほうがJSON設定ファイルにGlobパターンで柔軟に記述できる） - 特定プロジェクトだけ有効なMCPサーバーを指定可能
- 実行して欲しくないコマンドを
- 実装計画の出力が具体的で読みやすい
- Claude Codeが出力する実装計画は具体的なファイルパスや修正内容まで明示されており、そのまま実装に移れるレベルで詳細に書かれている
- Codexは推論能力が高い反面、出力する実装計画が抽象的になりがちで読みにくい傾向がある
- ドキュメントが充実している
- ベストプラクティス が公開されていたり、ドキュメントが充実しているので使い方に迷わない
ちなみにClaude Codeの ベストプラクティス だとPlanモードを推奨しています。
しかし私は以下の理由でPlanモードは使わずに、この記事で紹介した方法で実装計画を作成してもらう方法を採用しています。（実質的にPlanモードを利用しているのと変わらないと思っています）
- Planモードのインターフェースが実装計画を人間がレビューする前提のような作りになっている
- Planモードで実装計画が完了した後の選択肢が、会話履歴をリセットして実装、会話履歴を保持して実装、実装計画の変更を依頼のいずれかしかない
- つまりPlanモードには外部AIへのレビュー連携の導線がない
- 私の場合はPlanモードで作成した実装計画をCodexにレビューしてもらうスタイルを取っているのでマークダウンファイルを任意の場所に置けたほうが良い
またCodexは実装推論能力は高いですが以下のような点で不便に感じています。
- ツールの使い方が上手くない
- 新しいライブラリでの開発なのにContext7のMCPなどが設定されているのに使わない
- 他にも明確に指示がないととにかくツールを使わないで自らの推論能力だけで何とかしようとする傾向がある
- 優れた推論能力を持つ故の弱点
- 出力する実装計画が抽象的すぎて読みにくい
- ツールの使い方が上手くないのとも被るが自分の推論を過信する傾向があるなと感じることがある
- こちらが間違っていると指摘しても公式ドキュメントを見に行かず自らの自説に固執する
- テストの実行中なのにテストが終了したと報告する
- これはClaude CodeでもありますがCodexが特にやりがちに感じます
- E2Eテストなどの時間がかかるテストだと特にこれをやりがちです
- 融通が効かない
- デフォルトだと
KEY、SECRET、TOKENのいずれかを名前に含む環境変数はCodexの実行環境に同期されない- セキュリティを重視しているのかもしれないが必要な環境変数が同期されないのは不便
- direnvを利用したプロジェクトで上手く環境変数を渡せない問題
- その割には
.envや.envrcなどの機密情報が含まれるファイルを簡単に読み込もうとする
- デフォルトだと
このような理由からCodexは高い推論能力を活かしてコードレビューに活用するのが一番良い使い方だと感じています。
多分、自分がやっているのがWebアプリケーションの実装が中心でその場合外部ツールを使いこなすことが極めて重要なのでこの評価になっていると思います。
ロジックだけで完結するような課題だと推論能力が高いCodexのほうが良いケースはあると思います。
実際に技術負債や理解負債は溜まっていないのか？
若干タイトル詐欺のようになってしまいますが、技術負債や理解負債がゼロという状況ではありません。
ただそれでもフロントエンド、バックエンドともにフレームワーク、ライブラリのバージョンは最新に近い状態を保てていますし、コードの品質も高い状態を維持できています。（ちょうどこの方法を開始して1年くらいは経過しています）
しかも技術的な負債によって事業の成長に関連する開発を止めたりすることも起きていないです。
なのでスピードを維持しつつ、一定の品質管理はできている状態と考えています。
AIコーディングにおいては内部品質の低下による開発スピード低下の影響がもの凄いので、それでも定期的なリファクタリングは必須です。
1か月に1回程度はリファクタリング用のIssueを作ってAIコーディングでリファクタリングを実施しています。
今後の改善
1〜6のステップを自動化
人間が介入する部分を減らしていきたいと考えています。
人間介入がなくなれば自動化ができる目処が立ちますが、現時点だとコードの品質面はともかくとしてビジネスロジックを本当にちゃんと実装できているのか？ という点が不安です。
ビジネスロジックの正しさをどう担保するのか？ という部分が今後の課題になると思っています。
コーディングエージェントの並列実行について
私は複数の組織で仕事をしているので、複数のTerminalを起動して案件ごとのClaude CodeやCodexのセッションを立ち上げて仕事をしています。
そういう意味だと常に3から4並列でAIコーディングを回して開発をしていると言えます。
しかし Vibe Kanban や git worktree を利用したよく言われているような並列実行は実施していません。
私の仕事の特性上のある開発タスクを完了させるためには別のビジネス上の課題を解決したりする必要があったり開発タスク同士の依存関係があるケースが多くなかなか並列実行を有効活用できるケースが少ないと感じます。
あと思っているのは並列実行を有効に行なうためには人間のレビューを何とかして省略できる必要があると感じます。
さきほども挙げたビジネスロジックがちゃんと意図したとおりに実現されているか？ という点をどう担保するのかという問題やコード品質を完全に数値化して1つ1つのコードを見なくても良い状態を作るようにする必要があると感じます。
おわりに
この記事で最も伝えたかったのは、実装計画の作成とレビューに労力の大部分を注ぎ込むということです。
ここさえしっかりしていれば、実装自体はAIに任せても技術負債や理解負債が蓄積しにくくなります。
この方法はあくまでも2026年2月現在の方法になります。
1年後には全然違う開発プロセスになっている可能性があります。その時にまたこの記事を見返してみます。
以上になります。最後まで読んでいただきありがとうございました。
Discussion