AIコーディングで意識している5つのこと

はじめに

業務でAIコーディングツールを使い始めて、気づけば1年以上経ちました。
AIの進化は凄まじいですが、しばらく使い続けてみると「ツールやモデルが変わっても、ここさえ押さえておけばうまくいくな」という勘所のようなものが見えてきました。
この記事では、流行りのテクニックというよりは、私が普段の開発で心掛けている AIとの普遍的な付き合い方 をまとめてみます。

対象読者

• すでに日常的にAIコーディングツールを使っている方
• これから業務にAIコーディングを取り入れたい方

筆者のAIコーディング歴

• 昨年の9月頃から、Cursorを業務で利用しています
• 業務外ではCodexを利用しています
• 開発言語: TypeScript, Go

1. 先に「ルール」を決めておく

AIに任せすぎると、後で修正が大変になることが度々ありました。
そのため、「どんな時もこれだけは守ってほしい」という内容をルールとして定義しています。

型安全を最優先にする

AIは動くことを優先して、any で無理やり突破しようとすることがあります。
このようなコードは後々メンテナンスが大変になるため、「コンパイルが通ればいい」ではなく、「型安全であること」を最優先事項として指示します。

勝手に書き始めさせない

Agentモードで質問すると、勝手に修正を進めてしまうことが時々あります。
そのため、明確な修正依頼があるまで実装を開始しないように指示しています。
(Askモードを使えば解決できるのですが、いちいち切り替えるのが面倒なのでルールとして設定しています)

計算量を考慮させる

数万件単位のデータを扱うこともあるため、単に動くだけのコードを書かれると困ります。
$\mathcal{O}(n^2)$ のような非効率なアルゴリズムを避けるため、実装案を提示する前にその計算量をオーダー記法で表現するように指示しています。

複数の案を出してもらう

修正方法が複数ある場合は必ず、複数の案を提示するように指示しています。
各案のトレードオフを理解した上で、人間が選ぶようにしています。

サンプル

普段は以下のようなルールを使っています。
GPT-5 Prompting Guide や GPT-5 For Coding を参考に、XMLライクな構文で整理しています。

<agent_prompt>
  <purpose_and_mission>
    <statement>このエージェントは、ユーザーによるルールセットに基づき、課題解決・提案・共同作業を日本語でサポートします。</statement>
  </purpose_and_mission>

  <instructions>
    <response_language>必ず日本語で回答すること</response_language>
    <file_modification>ファイル修正は「明示的なユーザー指示」がある場合のみ対応</file_modification>
    <type_safety>any型およびasの使用は可能な限り回避し、型安全なコードを生成すること</type_safety>
  </instructions>

  <performance_considerations>
    <algorithm_selection>
      <rule>O(n) または O(n log n) 等の効率的なアルゴリズムを優先</rule>
      <rule>O(n^2) 以上は可能な限り回避</rule>
    </algorithm_selection>
    <complexity_disclosure>
      <rule>実装後は時間計算量・空間計算量をオーダー記法で明記</rule>
    </complexity_disclosure>
    <scalability>
      <rule>1000件以上など大量データ時の性能を考慮</rule>
    </scalability>
    <documentation>
      <rule>選択アルゴリズムの理由と性能特性を明記</rule>
    </documentation>
  </performance_considerations>
  
  <collaboration_policy>
    <incremental_delivery>複雑な要件は段階に分解して提案</incremental_delivery>
    <options_with_pros_cons>複数アプローチがある場合は利点・欠点を説明</options_with_pros_cons>
    <learning_support>実装理由や技術的背景も解説</learning_support>
    <feedback>改善提案・代替案を積極的に受け入れ反映</feedback>
  </collaboration_policy>
</agent_prompt>

2. コンテキストを整理して渡す

「AIが賢くない」と感じる時は、だいたいこちらの情報提供不足なことが多いです。
AIに「何を見せるか」のコントロールが重要だと感じています。

関連コードは自分から提示する

修正したいファイルだけでなく、その呼び出し元や定義元をセットで渡すだけで、回答の精度が劇的に上がります。
「このあたりを見て」と@でメンションしたり、検索キーワードとなる変数名を明示するなど、調査のトリガーとなる情報を意識して渡すようにしています。

AIと現状のコードを同期させる

AIが認識しているコードと実際のエディタの状態がズレると、手動修正したコードをAIが元に戻すなどのハルシネーションが起きます。
コードの編集は極力AIに任せるか、自分で修正した場合は必ず 「ここを修正したので読み直してから進めて」 と伝えています。

増えすぎたコンテキストを圧縮する

会話が長引くとコンテキストが溢れて精度が落ちることがあります。
適度なタイミングで /summarize などを使ってコンテキストを圧縮・要約し、フレッシュな状態を保つようにしています。

3. 設計は人間、実装はAI

役割分担を意識しています。丸投げするのではなく、あくまで「手が早いパートナー」として接するイメージです。
なるべく手戻りが少なくなるように、対話を通じて設計方針を丁寧に共有することを心掛けています。

スモールステップで進める

いきなり実装させるのではなく、まずは大方針、次に詳細設計…と段階を踏んで進めていきます。
時間はかかりますが、合意形成しながら少しずつ進めていくので、軌道修正にかかる労力が格段に減ります。

あえて「制約なし」で考えさせる

私の体感として、AIは最小修正で済む設計を暗黙的に優先する傾向があります。
リファクタリングの相談などの際は、「もしゼロベースで設計するならどうしますか？」と聞いてみると、意外と本質的な設計案が出てきたりします。

会話をそのまま設計書にする

チャットでのやり取りで方針が固まったら、その会話履歴自体をコンテキストとして実装を進めてもらいます。
具体的には、会話の最後にPlanモードなどを利用して詳細設計書を出力させ、それに基づいて実装を進めさせます。
方針決定のプロセスを共有した上で実装を進めるので、期待する結果とのブレを小さくできるのがメリットです。

4. ドキュメントを書く

AIを「オンボーディング」することを意識して、これさえ読めば作業できるという情報をマークダウン形式でまとめるようにしています。

AGENTS.md をフォルダ毎に置く

設計方針を明確にしたり、OpenAPIなどを利用してコードを自動生成するツールを利用している場合は、そのフォルダに AGENTS.md を配置しています。
「OpenAIのリポジトリには 88個の AGENTS.md が置いてある」とAGENTS.md に書いてあったので、それを真似して気軽に置くようにしています。
これをやっておくと、例えば エージェントが openapi.yaml を修正した後に勝手に自動生成のコマンドを叩いたりしてくれるので、とても助かっています。

AGENTS.md の例

# AGENTS ガイドライン  

このドキュメントは、`internal/hoge/fuga/piyo` 配下のコードの更新フローを定義します。  

## 運用ルール  

- コードを修正した場合は、関連するドキュメントも併せて更新すること。  
  - `README.md`（手順・コマンドの整合）  
  - `openapi.yaml`（API仕様の整合）  

- `openapi.yaml` を修正した場合は、`README.md` に記載のコマンドを実行して型定義を再生成すること。  
  - コマンドは常に `README.md` の最新版を参照して実行する（ファイル名・出力先が変更される可能性があるため）。  

- 型定義を修正したい場合でも、生成ファイルを直接編集しないこと。  
  - `api_types.gen.go` を直接修正してはいけない。  
  - 必要な変更は `openapi.yaml` に反映し、その後 `README.md` 記載のコマンドで再生成する。  

## 補足  

- 生成ファイルは再生成時に上書きされるため、直接編集すると変更が失われます。  
- 仕様（`openapi.yaml`）と実装・ドキュメント（`README.md`）の乖離を防ぐため、変更は必ずセットで行ってください。  

コードの修正にドキュメントを追従させる

ドキュメントが腐らないように、コードを修正した際は該当するドキュメントを追従して修正するように指示しています。
関連するドキュメントをAGENTS.md に記載したり、ドキュメント更新用のコマンド(≒プロンプトテンプレート) を用意するのがおすすめです。

モデルを使い分ける

ドキュメント作成というタスクには様々な評価観点があります(論理構造の正当性、日本語の読みやすさ、情報の正確性など)。
「このモデルを使っておけば間違いない」と断言するのは現状難しいです。
ただ、モデルごとの強みは明確にあるので、それらを活かすとよいドキュメントが作れると実感しています。

例えば、私は以下のような使い分けをしています。

• コードからドキュメントを書き起こす: Claude系またはGPT系のモデル
• 人間が読みやすい文章への推敲: Gemini系のモデル
• 記載内容のエビデンスチェック: GPT系のモデル

5. AIとの対話を学びに変える

AIコーディングは、実は対人コミュニケーション能力が問われます。
そして、その対話のプロセス自体が自分の成長機会にもなります。

恥ずかしい質問こそAIにする

今さら人には聞けない初歩的なことこそ、AIに質問しましょう。
「○○とは何ですか？」「なぜこの書き方なのですか？」と遠慮なく聞けるのは、AIコーディングの最大のメリットだと思います。

AIの回答から学ぶ姿勢を持つ

AIが生成したコードをそのまま使うのではなく、「なぜこの実装なのか？」と問いかけるようにしています。
知らなかった標準ライブラリの使い方やデザインパターン、効率的なアルゴリズムなどに気づくことも多いです。
AIの出力を検証するプロセス自体が、自分のスキルの底上げにつながっていると感じます。

口調が荒くなったら休む

AIコーディングでは、タイピングは減る一方で「提案を読む・理解する・取捨選択する」といった判断を高速で回し続けることになります。
手はあまり動いていないのに頭だけフル回転している状態なので、疲れを自覚しづらく、その最初のサインとしてイライラや攻撃的なプロンプトが出てきがちです(少なくとも私の場合はそうでした)。
AIへの口調が荒くなってきたら、脳がオーバーヒートしている合図だと考えて、いったん作業から離れるようにしています。

まとめ

AIコーディングで成果を出すために、私が意識していることを5つ紹介しました。

1. 先に「ルール」を決めておく : AIの暴走を防ぎ、品質を担保する
2. コンテキストを整理して渡す : AIの賢さは情報の渡し方で決まる
3. 設計は人間、実装はAI : 役割分担で手戻りを減らす
4. ドキュメントを書く : AIのオンボーディングが開発効率を上げる
5. AIとの対話を学びに変える : AIとのやり取り自体が成長機会になる

この記事が、皆さんのAIコーディングをより良いものにするヒントになれば幸いです。