既存のコードを画面で見比べながら、AIに渡す文脈をどう整理しようか考えている開発者
AIコーディング約12分

既存コードにAIを馴染ませる文脈の渡し方｜実務の型

AIに「このコードベースに機能を足して」と頼んだら、たしかに動くものが返ってきた。 でも、よく見ると命名のクセが違う。エラーの扱い方も、ファイルの置き場所も、チームの流儀とどこか浮いている。レビューで「うちの書き方じゃないね」と言われ、結局あちこち直す——そんな経験、ありますよね。

原因は、AIの実力不足とは限りません。 多くの場合、AIがあなたの既存コードベースを「見えていない」だけです。新規にゼロから書かせるのは得意でも、すでにあるコードの流儀・依存・構造を察してそろえる、というのはAIにとって一番苦手な部類。だから、ここを人が言葉にして渡せているかで、生成コードが馴染むかどうかが大きく変わります。

この記事は、AIに既存コードへ手を入れさせるとき、どの文脈を、どの粒度で、どう要約して渡すかの型をまとめたものです。コードを全部貼ればいい、という話ではありません。

なお「渡す」のやり方は、いまは1つではありません。①必要なコードを直接貼る ②Claude Code・Cursor・GitHub Copilot のようなエージェント型ツールに、リポジトリや対象ファイルを自分で読みに行かせる ③CLAUDE.md やルールファイル（AIに常時読ませる、約束事を書いた設定ファイル）に常設しておく——この記事の「渡す」は、この3つを総称した言い方です。手段は変わっても、そのタスクに効く文脈を選んで効かせるという中身は同じ。少し長めですが、一度に全部やる必要はないので、効く所から一緒に見ていきましょう。

結論：既存コードベースにAIを馴染ませるには、コードを丸ごと渡すのではなく、①このコードの「流儀」（命名・書き方・エラー処理の約束事）→ ②似た既存実装を1〜2例（お手本として）→ ③触ってよい範囲と触らない範囲 → ④依存とデータの流れ（何を使い、何を返すか）→ ⑤置き場所と完成の判断基準を、短い言葉と少量のお手本コードで渡します。全部を毎回そろえる必要はなく、その依頼でAIが迷いそうな所だけを埋めれば十分。これだけで生成コードが既存になじみ、レビューの「うちの書き方じゃない」がぐっと減ります。最後にコピーして使えるテンプレを置きました。

大きなコードベースを全部読ませようとしなくて大丈夫です。リポジトリを自分で読みに行けるエージェント型ツールでも、これは変わりません——読めることと、要点に注意を向けられることは別だからです。 AIに必要なのは全量ではなく、そのタスクに効く一握りのお手本と約束事。それを選んで効かせるのが、ここでの仕事です。

なぜ「動くのに浮く」が起きるのか

AIに渡す既存コードの文脈を、流儀・お手本・範囲・依存の層に分けて整理する概念図

AIは、目の前の依頼文と、渡された範囲のコードだけを手がかりに書きます。 あなたの頭の中にある「うちはこう書く」「ここはこの関数を通す」といった暗黙の了解は、渡さないかぎりAIには存在しないのと同じです。だから、一般的には正しくても、あなたのコードベースの中では浮いたものが返ってきます。

ありがちなズレは、だいたい次のどれかです。

裏を返せば、この5種類のズレを起こさないための情報を先に渡せば、馴染む確率は大きく上がるということ。やることは難しい技術ではなく、「察してほしい部分を、言葉とお手本にして渡す」だけです。順に見ていきます。

渡し方1：このコードの「流儀」を短い言葉にする

最初に渡したいのは、コードそのものより「このコードベースの約束事」です。長文の規約集はいりません。AIが迷いそうな所を、箇条書きで数行渡すだけで効きます。

たとえば、こんな粒度です。

ポイントは、「正しい書き方」ではなく「うちの書き方」を渡すこと。 世間の正解ではなく、あなたのチームのローカルルールこそAIが知りようのない情報です。ここを3〜5行渡すだけで、返ってくるコードの第一印象が大きく変わります。

渡し方2：似た既存実装を1〜2例、お手本として渡す

言葉での説明より速くて正確なのが、「これと同じノリで書いて」と既存コードを1〜2例見せることです。AIは説明文よりも、実物のコードからパターンを写し取るのが得意です。

たとえば「ユーザー登録の処理を、この既存の『商品登録』処理と同じ構成で書いて」と頼むと、層の分け方も、バリデーションの置き方も、お手本に寄せてくれます。 お手本は多すぎないのがコツ。一番効く1例を名指しするほうが、たくさん見せる（読ませる）より馴染みます。

なお現場には「典型コードが汚い」「お手本にできるきれいな実装が無い」こともあります。きれいな1例が無ければ、せめて命名とエラー処理だけ近いファイルを渡す。それも無ければ、無理にお手本を探さず流儀メモ（渡し方1）だけで代替して構いません。お手本探しで手が止まるくらいなら、進めたほうが早いです。

渡し方3：触ってよい範囲・触らない範囲を決める

次に、「どこまで手を入れていいか」の線を引きます。ここが曖昧だと、AIは親切心で関係ない所まで書き換えたり、共通部分に手を入れて他に影響を出したりします。

「この関数の中身だけ直して、外から見た引数と戻り値は変えないで」のように、動かしてよい箱の大きさを先に渡す。 範囲が明確だと、レビューで見る場所も狭くなり、思わぬ巻き込み事故も防げます。これは安全に小さく試すための線引きでもあります。

ただし、線を引いてもAIが結局共通部分に手を入れてしまうことはあります。線引きは守られないことがある前提で、受け取り側のガードも一つ持っておきましょう。差分（diff/PR）で「実際にどこを触ったか」を最初に確認する——これだけで、机上の線引きで終わらず、はみ出しにその場で気づけます。

渡し方4：依存とデータの流れを伝える

AIが既存の部品を無視して車輪の再発明をしないよう、「何を使い、何を通すか」を渡します。

ここを渡さないと、AIは「一般的にはこう書く」で、標準APIを直に呼んだり新しいライブラリを勝手に足したりします。 「日付整形は自前の formatDate を使って。新しいライブラリは追加しないで」の一言が、後の依存まわりのレビューを丸ごと減らします。

渡し方5：置き場所と「完成の判断基準」を添える

最後に、「どこに置き、どうなれば完成か」を渡します。出力の受け取り方まで決めておくと、差分やPRを確認してからの手戻りが減ります。

「完成の判断基準」は、AIに自己チェックさせる材料にもなります。テストを自分で実行できるエージェント型ツールなら、ここを渡しておくと書く→テストを走らせる→直すまで自走させやすく、あなたは差分やPRの確認に集中できます。 「既存の user.test と同じ形式でテストも書いて」と添えると、テストの流儀までそろい、後から書き直す手間が減ります。

そもそも既存テストが薄い・無い現場も多いはず。その場合は「テストを通す」にこだわらなくて大丈夫です。手で叩いて確かめる手順を1つ、あるいは「ここだけは確認すべき」という観点を1つ渡すだけでも、完成の判断基準として十分に効きます。最低ライン一つでも示せれば、AIの自走の的が定まります。

大きいコードベースを全部は渡せないとき

「文脈が大事なのはわかったけど、コードベースが大きすぎて全部は渡せない」——当然です。そして、全部渡す必要はありません。AIに要るのは全量ではなく、そのタスクに効く一握りです。

要点は、「AIが迷う所だけを、ピンポイントで渡す」こと。 広く薄く全部渡すより、狭く濃く効く所を渡すほうが、生成コードはよく馴染みます。

明日からやること（小さく始める3つ）

全部を一度にそろえようとすると重いので、まずこの3つから。

  1. 「うちの書き方」メモを3〜5行作る：命名・エラー処理・ログの約束を箇条書きに。一度作れば次から使い回せます（渡し方1）。
  2. 一番近い既存実装を1つ選んで一緒に渡す：「この書き方に合わせて」と添えるだけ。説明文より速く馴染みます（渡し方2）。
  3. 触ってよい範囲を一言そえる：「この関数の中身だけ、引数と戻り値は固定で」。巻き込み事故を防げます（渡し方3）。

既存コードに馴染ませる文脈チェックリスト

依頼を出す前に、その依頼で迷いが生まれそうな所だけ埋めれば十分です。全部チェックする必要はありません。

各カテゴリの先頭に ★最低ここだけ を付けました。時間が無ければ ★の3つ（命名一言／一番近い実装1つ／触る範囲一言）だけで構いません。これは「明日からやること」の3つと同じで、現場で本当に回る最低ラインです。残りは余裕があれば埋める任意項目だと思ってください。

渡し方1：流儀

渡し方2：お手本

渡し方3：範囲

渡し方4：依存と流れ

渡し方5：置き場所と完成基準

最後に

AIに書かせたコードが既存から浮くのは、あなたの説明が下手だからではありません。 チームの流儀は、長く一緒にやってきた人にしか見えない暗黙知で、それをAIが知らないのは当たり前です。それを少しだけ言葉とお手本にして渡せる人が、いまそのコードベースで一番頼りになる人です。

AIが返したコードが既存コードにすっと馴染み、納得した表情でレビューを終える開発者

5つ全部でなくても、今日ひとつ「うちの書き方メモ」を作れたなら、それはもう次の依頼から効いてきます。 コードを全部読ませようとしなくて大丈夫。AIが迷う所だけ、少しずつ言葉にしていきましょう。

なお、依頼そのものの組み立て方はAIにコードを書かせる前に渡す前提と制約の型に、書かせた後の確認はAI生成コードのレビュー・検証チェックリストにまとめています。あわせてどうぞ。

関連用語