AIにコードを書かせる前に決めるべき5つと、その置き場所

5つのうち、書くようになって結果が変わったのは完了条件です。ここを曖昧にすると、動くけれど意図と違うものが出てきます。エラーが出ないので、こちらも気づけません。

私は「確かめ方」まで含めて渡すようにしました。どのコマンドを実行して何が出れば正しいのか、どの画面を開いて何が見えれば正しいのかを、頼む時点で書きます。判断の基準を先に渡してしまえば、できたかどうかを毎回こちらが考えずに済みます。

仕様そのものの書き方はアプリの仕様書は何を書けばいい？個人開発で使う九つの項目にまとめています。あちらが何を書くかの話で、この記事は渡し方の話です。

1. 01　目的を手段ではなく状態で書く

   何を実現したいかを一文で書きます。「ボタンを追加して」ではなく「設定を開かずに通知を止められるようにしたい」。手段から渡すと、そのとおりのものが出てきます。良い手が他にあっても提案されません。困っている状態を伝えれば、こちらが思いつかなかった直し方が返ってくることがあります。

2. 02　動かす環境とバージョンを書く

   どのOS、どの言語、どのバージョンで動かすのかを書きます。ここが曖昧だと、手元では動かない書き方が混ざります。私はWindowsで作業していて、同じ「ファイルを探す」でもBashとPowerShellで書式が違います。どちらで動かすのかを言わないと、半分の確率で通らないコマンドが返ってきました。

3. 03　制約を挙げて選択肢を減らす

   使ってよいもの・使ってはいけないものを挙げます。「新しいライブラリを足さない」「書式は既存のファイルに合わせる」といった、選択肢を減らす情報ほど効きます。自由度を残すと、その場では最短の解が選ばれます。それが既存のやり方と違っていると、あとで全部そろえ直すことになります。「既存に合わせて」だけでは弱いので、どのファイルに合わせるのかを名指しすると確実です。

4. 04　完了条件を確かめられる形にする

   何をもって終わりとするかを、確かめられる形で書きます。「動くこと」では終わりません。「このコマンドが通る」「この画面を開いてこう見える」まで落とします。確かめ方を渡しておけば、できたかどうかを毎回こちらが判断せずに済みます。

5. 05　変更禁止の範囲を理由つきで名指しする

   触ってほしくないファイルや設定を名指しします。⚠️ 指定しなければ、整理のついでに直されます。悪意ではなく、残す理由がこちらの頭の中にしかないからです。

長く見えますが、書いているのは5つだけです。悪い形のほうが、あとから説明する量は多くなります。最初の返答が想定と違って、そこから条件を一つずつ足していくことになるからです。

実際、私が時間を無駄にしたときは、ほぼ全部が「短く頼んで、長く直した」型でした。

並べてみると分かりますが、良い形に専門用語は増えていません。増えているのはどこで確かめるかとどこを触らないかです。この2つは、技術の知識ではなくこちらの事情なので、頼む側にしか書けません。

もう一つ、一度に一つだけ頼むのも効きました。「ダークモードに対応して、ついでに余白も整えて」と渡すと、どちらかが雑になります。分けて渡すと完了条件も分かれるので、片方だけ戻すこともできます。まとめて渡したほうが速く見えますが、戻すときにまとめて戻すことになります。

「余計なことをしないで」は効きません。何が余計かはこちらの都合で、相手には見えないからです。

効いたのは、理由まで添えて名指しする書き方でした。たとえばこのサイトには、古いURLからの転送設定があります。配信済みのアプリが参照しているので消せません。ただ「消すな」とだけ書くと、整理のついでに消えます。「配信済みのアプリが見ているので消せない」と理由を書いてから、消えなくなりました。

同じ考えで、数を書かないことも決めています。「転送は5本あります」と書くと、増えたときに必ず古びるからです。本数ではなく、どこを見れば分かるかを書きます。

もう一つ効いたのは、壊れ方を書いておくことでした。「この設定を消すと、配信済みのアプリからのリンクが404になる」まで書いてあると、消す前に手が止まります。禁止だけを並べたファイルは、量が増えるほど読まれなくなりますが、結果まで書いてあるものは読まれました。

はじめは毎回の指示に書いていました。破綻します。同じ説明を繰り返すうえ、伝え忘れると静かに違う形になるからです。

いまはプロジェクトの規約ファイルに書いています。作業の前に読まれるので、こちらが言い忘れても効きます。置き方についてはClaude Codeとは？できること・始め方・任せない作業で触れました。

書き方には一つコツがありました。「何をしてはいけないか」だけでなく「なぜそうなったか」を残すことです。理由のない禁止は、状況が変わったときに守られません。このサイトの規約には、一度実際に壊した経緯がそのまま添えてあります。

全部を一つのファイルに書くと、長くなって効かなくなります。私は入口を薄く保ち、触るものと、先に読む場所の対応表だけを置いています。更新ログを触るならこの節、読み物を書くならこの節、という具合です。

同じ内容を2か所に持たないことも徹底しました。片方だけ古びて、どちらが正しいか分からなくなるからです。数字や一覧を写したくなったら、写す代わりに出どころを指します。

• 入口のファイルは索引に徹する。中身は書かない。
• 禁止には必ず理由を添える。
• 一覧や数を複製しない。出どころを指す。
• 一度壊した箇所は、経緯ごと残す。

書いても守られないものが残ります。読み飛ばされることもあれば、こちらの書き方が悪いこともあります。

そこで、ビルドを止める検査に移しました。このサイトには、書式や台帳との一致を確かめるスクリプトが6本あり、食い違うとビルドが失敗します。人が気をつける話ではなくなります。

強い例もあります。あるアプリは、審査で指摘を受けて使えなくなった語があります。紹介ページにその語が入るとビルドが落ちるようにしてあるので、うっかり書いても本番には出ません。禁止語の一覧はコードの中に一箇所だけ持っていて、注意書きとしてではなく、実際に照合される値として置いてあります。

この移し替えには判断の基準があります。間違えたときに自分で気づけるかどうかです。画面が真っ白になる類は放っておいても気づきます。気づけないのは、見た目が正常なまま中身だけ違っているとき。そこだけ機械に回せば、検査は増えすぎません。

検査を足すときは、まず落ちることを確かめます。わざと違反する値を入れて、本当にビルドが止まるかを見る。通ることしか確かめていない検査は、何も見ていないのと同じでした。

失敗を毎回の注意ではなく仕組みへ変える考え方は個人開発で失敗を記録する六項目。却下と障害から残した形式にまとめています。

5つ全部を毎回書く必要がありますか？

ありません。目安は元に戻せるかどうかです。読むだけ、調べるだけなら雑に渡して構いません。ファイルを書き換える、設定を変える、外へ出すものに触る場合だけ、先に5つを埋めます。

指示を書くほうが時間がかかりませんか？

書く時間より、直す時間のほうが長くなります。私が時間を無駄にしたときは、ほぼ全部が「短く頼んで、長く直した」型でした。最初の返答が想定と違うと、そこから条件を一つずつ足していくことになります。

まだ仕様が決まっていない部分はどう渡しますか？

決まっていないこと自体を伝えます。「ここは決まっていないので、案を2つ出してほしい」と渡せば、勝手に一つへ決められることはありません。黙って渡すと、相手はどこかで決めるしかなく、その判断はこちらに見えないまま進みます。

触ってほしくない場所を書いても直されます。

「消すな」だけでは効きません。理由と、消したときに何が壊れるかまで書くと止まります。私の場合、「配信済みのアプリが見ているので消せない」「消すとリンクが404になる」と書いてから直されなくなりました。

目的を一文で書けません。

そのときは、渡す作業が大きすぎる可能性があります。書けないと気づけること自体が、この5つの効用でした。こちらの中で整理できていない依頼は、誰に渡しても整理された形では返ってきません。

規約ファイルが長くなって読まれません。

入口を索引に徹させて、中身を書かないようにしました。触るものごとに「先に読む場所」を示す対応表だけを置きます。禁止を並べたファイルは量が増えるほど読まれませんが、壊れ方まで書いてあるものは読まれました。

5つは、こちらの事情を言葉にする作業です。技術の知識ではなく、何を守りたいかを書き出すことなので、頼む側にしか書けません。

そして、書き出したものは1回きりで消えません。規約ファイルへ移せば次から効きますし、機械の検査へ移せば忘れても効きます。毎回の指示に書いているうちは、まだ移し替えが終わっていないというだけのことです。