AIに任せたはずなのに、毎回同じ手直しが戻ってくる
木曜18時47分。翌朝公開する地域スーパーの受取予約画面の修正をAIへ任せ、エンジニアは帰り支度を始めていた。
依頼したのは、人数を変更した時に料金表示がずれる不具合の修正とテストだ。調査の結果、変更したファイル、実行したテストが報告されている。ここだけ読めば、今日こそ定時に帰れそうだった。
ところが、差分を開いたところで手が止まった。
npm installが実行され、package-lock.jsonが増えている- 自動生成する
src/lib/generated/schema.tsが直接書き換えられている - 時間切れになったE2Eテストへ
.skipが付いている
このプロジェクトではpnpmを使う。生成済みファイルは元のスキーマを直して作り直す。テストを外して成功扱いにはしない。どれも前の会話で伝えた内容だった。
また同じ説明が必要なのか。AIを使えば速いと言ったのは自分なのに、これを共有したら「使い方が下手なだけでは」と思われるかもしれない。
そう考えると、同僚へ相談するより、自分で直した方が早い気がした。チャットには「細部はこちらで整えます」と返し、増えた固定ファイルを消す。スキーマを元へ戻し、テストを有効にして、別の失敗原因を追う。
19時を過ぎ、さっきまで軽く見えた三つの手直しが急に重くなる。同じ修正を繰り返すたびに、AIへ任せた時間と自分で直す時間が二重にかかる。それでも伝え方の失敗だと思うと、ひとりで抱え込んでしまう😮💨
でも、ここで見直したいのは、気の利いたプロンプトの書き方だけではない。何度も守るルールが、個人の会話にしか残っていないことだ。
三度目の手直しで、自分の説明力が嫌になる
最初の一回なら、会話で補足すれば済む。「このリポジトリはpnpmです」「生成済みファイルは触らないでください」と返せば、次の修正へ進める。
苦しくなるのは、その会話が次の依頼へ持ち越されない時だ。別のスレッドを開く。別の担当者がAIへ頼む。対象フォルダが変わる。そのたびに、同じ前置きを思い出して書かなければならない。
一つでも書き忘れると、また手直しが戻ってくる。すると、AIに任せた側は「説明を漏らした自分が悪い」と感じやすい。レビューで指摘される前に黙って直し、AIを使ったこと自体を目立たせないようにする。速くするための道具なのに、失敗を隠す作業が増えていく。
今回も、同僚から同じレビューコメントが入った。
この生成ファイル、前のPRでも直接変更されていなかった？ 次も人が戻す前提になっていないかな。
責める言い方ではなかった。それでも、胸の奥がきゅっと縮む。前回も自分で直したことを言えば、「なぜその時に残さなかったのか」と思われそうだった。
エンジニアは、前のチャットを開いてみた。そこにはpnpm、生成コマンド、テストを外さないことが書かれている。説明はしていた。ただし、その説明を読めるのは、その会話を開いた自分だけだった。
ここで少し気持ちがほどけた。伝える能力がないのではない。チームで繰り返し使う約束を、個人の会話へ置いたままだったのだ。
会話にしかないルールは、次の依頼で消える
AIへの指示には、少なくとも二種類ある。
一つは、今回だけの依頼だ。「予約人数を変えた時の料金表示を直す」「この不具合の原因だけ調べる」のように、仕事が終われば役目も終わる。
もう一つは、プロジェクトで繰り返し守るルールだ。使うパッケージ管理ツール、生成ファイルの作り方、変更後に実行する確認、勝手に変えてはいけない場所。担当する機能が変わっても、次の週になっても必要になる。
この二つを毎回一つの依頼文へ詰めると、長くなるだけでなく、書き漏らしも増える。今回の目的より、注意事項の方が長いチャットになる。読む側も、どれが今日だけの条件で、どれが今後も守る約束なのか分かりにくい。
OpenAIのCodexは、作業前にAGENTS.mdを読み、プロジェクトのルートから現在の作業場所まで、階層ごとの指示を重ねる。GitHub Copilotにも、リポジトリ全体へ適用する指示と、特定のパスだけに適用する指示がある。
製品によってファイル名、対応する画面、指示の優先順位は異なる。ただ、共通している考え方は分かりやすい。
何度も必要な説明は、会話の記憶に頼らず、コードと一緒に読める場所へ置く。
そうすると、AIだけでなく、新しく入った人にも役立つ。「このプロジェクトはなぜpnpmなのか」「どのファイルを直せば生成物が変わるのか」を、詳しい人へ毎回聞かなくて済む。繰り返していた手直しが、そのまま引き継ぎの材料になる🧩
残すなら、全体・場所・今回だけを分ける
何でも一つの指示ファイルへ入れればよいわけではない。長い説明を全部貼ると、大事な一行が埋もれる。OpenAIの公式文書にも、Codexが読み込むプロジェクト指示には既定の合計サイズ上限があり、必要に応じて階層へ分ける考え方が示されている。
GitHubも、カスタム指示は短く、それだけで意味が分かり、リポジトリ内の多くの依頼に当てはまる内容がよいとしている。
今回のプロジェクトなら、次の三つに分けられる。
リポジトリ全体で守ること
どの機能を触る時にも必要な内容は、ルートのAGENTS.mdや、利用製品が読むリポジトリ共通の指示ファイルへ置く。
## Package manager
- Use pnpm. Do not run npm install or create package-lock.json.
## Validation
- Run pnpm check and the relevant tests after changing code.
- Report the commands you ran and whether they passed.
## Stop and ask
- Ask before changing dependencies, CI, database migrations, or test scope.ここで「品質を大切にする」のような広い言葉だけを書いても、次の動きは決まらない。何を実行するか、どの変更で止まるかまで書く。人がレビューする時も、同じ文章を基準にできる。
特定の場所だけで守ること
予約機能の生成手順は、別の機能には関係しない。全体の指示へ混ぜず、対象フォルダの近くへ置く。
## Generated reservation types
- Do not edit src/lib/generated/schema.ts directly.
- Edit schemas/reservation.yml, then run pnpm generate:reservation.
- If generation changes files outside src/lib/generated/, stop and report them.Codexなら、作業場所に近いAGENTS.mdへ分けられる。GitHub Copilotなら、対象ファイルを指定するパス別の指示を使える。どちらを使う場合も、実際に利用する製品がその形式を読めるかは、現在の公式文書で確認したい。
今回だけ頼むこと
不具合の内容、変更してよい範囲、今日の締め切りは、今回の依頼へ書く。
予約人数を3人から4人へ変えた時、合計金額が更新されない原因を調べてください。
まず変更せず、再現手順と原因候補を報告してください。
修正は確認後に依頼します。一度だけの仕事まで共通ルールへ足すと、指示ファイルはすぐ古くなる。ずっと守ることと、今日やることを分けるだけで、依頼文もかなり短くなる。
一つの手直しを、三行の約束に変える
指示ファイルを最初から完璧に作ろうとすると、それ自体が重い仕事になる。過去のレビューを全部読み返し、開発手順を網羅しようとすると、着手できないまま終わりやすい。
まずは、今日二度目に直したことを一つ選ぶ。エンジニアはpackage-lock.jsonが増えた件から始めた。
残したのは、次の三行だ。
- 現在の事実: このリポジトリは
pnpmを使い、pnpm-lock.yamlを管理している - 実行する確認: 依存関係を触ったら
pnpm checkと対象テストを実行する - 止まって聞く操作: 依存関係の追加・更新や別の固定ファイル作成は、実行前に確認する
「npmは禁止」だけで終わらず、何を使うかを書く。「テストする」だけで終わらず、コマンドを書く。「危険な変更は確認する」だけで終わらず、依存関係やCIなどの操作を書く。これなら、一度読んだ人が次に何をすればよいか分かる📝
自分の好みを、そのままチームの決まりにしない
もう一つ大事なのは、ひとりで書いて確定しないことだ。何度も自分が直した内容でも、それがプロジェクトで合意したルールとは限らない。慣れている書き方や、個人の好みが混ざっていることもある。
エンジニアは三行を同僚へ見せた。すると、pnpmと生成手順は既存のREADMEにも書かれた事実だったが、「依存関係は一切変えない」は広すぎると分かった。脆弱性対応では更新が必要になるため、正しくは「追加・更新する前に、理由と変更予定のパッケージを報告して確認する」だった。
ここで修正されたのは、AIへの言い方だけではない。人同士でも曖昧だった約束だ。指示を一緒に読む時間を取ると、「AIのための特別な説明書」ではなく、新しく入った人もレビュー担当者も使える確認事項になる。
逆に、誰も理由を説明できないルールは、そのまま増やさない方がよい。過去の失敗、現在の構成、実際に通るコマンドへ結びつけられる内容から残す。そうすれば、指示ファイルが古い注意書きの倉庫になるのを防げる。
書いた後は、小さな依頼で確かめる。まずAIへ、今回読み込んだ指示と、変更前に確認が必要な操作を説明してもらう。次に、影響の小さい文言修正などを頼み、報告されたコマンドと差分を見る。
ここで期待どおりでなくても、また自分の能力のせいにしなくていい。指示が読まれていないのか、対象範囲が違うのか、文章が曖昧なのかを一つずつ確認できる。
そして、指示ファイルを作ったからといって、レビューやテストを外してはいけない。GitHubの公式文書も、生成AIは同じ指示へ毎回まったく同じように従うとは限らないと注意している。指示は、確認をなくす仕組みではない。何を確認するかを揃える材料だ。
翌日の昼、エンジニアは別の小さな修正をAIへ依頼した。報告にはpnpm checkと対象テストの結果があり、固定ファイルの追加はなかった。生成ファイルを変える必要があると判断した時点で、元のスキーマをどこで直すか質問も返ってきた。
一回で全部が解決したわけではない。それでも、黙って三つ直す夜から、質問へ一つ答える昼に変わった。この差は小さく見えて、気持ちにはかなり効く。
AIがまた同じルールを外した時、自分の伝え方が悪いと決めて、ひとりで直し続けなくていい。まず、繰り返した手直しを一つ選ぶ。現在の事実、実行する確認、止まって聞く操作の三行にして、チームが読める場所へ置く。
同じ注意を何度も打ち直す時間を、次の人とAIが最初から読める約束へ変える。 そこからなら、AIへ任せる速さと、自分だけが後始末を抱えない働き方を一緒に作っていける🙂
AIとの会話で決めた理由まで共有したい時は、AIとの会話で決めたこと、チームに残ってる？ 判断を共有する5行もあわせて読んでほしい。PRを渡す時の情報が足りないと感じるなら、AIで作ったPR、「レビューお願いします」だけで投げてない？で、レビュー相手へ残す内容を整理できる。
