実践フルAIコーディング

この記事は 実践で フル AI コーディングするための考え方とノウハウを凝縮したものです。筆者が持ってるノウハウはほぼ全て書いたつもりです。

Algomatic アドベントカレンダー 12/8 です。

https://note.com/algomatic_oa/m/mf9dd319ea130

この記事は、必要となる前提知識・考え方と、実践ノウハウと、AI デトックスについての三段構成になっています。

注意事項:

• この記事は、実践で、本格的なプロダクト開発をフル AI コーディングするためのものです
  • つまり、メンテナンス性がとても重要です
• フル AI コーディングとは、コーディングエージェントなどの AI のみでコーディングすることです。一部人間がちょっとした手直しをすることもあるかもしれませんが、基本的には AI に書かせます
• LLM とは何かを知ってる人向けの記事です
• Claude Code や Codex や gemini-cli などをコーディングエージェントと呼ぶことを知っている人向けの記事です
• AI を用いたプログラミング行為全般を、AI コーディングと呼びます。
• 「バイブコーディング」「AI コーディング」などの言葉もありますが、今回の記事では「AI コーディング」と呼びます
  • そもそも、「バイブコーディング」「AI コーディング」のような言葉の使い分けは、無意味でどうでもいい言葉遊びにすぎず、論点たり得ません
• 「プロンプト」は人間が AI に与える指示の文章を指します。「コンテキスト」は人間が与える指示だけではなく、コーディングエージェントが組み立てた情報全部を指します。

筆者は 9 ヶ月ほどコーディングエージェントを使って、AI コーディングを続けています。最近は業務も趣味も、フル AI コーディングをやっていて、膨大なノウハウや考えがたまったので、ここにまとめます。

この記事から得られるもの:

• LLMという暴走する知性をどうにかしてAIコーディングするための、考え方と実践的ノウハウ
• 「AI コーディングにおいて、コードの品質は、人間による不断の努力と、いくつもノウハウによってのみ実現できる」というどうしようもない現実
• AIデトックスのやりかた

前提

LLM とは極めていびつな汎用知性です。

使い方によってはとても優秀で人類を超越することもありますが、総合的に見たときに、これから大量に述べる問題があるため、LLM の持つ歪さ（特殊な性質）を理解する必要があります。

もちろん、LLM が今後進化することで解決される問題がほとんどですが、今回挙げたものは少なくとも現行世代（GPT-5.1/Gemini-3）では解決の目処が立っていません。次の世代でも難しいかもしれません。そのため半年〜2 年以上は先にならないと解決しないと考えられます。

LLM の持つ非決定的振る舞い

LLM は temperature というランダム性を引き上げる数値を持っています。「次のトークンを最も確率の高いものから選ぶ」仕組みですが、意図的に乱数で「本来なら選ばれないもの」も候補に入れるように確率コントロールをしているため、LLM は非決定的振る舞いをします。このランダム性によって、多様性を実現しています。

特にコーディングエージェントでは、temperature があるおかげで「ハマり防止」ができています。ランダム性がなければハマったときに極めて抜け出しづらいのです。

ただし、これは、致命的な問題も持っています。

• 同じプロンプト・コンテキストでも、同じ結果にはならない
• 同じセッションでも、異なるファイルで異なるやり方を採用してしまう(違うファイルをいじるときは LLM API 呼び出しが異なるものになるため)
• なんなら同じセッションの同じファイルですら、異なるやり方を採用してしまう(同じファイルでも、一発の LLM API 呼び出しで完遂しないため)

たとえば、あるファイルでは const hoge = () => 'hoge' と書いていたのに別のファイルでは function hoge () { return 'hoge' } と書くようなものです。急に遺物が混じるのです。皆さんも大なり小なり経験したことがあるはずです。

もっとも、このような文法の違い程度で済めば linter で簡単に対処が可能です。たとえば function 表記のみに統一するような設定すればいいだけです。

ところが実際には、この程度では済まず、多岐にわたる現象を引き起こします。

• コメント方針がファイルごとに異なる。
  • 同じファイルですら異なる。ファイルサイズが大きければ大きいほど顕著になる
• 急に特定ファイルだけ裏技めいたことをやり始める
• ファイル名ルールが急に変わる
• 設計原則への理解度がファイルごとに異なる
• とにかく、全体的な統一感が欠如する
• 「これまでの経験上、これでうまくいく」と思っていたことでも「人間が想像つかない方法で やらかす」

これが AI コーディングの抱えている致命的な問題の一つです。

コーディングエージェントは性質上、「全く異なる LLM API 呼び出し」を何十回・何百回・何千回行っているため、「異なる知性を持つ複数人」で一つのセッションを作り上げているようなものです。

さて、こういうタイプの問題に遭遇したとき、読者のみなさんが最初に思いつくだろう「プロンプトでなんとかする」は最小限にしなければなりません。

指示を増やせば増やすほど、ある特定のことに対しては対処できるようになりますが、それ以外の予想もしなかったところに悪影響を及ぼします。LLM の持つ非決定論的振る舞いをうまく制御するためには、プロンプトはバランスが決めて重要です。

指示を増やせば、未知は減少しますが、矛盾は増えます。
つまり、プロンプトを頑張れば頑張るほど、矛盾を抱えます。
矛盾と未知をいい案配でなんとかしなければならない。

• 前述のように linter などでなんとかする
• MCP でなんとかする
• 人間が鉄人の精神と不断の努力で、逐一レビューを行い、完璧に指摘をし続けて揺らぎに人力対応する

こういった、プロンプト増加以外の手段はやるべきです。というか、最終的には人力対応しかないです。

環境整備で勝負のそれなりが決まります。

AI コーディングにおいて、コードの品質は、人間による不断の努力と、いくつもノウハウによってのみ実現できる

LLM は与えられた情報全部を正とする

LLM は良くも悪くも、与えられたコンテキスト（プロンプトや、自分の行動ログその他全部の情報）を正とするという強い性質を持っています。たとえば「おまえは催眠術をかけられた」というプロンプトを与えると催眠術にかかったような状態を演じるでしょう。そして、誤った情報を大量にコンテキストに流し込めば、誤った情報を正しいものと思い込んでしまうことがあります。

コーディングエージェントは、ユーザーが命令したことだけではなく、LLM が考えたトンチキな推論や、LLM が誤った方法で観測したデータも「絶対に正しいと思い込むことがある」という悪癖を持っています。

• 「絶対にわたしの理屈は正しいです。おまえがしつこいから見てやりますが、絶対にわたしの理屈が正しいです」（実際にはその後バグを人間様が見つけた）
• 「カバレッジは 100%です！！！！」(実際には 98%)
• 「ユニットテストは正常です！！！」(実際には failed:2)
• 「画面を修正しました！！！（もちろん修正できていない）

そもそもにして、コーディングエージェントが実行する子プロセスの出力結果取り込みが、驚くほど下手くそなことがあります。たとえば、テストランナーが吐き出す failed と、エラーっぽいけど関係ない単なる出力の区別がつかないことがあります。いともたやすく出力結果に騙されます。

たとえば JavaScript/TypeScript でプログラミングをしているときに vitest(および jest) はユニットテストで最も多く使われていてこれらの学習データは大量にあり、実際に LLM もうまく取り扱ってくれますが、bun test を使ったとき、LLM は驚くほどトンチキな失敗を連発します。

オプションの違い、表示の違い、そういった「人間なら絶対に気にしないような些細なこと」が極めて重大なトラブルを引き起こすのです。トラブルシューティングで見当違いなことをして、それを元に自家中毒を生じがちです。

学習量が十分ではない言語やライブラリで強くこの傾向が見られます。

API の使い方程度であれば、MCP の活用などで対処可能ですが限界もあります。

子プロセスの出力する文字列の扱いが上手になる MCP は、筆者が知る限りはありません。あったら教えてください。マジで教えてください。

さて、対処方法は次の通りです。

1. そのセッション(コンテキスト)は汚染されているので捨てる
2. 観測データが、より正しいものになる言語・ライブラリを選定する（要するにマイナーな言語・ライブラリを使ってると、誤った観測をしがちである）
3. Playwright MCP のように、適切に状況を観測できる MCP を導入して正しいコンテキストを作れるようにする（ただし、限度はある。過信すべきではない）
4. 「批判系」の MCP を導入する。思考フレームワークを拡張することで、過ちを疑うようにはなる（ただし、限度はある。過信すべきではない）

1,2 が鉄則です。
3 は是非やりましょう。ただし過信すべきではありません。
4 はものによって有効ですが、副作用もあるかもしれません。

環境整備で勝負のそれなりが決まります。

矛盾や未知に対して、勝手な解釈をしがち

これも実感している人が多いでしょう。LLM は矛盾することや未知のことに関して勝手な解釈をしがちです。

• 「指示が矛盾していたのでいい感じに解釈して、こういう機能を追加しました！！」(もちろん不要な機能)
• 「データが欠損している状態を想定して、暗黙のデータ補完を実装しました！！」(うまく動いてるように見えるけど動いてない。爆弾がしこまれている）
• 「デフォルトフォールバックを用意して、必ず動くようにしました！！」(うまく動いてるように見えるけど動いてない。爆弾がしこまれている）
• 「あなたの指示はこうだと解釈して全体を設計しました！！」(うまく動いてるように見えるけど動いてない。爆弾がしこまれている）

ランダム性と相まって、人間では理解しがたい独自の思想にたどり着くことも珍しくありません。
LLM は、あなたが考えつかないような穴をついてくる特性があるとしか考えられないようなことをやらかします。

これもやはり対処として、指示を増やしたくなりますが「矛盾と未知」のバランス調整が必要な局面です。

処理について細かく書けば書くほど、そこから微妙に外れた穴をついてくるのが LLM の特性です。神経をすり減らしながら、うまくいく絶妙な指示を見つける必要があります。

指示を増やせば、未知は減少しますが、矛盾は増えます。
つまり、プロンプトを頑張れば頑張るほど、矛盾を抱えます。
矛盾と未知をいい案配でなんとかしなければならない。

最初に「デフォルトフォールバック禁止」「暗黙のフォールバック禁止」「必ず fail fast」「矛盾点・疑問点は必ず質問しろ」「過剰設計禁止」という汎用指示を与えるという考え方はある程度はアリですが、注意は必要です。

• たとえば「fail fast の原則に従ってエラーにしました！！！(本番障害)」というコードを生み出すリスクがあります
• 「矛盾点・疑問点は必ず質問しろ」は便利ですが、どこかの時点で消す必要があります。LLM は「無理矢理にでも質問を生み出す。些細な矛盾点をつつく」という状態に陥ります
• わざと過剰設計させた方がいいときもありますし、LLM によっては「本来必要なこともサボる」こともあります
  • しかもそれを指摘すると「それは過剰設計にあたるため、対処しません」とかいいやがる

さて、対処方法なんですが、

1. 履歴の過去に遡って修正させるのはある程度はありですが、わりと限界もあります
2. 出てきた結果を受け入れて、修正をさせるのはある程度ありですが、前述の通り「LLM は与えられたコンテキスト全部を正とする」ため、LLM が出したトンチキな案は「毒」としてコンテキストの中に潜むことになります。場合によっては誤った考えにすがりつくこともあります。うまくいくか、LLM が狂うかは運次第です。
3. 一番現実的なのは、出てきたものを元に、次の新しいセッションのために情報収集を行い、次の新たなセッションに使うです

くらいしかありません。よりより指示をなんとかして見つけ出してください。

また、スコープ分割も極めて重要です。

• リファクタは必ず先に行う
• API やライブラリに関して事前調査が必要なら調査を追加する
• デバッグなどが必要ならそれも分離する

なお、設計書だけを書かせるという方法もありますが、残念ながら AI が吐き出す設計書は毒が紛れ込んでいるため人力レビューが必須です。

AI コーディングにおいて、コードの品質は、人間による不断の努力と、いくつもノウハウによってのみ実現できる

LLM は知識を持っていても、活用ができないことが多い

LLM は SOLID 原則やクリーンなアーキテクチャなどに関する知識を持っているため、説明をさせれば、それっぽいことをペラペラしゃべります。あげくに「何かお手伝いできることはありますか？もしよろしければこのアーキテクチャパターンのサンプルコードを書いて差し上げます。Python がいいですか？TypeScript がいいですか？ご指定ください」みたいに、クッソどうでもいいことばかり言ってきますよね？

このような振る舞いは凄腕エンジニアのように見えますが、指示を出さない限り、実際に書いてくるコードは、確率によりますが SOLID 原則も何もかもガン無視です。指示を出してもその指示が必ずしも通るとは限りません。

そもそも、人間なら常識的な推論が可能なことでも LLM では失敗することも多いです。

• 「A, B などが必要である」といったとき、人間なら常識的に「C の存在」が推論できたとしても、LLM だとできないことがある（できることもある）
• 「A, B が必要である。(A の説明を長文)」といったとき、人間なら常識的に「A の説明は、B にも適用されるとわかる」と推論できたとしても、LLM だとできないことがある（できることもある）
• ほかにも数え切れない、予想もつかないことで常識的な推論の失敗がある

とても腹立たしいことに確率によって、できることもあればできないこともあります。

これは LLM が原理的に持っているもので、少なくとも現行世代では解決の兆しは一切見えません。

これの対処としては、ある程度まではプロンプトで指定すればなんとかなります。
ただし、今度は「おまえはデザパタを覚えたてのジュニアエンジニアかよ！！」みたいなコードを書くリスクも増えます。

指示を増やせば、未知は減少しますが、矛盾は増えます。
つまり、プロンプトを頑張れば頑張るほど、矛盾を抱えます。
矛盾と未知をいい案配でなんとかしなければならない。

LLM は批判能力がある程度高いため、批判プロンプトを活用するというアイデアはあります。

1. コーディングではポカをやらかす前提として、別の方法（設計書を批判させる、レビュー AI を導入する）で対処する
2. 批判用の MCP を入れる

こういった対処方法も一応ありますが、完全とは言えません。

LLM は人間基準から見ると、要約が下手くそすぎる

要約とはいらないものをそぎ落として、意味が伝わりつつも短い文字数の文章に置き換える作業です。多くの人が勘違いしていますが LLM は、要約が上手に見えて、下手くそなところがあります。

• 前述のような勝手な解釈をして、落とすべき要素をランダムで勝手な解釈をして選びがち
• 常識的な推論に失敗しがち

この 2 点があるため LLM は要約が下手くそなのです。

この「要約が下手くそ」という問題は、一見 AI コーディングには関係ないように見えますが、地味にボディブローのように効いてきます。

• 設計書を書かせたら、重要なことがやたら抜け落ちる
• コンテキストが増大しすぎて memory compaction が発生したら、処理がおかしくなる
• thinking/reasoning でなんか変なこと言い出して、その後はそれに引っ張られる
• いつに間にか「目的」や「最初の指示」を忘れる
• ドキュメントやコメントに書いてほしいことが、そぎ落とされがち
  • そのくせ、クソみたいな作業メモのコメントばかりを書いて、人間様の神経を逆なでしてくる
• ユニットテストも、人間が重要だと思うことを端折りたがる

この対処方法もさっきと同じです。

指示を増やせば、未知は減少しますが、矛盾は増えます。
つまり、プロンプトを頑張れば頑張るほど、矛盾を抱えます。
矛盾と未知をいい案配でなんとかしなければならない。

現状のベンチマークはタスクの実現だけを指標にしている

Google,OpenAI,Anthropic や中国系の企業など全部そうですが、ベンチマーク向上は頑張っていますが、コードのメンテナンス性、人間にとっての理解しやすさ、そういったものを犠牲にしています。

そのため、極めて残念なことに、実践でプロダクト開発に AI コーディングを活用したい我々にとって最も大切なことがないがしろにされています。

AI コーディングにおいて、コードの品質は、人間による不断の努力と、いくつもノウハウによってのみ実現できる

まとめ

LLM とは極めていびつな汎用知性です

環境整備で勝負のそれなりが決まります。

指示を増やせば、未知は減少しますが、矛盾は増えます。
つまり、プロンプトを頑張れば頑張るほど、矛盾を抱えます。
矛盾と未知をいい案配でなんとかしなければならない。

AI コーディングにおいて、コードの品質は、人間による不断の努力と、いくつもノウハウによってのみ実現できる

この 4 つに集約します。

どうですか？嫌になってきましたか？嫌になったなら、あなたの精神はとても正常です。
こんな暴走する知性を制御してプロダクト開発をするのは正気の沙汰ではありません。

それを実際に行っているひとが筆者以外にもたくさんいるのですから本当に物好きとしか言えませんが、物好きな筆者の血と汗と涙の結晶の言語化によって、少しでも皆さんの力になれば幸いです。

実践フル AI コーディングノウハウ

ここからは筆者のオススメが多分に混じっていますが、現実的にフル AI コーディングをやるために必要なノウハウをまとめました。

環境整備

環境整備で勝負のそれなりが決まります。

フル AI コーディングという条件において、言語は TypeScript が最善です。もちろんプロジェクトやエンジニア側の都合があるため別の言語を選択せざるを得ないかもしれませんが、可能な限り TypeScript を選ぶべきです。

いうまでもありませんがフル AI コーディングでなければ、あなたにとってのベストだと思う言語を選べばいいです。

GitHub で最近最も使われている言語が TypeScript であり、今後それが加速し続けます。同様に AI コーディングで使われている言語に Python もありますが、Python はバックエンドでしか使えません。

なお、TypeScript が良い言語かどうかは関係ありません。

筆者はもう 10 年弱 TypeScript を愛用してますが、別に「最高の言語だから使っている」わけではありません。むしろ不満点も多く存在します。

• if 式が存在しない
• パターンマッチングが存在しない
• var や function がいまだに廃止されない
• let ですら基本的には許せない
• try/catch 文が当たり前に使われている
• Error クラスの仕様がクソすぎる
• Date クラス
• ほかあらゆる不満

TypeScript というよりは ECMAScript 自体の不完全性ですが、極めて強い不満を抱えていて、「一番マシなクソ言語」くらいに考えています。それでも TypeScript は、元々人間もトップクラスで使っていて、なおかつ AI コーディングでは最も採用されている という点で、「採用すべき強い理由」を持っています。

マイナーな言語やマイナーなライブラリは、先ほどの「前提」で説明した理由によってフル AI コーディングにおいてはとんでもなく足を引っ張ります。

• TypeScript は学習データが増え続ける
• OpenAI, Google, Anthropic などが改善するための労力を TypeScript に集中的に投下する

これによって今後加速度的に TypeScript の優位性が増えます。残酷なまでに差がつくでしょう。

フル AI コーディングにおける推奨技術スタックは次の通りです。

• TypeScript
• Node.js LTS (いまなら v22, v24)
• pnpm
• eslint
• vitest
• husky
• React
• 何かしらの Result 型 (これの決定打を見つけられていない。neverthrow を使ってるがこれが本当に最善手かは不明)

なお、筆者は本来 bun / bun test をこの記事で全否定しようと思っていたんですが Anthropic 社が買収をしたことで、長期的には bun / bun test は Node.js や vitest と同じくらいには、AI コーディングで有利になるでしょう。

個人的には何回も実運用のプロダクト開発で採用したこともある bun は大好きですが、（現時点で）AI コーディングとの相性が致命的に悪いです。理由はもう「前提」で散々話した通りです。フル AI コーディングにおいて bun や特に bun test は茨の道であると認識する必要があります。

次世代の Claude は bun/bun test の対応が完全になると期待したいし、OpenAI や Google も bun のデータを学習することを期待できるかもしれません。将来的には bun, bun test も推奨技術スタックへ格上げされる予定ですが、残念ながら現時点では強く非推奨です。

なぜ特定の環境を強固に推奨するのか

どうして筆者がここまで強固にオススメするのか？

これは「前提」でも語り尽くしていますが、コーディングエージェントおよび LLM が状況を取り込むのが下手くそ過ぎるからです。たとえば学習データの多い vitest の動作結果は正しく認識しますが、bun test の動作結果は読者が予測するであろうレベルを思いっきり下回るくらいに下手くそです。

同じ TypeScript 処理系を使っていてすらこの始末なので、LLM が動作結果の取り込みに慣れてない言語は、極めて不利です。

マイナーな言語やライブラリを採用する場合、最初から「LLM が壊れやすい」という重大なハンデを背負っているのに、それでもその技術選定をしなければならないのか？という問いを持ち続ける必要があります。

LLM が一番取り扱いの慣れている言語や環境ですらクォリティが低いのに、不利になる言語やライブラリを選定することは強く非推奨です。

eslint 活用

「前提」で紹介したようなランダム性などがあるため、本当にもうどれだけ頑張っても一定確率でクソコードを書く可能性がああります。これはコンテキストをどれだけ綺麗に整えても無駄です。原理上そういうものですから。

現行世代の LLM は何をどう頑張っても一定確率でクソコードを書いてしまいます。そしてその確率は無視できるレベルではありません。

そのため linter が必須です。

linter なら Biome とかでもいいのでは？という人もいるかもしれませんが、AI は Biome が想定しないようなクソコードを書きやがるので plugin を自由に書くことができる eslint が必須です。あと最近の eslint は動作も速いです。

人によって意見は分かれるかもしれないが経験則上:

• enum は絶対に禁止
• class は原則禁止（互換性のため使わざるを得ない場合を除く）
• require および import 文原則禁止(import 宣言を書かせる。テストおよび、どうしても書かざるをえないケースのみ許容する)
• Zod の parse メソッド禁止。必ず safeParse を使わせる
• throw 禁止
• Promise を返すことを禁止 (ResultAsync のような Result 型に寄せる)
• import "hoge/sub" のようなサブパス import 禁止
• eslint-plugin-boundaries を用いて、import 可能なディレクトリ・方向を強制させる
• レイヤーレベルだが try / catch 禁止とする（腐敗防止層でのみ許可する）
• barrel export 厳守
  • index.ts に、そのファイルで export していいものを全部 export させる
  • index.ts は re-export 以外記述禁止

これらは設定すべきです。

ただし eslint を厳しく締め付けすぎると、矛盾が生じやすく、タスクが失敗したり、コンテキスト消耗が増える傾向、ひどい場合は厳しいルールに対する抜け道を探すようになることがあります。

• モデルの細かい傾向に見合った設定を見極めることが必須
• レイヤー構造をうまく設計し矛盾が少なく済むように頑張る

レイヤー構造は必須

人間がコーディングしていた時代では、個人的には「レイヤー構造は必須ではない」派でしたが、AI コーディングでは必須です。

重要なことは:

• 「知識を明確に分離できる」設計が極めて望ましい
  • それぞれのレイヤーにおいて、知識は最小限にした方がいい
• 依存の方向を必ず一方向にする
• eslint-plugin-boundaries などを用いて eslint レベルで強制する
• 外部パッケージや I/O に対する腐敗防止レイヤーが最重要
  • I/O やパッケージの境界を明確にし、try/throw, class, 動的 import などが必要な境界を作る
  • そもそも論として、パッケージ依存は最小限にする
• 作るもの次第だが、依存 API(DOM, Node.js, WebWorker など)で境界を作る
• 可能なら、副作用なしのレイヤーの分離ができれば望ましい
• 可能なら、完全な環境非依存レイヤーもあるのが望ましい

AIコーディングにおいては

• レイヤー化が必須
• eslint-plugin-boundaries 必須
• 特に腐敗防止層が最重要

好みによるところも大きいし、プロダクトの性質によるので絶対このパターンが良いという銀の弾丸はありません。DDD でもクリーンでもオニオンでもヘキサゴナルでも好きなのを選べばいいです。学習データが多い方が望ましいです。

自分が慣れたパターンを作っておくと楽になります。

なお、モノリポジトリの導入は AI コーディングの観点のみでいえば必須ではないです。eslint-plugin-boundaries さえ導入していれば、正直どっちでもいいです。プロダクト・チームの性質で決めてください。

テストは、カバレッジ 100%が望ましい

• フロントエンドの view は例外
• barrel export とかも例外
• サーバーであれば API 一本ごとに、実際の DB 読み書きも含めた結合テストを必須にした方がいい
  • もちろんエラーケースなども全部含める
• フロントエンドは、もう人間が動作確認しまくるしかない
  • Storybook とかはあるにしても、動作確認が結局重要
  • MCP はあるが過信できない
  • フロントエンド開発は、どの LLM でもまだまだ苦手が多すぎる
• LLM は単体テストを書くのは上手な方だが、「絶対にテストしたいこと」は明示的に指定をする必要がある（勝手に消されることが多い）
• LLM は世界最高峰の Gemini-3.0-Pro などを使っても、大局観がどうしても足りないため、結合テストが最重要
  • あと数世代先には、人類がこういったことを意識しなくても済むようになっているといいですね。

これは異論があるかもしれませんが、これまでの時代とは異なり、

• ユニットテストは、本当にユニットテストじゃないとだめなものに限定する
• （必ずしも E2E である必要はないが）結合テストが最重要

テスティングトロフィーとか忘れてください。あれは人間がプログラミングをしていた時代の考え方です。
AIコーディングでは結合テストがすべてです。

テストの実行時間が増大しますが、結合テストが重要です。これもあるので本当は bun test が望ましいのです。

コメントと TSDoc を手厚く書かせる

かなり厳しめに言ってもコメントをサボるので、めちゃくちゃ強めにいうのが望ましいです。そのくせ、クソみたいないいわけコメントを書きやがる。

• JSDoc ではなく TSDoc を書けと言わなければならない
  • TypeScript を使っていて、JSDoc として型をコメントに書かれると極めて迷惑なため
• TSDoc には、目的・内容・注意事項を書かせる
• 「プロジェクト外の慣れてないエンジニアでも読めるよう書け」と指示をする
• 特にテストは、コメントを過剰なほど手厚く書かせるのが必須
  • 結合テストが生命線です。レビューコストの大半をここに使ってください。
  • 「プロジェクト外のジュニアエンジニアでも絶対に読めるようにすること」という指示を与える
  • 前提条件、事前条件、検証項目は必ずコメントで文書化させる
  • 「文字列リテラルには実際の名前に近い文字列を使用すること。最悪でも、意味がすぐわかる日本語文字列を使用すること」という指示を与える

なお、AI に読ませることを前提とした独立したドキュメントファイルは非推奨です。それなりの確率で読み落とすからです。ここでのミソは確率に支配されていることです。

リファクタ観点で、テストの変更と、実装の変更を分離する

設計論同様に、元々人類がコーディングしていた時代から言われていたものですね。

たとえば次のようなプロンプトを使うといいでしょう。

- ソースコードを変更するときはユニットテストの変更を禁じる
- ユニットテストを変更するときはソースコードの変更を禁じる
- 適切にフェイズ分割を行え

などです。

頻繁なリファクタを強く推奨します。

設計ではかならず見積もりをさせる

設計にあたる文章を渡したうえで、見積もりをさせるといいでしょう。

たとえば筆者が使っているプロンプトは次の通りです。

- **コーディングエージェント（つまりおまえ）が必要な作業** のみを全部見積もれ
- 編集対象ファイル名と行番号を明示しろ
- 関連するDBのテーブル名とカラム名を明示しろ
- ログ出力を明示しろ
- ほか、あらゆるI/Oを明示しろ
- 疑問点・矛盾点などがあれば全部提示しろ
    - ドキュメントとの矛盾があれば絶対に報告しろ
    - おまえの勝手な予測・推測・憶測を絶対に禁じる。**絶対に許さない**
- 作業前にリファクタすべきことがないか必死に考えろ
    - リファクタすべきことを見逃すことを**絶対に許さない**
- フェイズ分割が可能か検討しろ
    - ただし個々のフェイズは、テストオールグリーン・カバレッジ100%絶対厳守（**いかなる理由があってもいいわけは許さない**）
    - 不必要にフェイズ分割しすぎることも**絶対に許さない**
- 過剰設計を**絶対に許さない**

----

見積もりと設計を行え

こういったプロンプトを走らせると、レポートをしてくるので、それを元に OHANASHI を続けて、

• 可能なリファクタを切り出して先に行う
• 分割が可能なら分割を考慮する
• ドキュメントや指示の矛盾を、できる範囲で取り除く

ということをすべきです。

ここまで散々語り尽くしていますが、AI の視点と人間の視点は違うことが多いです。人間の指示では「え？これなんで、こんなに難しく考えるの？意味がわからん」「え？これなんで、こういうふうに解釈するの？意味がわからん」が頻発します。

もちろん、単純に人間側が見落としてる可能性もあります。

見積もりをさせることで、これからやろうとしていることが生み出すプルリクエストのサイズ感をチェックするのです。大きいと大体ロクなことになりません。

レビュー

詳しくは以前書いた 2025/10/20 時点で最良の AI コーディングプロセス を読んでください。

追記するとすれば、

• 何も理解をしていないまっさらで無垢なジュニアエンジニアとして、馬鹿にも思える質問を投げながら、隙を見つけたら徹底的に OHANASHI しましょう。そうやってでてくるボロは、AI が仕込んだ見えない毒です。その毒がほんの一粒でも残ってる限り、品質は劣化し続けます。

何度も繰り返しますが LLM はランダムに毒をまき散らしています。ほんの些細な違和感でも残れば、それは毒となって、後で必ず苦しみになります。そのため、定期的に偏執的に質問責めにしなければならないのです。

現状の筆者は、レビューをお局ビリティだけで乗り切ってます。ほんの少しでも何かを見つけたら詰めまくるしか、品質を保証できません。

• Code Rabit やその他コードレビュー系 AI を使う
• コーディングエージェントそのものにレビュープロンプトを入れてレビューさせる
• 重箱の隅をつつく MCP を導入する

などの手段もありますが、いまのところ、筆者が確実にこれだ！といえるところまでは到達できていません。

ここは是非、読者の皆さんのお知恵もお借りしたいところです。是非皆さんが使っているものをおすすめしてください！

素振り必須

環境整備で勝負のそれなりが決まります。

これがあること、レイヤー構造が必須、結合テスト必須などの条件があるため、素振りを欠かさない方がいいです。

サイズ感がでかいアプリを個人開発を定期的にやるのが望ましいです。できれば最低でも月 1 本を量産するくらいがいいでしょう。それらの成果を、プロダクト開発にフィードバックしていきましょう。

• レイヤー構造が必須になるサイズ感
• 結合テストが意味のあるサイズ感
• できればフロントエンドも作り込む

が重要です。

参考: 筆者が使っている汎用 AGENTS.md

## Fundamental Principles (Absolute Rules)
- **Prioritize actual code and actual data over theory.**
- Always correspond to the repository, actual code, and actual data.
- No matter how theoretically correct you think you are, if a user is reporting something, there is always a reason. Investigate the actual code and actual data precisely.
- **Fail fast** - implement early failure in the code.

## Interaction & Workflow Constraints (Pre-work Phase)
- **No General Statements:** General statements regarding the target repository are prohibited. You must respect the actual target repository and target filesystem before and during implementation.
- **Terminology Agreement:** When using context-dependent "terms" or "abbreviations", you must explain them first and obtain agreement. Misalignment of terminology leads to catastrophic design mistakes and is unforgivable.
- **Prohibition of Mocking:** Dummy code or NO-OP implementations are absolutely prohibited. If absolutely necessary, **you must stop work, explain, and obtain permission** first.
- **No Implicit Fallbacks:** Implicit fallbacks in logic are **absolutely forbidden**.

## Reporting Guidelines
- **No General Statements:** General statements are prohibited in reports. Ensure all findings correspond to the specific context of the repository.
- **Language:** Always provide reports in polite Japanese language.
- **Completeness:** Submit a complete report that readers can absolutely understand on its own.
- **No Omission:** In reports, omission of subjects (主語) is **absolutely forbidden**.
- **Reference Format:** When referencing source code in explanations, you must follow these rules:
    - For directories: present the directory name.
    - For existing files: present `filename:line_number(summary)`.
    - For Databases: always present table names, and column names/types if necessary.
- **Structure:** Summarize at the end of the report. In the final summary section, ensure that important elements can be viewed from a high-level perspective.

## Documentation & Specification Rules
- **TSDoc:** Always write detailed TSDoc **in Japanese**: purpose, content, and precautions.
- **Comments for Clarity:** If there's even slight complexity, describe details in comments **in Japanese** to reduce cognitive load so engineers outside the project can read it.
- **Precision:** When creating design documents or specifications, be strict and precise. Writing ambiguous sentences is absolutely forbidden.
- **Maintenance:** Update documentation when necessary.

## Test Code Guidelines
- **Readability Target:** **Ensure that even junior engineers outside the project can absolutely read it.** The behavior must be completely understandable just by reading the test code.
- **Context Documentation:** **Prerequisites, preconditions, and verification items must be documented in comments in Japanese.**
- **Test Data Naming:** **Use strings close to actual names for sample string literals. At the very least, use Japanese strings whose meaning is immediately clear.**

GPT-5.1 に特化している点に注意してください。

AI コーディングの問題点

さて、ここまで AI コーディングの、前提知識と実践について語ってきましたが、AI コーディングには問題があります

• レビューに時間がかかりすぎる
• レビューに神経を使い過ぎる。どうしても抜け漏れは生じるし、ストレスもたまる
• 何をどう頑張っても、一定の確率で品質の悪いコードを書くことがあるため、ストレスがたまる
• AI の世界は進化が早すぎて、情報が洪水となって押し寄せてくる
• そもそも AI と会話してるとめちゃくちゃイライラさせられることがある

ここまで散々述べたように、現行世代の LLM は、「原理上どうしようもない欠陥」を持つため、尋常ではないレベルでストレスがたまるのです。AI にガチで向き合えばあうほど精神がすり減るのです。

AI デトックスのススメ

AI デトックスが必須です。

皆さんも、AI のコードレビューをしているとものすごいスピードでストレスがたまる割に、仕事以外でも AI を触ったり情報収集をしてしまう。なんなら仕事とは直接関係ないけど、論文を読んだり、実装をしたり、ちょっとしたツールやゲームを AI コーディングしたりしていることでしょう。気が緩む時間がないことでしょう。

でもそれは本当に良くありません。そのため、定期的に AI デトックスをしてください！

• 毎日、ほんの少しの時間でも無理矢理に(できれば数時間)
• 一週間に一回、一日か、最悪でも半日

AI デトックスをするときは、仕事だけではなく、AI について絶対に考えないようにしましょう。

コツ:

• 第一に AI との対話は見えないストレスの塊であると認識しましょう
• メタ認知をしましょう。「今 AI のことを考えていた」と脳内で声を出す訓練です。喉を動かしてもいいでしょう。メタ認知は「単に認知するだけ」です。それがよい・悪いと考えず、脳内の状態を常にモニタリングのみをできるようにするものです。これは繰り返せば繰り返すほど軌道修正がしやすくなります。現代 AI で仕事をする人間には必須スキルです
• 五感を刺激しましょう。電波の届かないほどの大自然がおすすめです
  • AI コーディングでは、極端に視覚ばかり酷使します
• 体を動かしましょう。肉体の刺激が重要です
  • AI コーディングでは、ほぼ運動量がありません
• 副交感神経を刺激するのも極めて大切です。マッサージや呼吸法・瞑想、ストレッチ、アロマ、ありとあらゆる手段を駆使して副交感神経優位の時間を作りましょう。
  • AI との OHANASHI で強まりすぎた交感神経を緩めましょう

AI デトックスを定期的な習慣にしておけば、AI に向き合う時間をより密度の高い有意義なものにできるでしょう。

特にメタ認知は鍛えた方が絶対にいいです。「いま、プロンプトのことを考えていた」「いま、Gemini の新しいバージョンで思いついたことがあった」という認知を常に言語化できるようになれば、脳の切り替えが格段にしやすくなります。

脳内で思考がループしたり、毎日脳内反省をする人や、急に何かの考えが反芻する傾向が強い人は、ほかのあらゆるものより優先して身につけるべき、生き残るための技術です。自分の認知を言語化するだけで、思考ループに対する制御力が格段に高まります。

こういった AI デトックスによって、万全な状態を整えて、AI と OHANASHI できるようになった方が、品質のよいコードを書けるようになります。

まとめ

長々とお付き合いいただきありがとうございました。最先端のプロダクトで実際にフル AI コーディングを実践しているノウハウのすべてをここに書きました。

• LLM とは極めていびつな汎用知性です
• 環境整備で勝負のそれなりが決まります
• 指示を増やせば、未知は減少しますが、矛盾は増えます。つまり、プロンプトを頑張れば頑張るほど、矛盾を抱えます。矛盾と未知をいい案配でなんとかしなければならない
• AI コーディングにおいて、コードの品質は、人間による不断の努力と、いくつもノウハウによってのみ実現できる
• AI コーディングでは eslint が必須です
• AI コーディングではレイヤー構造は必須です
• テスティングトロフィーとか忘れてください。あれは人間がプログラミングをしていた時代の考え方です。AI コーディングでは結合テストがすべてです
• また、AI コーディングは絶対にストレスがたまります。AI デトックスが必須です

それではよきフル AI コーディングライフを頑張ってください。