こんにちは！ 高千穂ムラたび/ラクダの佐伯です 😊
「理解負債」シリーズ、第3弾です。
①では「理解負債って何？」という話、 ②では「DECISION.mdで返済する方法」を書きました。
今回のテーマは、 もっと手前の話。
そもそもAIへの「指示の出し方」が悪いと、 どれだけレビューしても品質は上がらない。
という話です。
😅 同じAIなのに、なぜ品質が全然違うのか
私は今、酒税の記帳が簡単にできる、ツールを開発しています。
開発はClaude Codeを使っています。
で、開発を進めていく中で 不思議なことに気づきました。
同じAIに頼んでいるのに、 良いコードが返ってくる時と、 ひどいコードが返ってくる時がある。
最初は「AIの調子が悪いのかな」と思ってました笑
でも違った。
違いは、自分の指示の出し方でした。
🔴 ダメな指示の例：「ログイン機能を作って」
実際にやらかした例を出します。
開発初期、私はこんな指示を出していました。
「ログインする機能を作って」
AIは素直にコードを返してくれます。 動きます。ログインできます。
でも1ヶ月後、問題が起きました。
- ログイン失敗した時のエラー処理がない
- タイムアウトの設定がない
- パスワードがコードに直書きされている
- ログが何も残らない
「動くけど、本番では使えないコード」の完成です。
これ、AIが悪いんじゃないんです。
「ログイン機能を作って」としか言ってないから、 AIは「ログインできればOK」と解釈した。
当たり前ですよね。
🟢 良い指示の例：「5つの条件を満たすログイン機能を作って」
同じ機能を、指示を変えて頼み直しました。
「ログインする機能を作って。 ただし以下の条件を満たすこと。
① ログイン失敗時は3回までリトライする
② タイムアウトは30秒に設定する
③ パスワードは環境変数から取得する（コードに書かない）
④ ログイン成功・失敗をログファイルに記録する
⑤ 2段階認証が求められた場合のハンドリングも含める」
返ってきたコードは、 最初の指示とは別物でした。
エラー処理がしっかり入っている。 パスワードが安全に管理されている。 ログが残る。
同じAI、同じ機能、でも品質が全然違う。
違いは「指示に条件を入れたかどうか」だけです。
💡 気づいたこと：AIは「言われてないことはやらない」
これ、当たり前のようで深い話なんです。
人間のエンジニアに「ログイン機能作って」と頼んだら、 経験のある人なら勝手にエラー処理を入れてくれます。
「パスワード直書きはダメだよね」と自分で判断してくれる。
でもAIは、言われてないことはやらない。
正確に言うと、やってくれる時もあるけど、 やらない時もある。
この「やらない時」が怖い。
しかも「やらなかった」ことに気づくのは、 大体トラブルが起きた後 😱
📝 私が実践している「指示テンプレート」
この経験から、AIにコードを頼む時の テンプレートを作りました。
毎回これに沿って指示を出しています。
━━━━━━━━━━━━
■ 何を作るか？（機能の説明） → やりたいことを具体的に
■ なぜ作るか？（背景・目的） → これがあるとAIが「意図」を理解する
■ 満たすべき条件（最低5つ） → エラー処理、セキュリティ、ログなど
■ やってはいけないこと → パスワード直書き禁止、など明示
■ 参考にすべき既存コード → 「この書き方に合わせて」と伝える
━━━━━━━━━━━━
特に大事なのが「なぜ作るか」です。
「ログイン機能を作って」と言うだけだと、 AIは「ログインさえできればいい」と解釈する。
でも「本番環境で24時間自動運用するための ログイン機能を作って」と書くだけで、
AIは「じゃあ安定性が重要だな」と判断して、 リトライ処理やタイムアウトを自分から入れてくれる。
目的を伝えると、AIが「行間」を読んでくれるようになる。
📊 指示を変えたら、どれくらい変わったか
体感ではなく、実際の数字で比較します。
今回の開発で記録を取りました。
テンプレート導入前（雑な指示）
→ AIが返したコードをそのまま使える確率：約30%
→ 残り70%は手直しが必要
→ 敵対的レビューで見つかる問題：平均 5〜8件/回
テンプレート導入後（条件付き指示）
→ そのまま使える確率：約70%
→ 手直しが必要なのは30%
→ 敵対的レビューで見つかる問題：平均 1〜2件/回
問題の発生率が約4分の1に減りました。
開発のスピードが上がったのはもちろん、 「後から直す」作業が激減したのが大きい。
修正作業って、新しく作るより疲れるんですよね 😅
🔥 「指示の質 = コードの質」という法則
ここまでの話をまとめると、こういう図式です。
①雑な指示 → 動くけど危ないコード → 後で大量の修正
②丁寧な指示 → 最初から質の高いコード → 修正がほぼ不要
つまり、指示を書く5分を惜しむと、 修正で2時間かかる。
指示に5分かけると、 修正は10分で終わる。
「急がば回れ」は、AI開発でも真理でした。
✨ シリーズまとめ：理解負債を溜めない3つの習慣
ここまで3回にわたって書いてきました。 整理するとこうなります。
① 理解負債を知る（第1回） → AIが書いたコードを「理解してない」ことがリスクになる
② DECISION.mdで記録する（第2回） → 「なぜそうしたか」を残して、未来の自分を救う
③ 指示の質を上げる（今回） → そもそもAIに良いコードを書かせる
この3つをセットで回すと、 理解負債はほとんど溜まりません。
良い指示 → 良いコード → 判断を記録 → 理解が維持される
このサイクルです。
💪 一人開発でも「仕組み」で品質は上がる
大企業には開発チームがあって、 コードレビューの仕組みがあって、 品質管理の専門家がいます。
一人開発には、それがない。
でも、AIをうまく使えば 一人でもチームと同じ品質が出せる。
ただし「うまく使う」がポイント。
AIに雑に頼んで雑なコードをもらうのか、 丁寧に頼んで質の高いコードをもらうのか。
その差を生むのは、 たった5分の「指示の書き方」です。
ぜひ試してみてください 😊