Practical Guide / 実務ガイド

AIをコード生成機として使う
正しい付き合い方

AIは「優秀だが無責任な実装者」である。指示通りには動くが、なぜそう作るかを理解しない。だから設計の責任は常に人間にある。 このガイドはその前提のもとで、AIとの協業を最大化するための実務ノウハウをまとめたものだ。

// CORE PRINCIPLE

「AIに作らせる」ではなく「AIを使って自分が作る」という意識の転換が、すべての出発点になる。

01 事前準備 — 渡す前に決めておくこと Preparation
1
仕様だけでなく「目的」を必ず書く
AIは仕様通りに作るが「何のためか」は理解しない。目的があると設計の質が上がり、将来要件も推測できる。
✗ 悪い例
CSVを読み込んでDBに登録するプログラムを作ってください
✓ 良い例
CSVを読み込んでDBに登録するプログラムを作ってください。
目的は「毎日バッチ処理で顧客データを更新すること」です。
将来、差分更新にも対応したいです。
2
前提条件（環境・制約）を明示する
これだけで生成精度が大幅に向上する。AIはデフォルトで最新・最一般的な構成を選ぶため、環境が違うと動かないコードが出る。
例
Python 3.11
Windows環境
外部ライブラリ禁止（標準ライブラリのみ）
ORMは使わず、sqlite3で直接書く
関数ベースで作る（クラスは使わない）
「自由に作らせる」は事故の元。制約を与えるほど品質が安定する。
3
入出力仕様を明確にする
AIは「それっぽいインターフェース」を勝手に決める。後で差し替えが発生する。
例
入力：CSVファイル（UTF-8、ヘッダー行あり）
出力：処理件数と失敗件数をJSONで返す
エラー時：ログ出力のうえ処理継続（中断しない）
4
命名規則・コーディングスタイルを指定する
指定しないと、チャットを分けるたびに命名規則が変わる。
例
関数名：snake_case
クラス名：PascalCase
定数：UPPER_SNAKE_CASE
コメント：日本語OK
5
フォルダ・ファイル構成は人間が決める
AIに任せると毎回構成が変わり、保守性が落ちる。
例（先に宣言する）
project/
 ├─ main.py
 ├─ service/      ← ビジネスロジック
 ├─ repository/   ← DB操作
 └─ test/
この構成に従って実装してください、と最初に渡す。
02 開発中の進め方 During Dev
6
いきなり全部作らせない
AIは長い文脈で破綻しやすい。小さい成功を積み上げる方が、結果的に速い。
①CSV読み込みだけ作る → 動作確認
②バリデーション追加 → 動作確認
③DB登録 → 動作確認
④エラーハンドリング → 動作確認
各ステップで動作確認を挟む。デバッグも格段に楽になる。
7
実装方法は複数案を出させてから選ぶ
AIは「1案しか出さないとそれが正解になる」。人間が設計者として選択する工程を意図的に作る。
例
この機能の実装方法を3案出してください。
それぞれのメリット・デメリットも書いてください。
選択は私がします。
AIは「選択肢生成機」として使う。決断は人間がする。
8
コンテキストに渡す情報を絞る
関係ないコードを大量に貼り付けると、AIの注意が散漫になり誤った修正が増える。
✗ 悪い例
プロジェクト全体のコードを貼り付けて「バグを直してください」
✓ 良い例
「この関数だけ」「このエラーに関係するファイルだけ」を渡す
必要最小限のコンテキストが、精度の高い回答を引き出す。
9
指示は具体的に。「いい感じに」は禁止
曖昧さ = バグの原因。AIは曖昧な指示に対して「それっぽい」何かを返すだけ。
✗ 悪い例
いい感じにエラー処理してください
✓ 良い例
エラー時はloggingでERRORレベルのログを出力し、
例外はキャッチして処理を継続してください。
プログラムを止めてはいけません。
10
テストデータはコードで生成させる
手作りのテストデータは偏る。大量データでのテストが難しい。
例
ランダムな顧客データを1000件作るPythonコードを書いてください。
フィールド：名前（日本語）、年齢（20-80）、メールアドレス
再現性があり、件数も自由に変えられる。
03 品質管理 — 出力を信じるな Quality
11
AIの出力は「それっぽい嘘」を含む
AIは自信満々に間違える。動くように見えるが、エッジケースで壊れることがある。
注意すべき症状：
・存在しないライブラリのメソッドを平然と書く（ハルシネーション）
・「修正しました」と言いながら何も変わっていない
・動くように見えるが特定条件で落ちる

対策：必ず手元で動かす。コードレビューは「動作確認」ではなく「意図の確認」。
12
定数を使わせる（マジックナンバー禁止）
AIは値を直書き（ハードコード）しがち。変更に弱くなり、バグの温床になる。
✗ 悪い例
if status == 1:
    timeout = 30
✓ 良い例
STATUS_ACTIVE = 1
DEFAULT_TIMEOUT = 30

if status == STATUS_ACTIVE:
    timeout = DEFAULT_TIMEOUT
プロンプトに「マジックナンバーを使わず定数にまとめてください」と毎回入れる。
13
修正は「影響範囲を限定」させる
AIは関係ない部分も勝手に変える。差分が追えなくなり、バグの混入に気づきにくい。
例
この関数のみ修正してください。
他のコードは一切変更しないでください。
差分管理ツール（git）は必須。コミットを細かく切る。
14
AIが生成したコードのセキュリティを必ず確認する
AIは「動くコード」を出すことを優先する。セキュリティは後回しにされやすく、動いているため気づきにくい。
まず「何が起きるか」を理解する

AIが生成したコードに潜むセキュリティの問題は、多くの場合動作に影響しない。 システムは正常に動き続ける。しかし、攻撃者にとっては「入口」になっている。

発覚するのは大抵、情報漏洩・不正アクセス・サービス停止が起きた後だ。
RISK 01 — パスワード・APIキーの埋め込み
AIはサンプルコードにパスワードやAPIキーをそのまま書く癖がある。 それをGitHubに上げた瞬間、世界中に公開される。 対策：秘密情報は必ず環境変数か設定ファイルに分離させる。コードに直接書かせない。
✗ AIがよく書く例
API_KEY = "sk-abc123xyz..."   # コードに直書き
✓ 正しい書き方
import os
API_KEY = os.environ.get("API_KEY")  # 環境変数から取得
RISK 02 — 外部からの入力をそのまま使う
ユーザーが入力した文字をそのままDBへの命令や、ファイルパスに使うコードを生成することがある。 悪意のある文字列を入力されると、データベースの中身を全件取得・削除される（SQLインジェクション）、 あるいはサーバー内の任意のファイルを読まれることがある。
対策：ユーザーからの入力は「信頼しない」を前提にさせる。必ずバリデーションと無害化を指示する。
RISK 03 — 認証・権限チェックの省略
「動作の確認」を優先するあまり、ログイン済みかどうかの確認、管理者権限かどうかの確認を省いたコードを生成することがある。 URLを直接叩けば誰でも管理画面に入れる、という状態が生まれる。
対策：認証・権限チェックを「必ず入れること」を毎回明示する。
プロンプトへの追加例：
「セキュリティに配慮してください。パスワードやキーは環境変数から取得し、ユーザー入力は必ずバリデーションを行い、認証チェックを省かないでください。」
生成されたコードは「セキュリティの観点で問題はないか確認してください」とAI自身に聞くのも有効。ただし完全には信頼しない。
15
1ファイルは300〜700行以内を目安にする
AIは全体俯瞰が苦手。ファイルが大きいと後半への注意が薄れ、一貫性が崩れる。
ファイルを小さく保つことで、コンテキストに「必要な部分だけ」渡せるようになる。責務の分離（単一責任原則）とも一致する。
17
AIコードは必ずレビューしてから使う
「動いた」と「正しい」は別物。動作確認とコードレビューは別工程として行う。
レビュー観点：意図通りか、エッジケースは、セキュリティ上の問題はないか。
「このコードの問題点を指摘してください」とAI自身に聞くのも有効。
04 トラブル対応 Troubleshooting
18
AIが混乱したらチャットを分ける
AIは長い会話で「コルサコフ症候群」的な状態になる。文脈が壊れ、以前の合意を無視した回答が増える。
症状：「さっき決めたこと」を無視し始める、矛盾した回答が増える、同じミスを繰り返す

対応：新しいチャットを開き、引き継ぎ用プロンプトを作らせる
引き継ぎプロンプトの例
今までの決定事項と実装済みの内容をまとめてください。
次のチャットへの引き継ぎ用として使います。
19
バグで詰まったら人間が仮説を出す
AIは原因特定が弱い。「何が起きているか」の説明は得意だが「なぜか」は苦手。
例
このバグはインデックスズレの可能性はないですか？
その前提でコードを確認してください。
人間は「仮説生成機」。AIは「仮説検証機」として使う。
20
AIが突然方針を変えたらルールを再提示する
文脈の揺れにより、以前合意したスタイルや方針を忘れることがある。
スタイルガイドをテキストファイルにまとめておき、新チャットの冒頭に貼り付ける。
「このルールに従って作業してください」を毎回の先頭に入れる習慣をつける。
21
こだわりが強くなったらチャットを変える
長い会話でAIが特定のアプローチに「執着」し始めることがある。新チャットでフラットに戻す。
17（混乱）と似ているが別の問題。こちらは「間違った方向に確信を持ってしまっている」状態。リセットが最も速い解決策。
05 ツール活用 Tools
22
複数のAIをセカンドオピニオンとして使う
AIごとに「癖」が違う。同じ問題を複数AIに投げると、見落としていた視点が出ることがある。
特定モデルの優劣より「別の視点を得る」目的で使う。
「このコードの問題点を別のAIにも聞いてみる」は有効な品質チェック。
モデルの得意分野は頻繁に変わるため、固定したランキングは当てにしない。
まとめ — 成功の3原則
① 小さく作る
② 制約を与える
③ 比較する
AIは「優秀だが無責任な実装者」だ。設計の判断・方針の決定・品質の責任は常に人間にある。
AIが書いたコードは「下書き」であり、「成果物」ではない。
この認識を持って使う人と、そうでない人とでは、長期的な生産性に大きな差が出る。