Claude Code などのAIに作業を頼むと「できました」と返ってくるのに、本当にできているのかを確かめられない。頼んでいない所まで書き換えられていた。この記事を読むと、「確かめ方」と「書いてよい範囲」を入れた指示書を、枠を写してすぐ書けるようになります。枠のもとにしたのは、運営者が自分用に作っているYouTubeライブのコメント管理ツール「LiveJazzup」の開発記録で、2026-11-10 11:32 時点の、進行中の開発記録です。アプリはまだ完成していません。
2026-11-10 に、読む人の課題から始まる順に組み替えました。記録の内容と時点は変えていません。
「できました」を確かめたいときに写して使う、指示書と報告書の枠
ここに載せるのは、記録の型を一般化した枠です。例は自作で、LiveJazzup の中身ではありません。また、この枠を実際の作業で使って試してはいません。「社内の手順書（Markdown の文書）の表記ゆれを直してもらう」作業を、AIに頼む場面を想定しています。
指示書は、AIに渡す頼みごとを書いた文書（プロンプト）のことです。冒頭の2つの困りごとについて書く欄は、下の枠の「4. 出す前の検査」と、「5. してはいけないこと」「6. 書いてよいファイル」です。自分の作業に写すときは、1の頼みごと、4の検査と期待値、6のファイル名などを、自分のものに書き換えます。
指示書の枠
# 指示書 — 手順書の表記ゆれ直し / 第3回
| 項目 | 値 |
|---|---|
| 担当 | 文書の直し役 |
| 工程 | 直し |
| 連番 | 0003 |
| 作業場所 | 作業用にコピーしたフォルダ（元のフォルダに触らない） |
| 報告書 | reports/0003.md（下の報告書の枠を使う） |
| 許された判定 | COMPLETE / UNRESOLVED（合格・不合格は書かない） |
## 1. この回は何か
「サーバ」と「サーバー」が混ざっている。「サーバー」にそろえる。
## 2. 決まっていること（論じ直さない）
- 表記は「サーバー」。見出しの番号と並びは変えない。
## 3. 読むもの
- docs/手順書.md だけ（ほかの文書は読まない）
## 4. 出す前の検査（出力をそのまま報告書に写す）
- grep -cE "サーバ([^ー]|$)" docs/手順書.md → 期待値 0
- grep -c "^## " docs/手順書.md → 期待値 12（見出しの数が変わっていない）
どれも期待どおりになるまで直してから出す。
## 5. してはいけないこと
- 書いてよい所の外を書き換えない
- 検査を通すために、検査のほうや見出しを変えない
- 元のフォルダに書き戻さない（元のフォルダへの反映は依頼者がする）
## 6. 書いてよいファイル
- docs/手順書.md
- reports/0003.md
## 7. 完了条件（1つでも欠けていたら終わりではない）
1. 表記が「サーバー」にそろっている（そろえられない所があれば UNRESOLVED とし、理由を書く）
2. §4 の出力が報告書にあり、期待どおりである
3. 報告書の成果物一覧に、変えたファイルと報告書自身が書いてあるgrep -c "言葉" ファイル は、ファイルの中でその言葉を含む行の数を数えるコマンドです。枠の1つ目の検査は、「サーバ」のすぐ後ろが「ー」でない行（行の終わりで切れている行も含む）を数える書き方にしてあります。コマンドを使わない場合は、「エディタの検索で『サーバ』を探し、件数を報告書に書く」のように、数で答えが出る確かめ方にしておくと、返ってきたときに比べられます。枠の中の COMPLETE は「終わった」、UNRESOLVED は「終わらなかった」の意味です。
報告書の枠
# 報告書 — 手順書の表記ゆれ直し / 第3回
| 担当 | 連番 | 指示書 | 判定 |
|---|---|---|---|
| 文書の直し役 | 0003 | 指示書 0003 | COMPLETE |
## 1. 結論
## 2. 成果物一覧（この表に無いファイルは無いものとして扱う）
## 3. 参照した入力
## 4. 判定と根拠（検査の出力をここに貼る）
## 5. 未決事項
## 6. リスク（できなかった確かめもここに）
## 7. 次の担当への依頼
## 8. 完了条件の自己チェック（指示書の完了条件を1行ずつ）使うときのコツは、記録から読み取れる範囲で3つです。
- 判定の言葉を2つに絞り、作る側に「合格」を名乗らせない。
- 検査の出力は写させたうえで、受け取った側でも流し直す。
- 検査が通っても、見て確かめる所は別に残す。コマンドで分かるのは形までだった、というのが今回の記録です（後の「うまくいかなかった所」の1と2）。
ただし、これは1件の開発の記録です。この型が別の開発でもうまくいくかは確かめていません。
「できました」が本当かを確かめるには：検査のコマンドと期待値の書き方（枠の4）
ここからは、枠の部品ごとに、もとの記録でどう書かれていたかを見ていきます。書いてあるのは1件の開発の記録にあった書き方で、こう書けばうまくいくと確かめたものではありません。
もとにした記録は、2026-11-10 11:32 時点で、指示書が38本（38番目は 11:32 に出たばかりで、まだ結果が無い）、報告書が36本です。指示書を書いているのは、進行役のAI（記録上の呼び名は「PM補佐」）です。受け取る側は、役割ごとに Claude（要件・設計・レビュー）、Codex（調査・保存形式の設計・実装・テストのレビュー）、Antigravity（システムテストの設計と実施）に分かれています。Claude と Codex は記録上の担当名で、動かしている製品は Claude Code と Codex CLI です（2026-11-10 に運営者に確認）。
開発全体の流れ（誰が何を担当し、どこで差し戻しになったか）は、先に公開した記事にまとめています。
出す前の検査：期待値と、出力を写す先まで書かれていた
テスト項目を設計させた6番目と8番目の指示書には、「出す前の検査（報告書 §6 に出力をそのまま写す）」という節があります。中身は、出来上がった文書に対して流す短いコマンドと、その期待値です。
8番目の指示書で確かめさせていたのは、例えば次のようなものです（中身は言い換えています）。
- 受入基準（合格の条件）の番号が、決まった29件から外れていないか → 期待値は「空」
- 「または」のような逃げの書き方が残っていないか → 期待値は「0件」
- 項目の数が、単体12・システムテスト15・人の目で見る確認2 のままか → 期待値は「12・15・2」
- 差し戻しで直すよう言われた言葉が、直したはずの行に入っているか → 期待値は「1件以上」
そして「どれも期待どおりになるまで直してから出す」と書かれています。報告書の側には、出力がそのまま貼られていました。
実装や直しの回では、同じ役目の節が「確かめ方」という名前になっています。37番目の指示書では、次の3つを流して出力を報告書に写すよう求めていました。lint（リント）は、プログラムの書き方の誤りや決まり違反を自動で探す道具、単体試験は、部品1つずつをプログラムで自動的に確かめる試験です。
- lint を流して、エラー0
- 単体試験を流して、12件が通る（試験を足さない・分けない）
- 変えたプログラムのファイルそれぞれに、文法だけの確かめ
これに加えて「変えたファイルと関数、直したことをどう確かめたか（試験の中か・読んでか）の表を出す」とあります。確かめ方まで指定すると、報告書の中身が比べられる形でそろう、というのが記録から読み取れる使い方です。
写された出力を、進行役も流し直していた
もう1つ大事なのは、進行役が写された出力を信じて終わりにしていないことです。進捗の記録には、6番目と8番目のあと「PM補佐が検査を流し直し」て期待どおりだったことを確かめた、と残っています。実装の回では、実装担当のAIがネットにつながらない環境で動いていたため、進行役が毎回、部品の導入（インストール）・lint・単体試験・起動・画面の確かめを自分で流して記録していました。
判定の言葉は2つに限られていた（枠の「許された判定」）
38本すべてが、本文の前に、担当・工程・連番・作業場所・許された判定などを書いた表を置いています。目を引くのは「許された判定」の欄です。作る・直す回やテストの回は「COMPLETE（終わった）／UNRESOLVED（終わらなかった）」、レビューの回は「PASS（合格）／REWORK（差し戻し）」の2つに限っていました。テストを設計する回の指示書には「PASS と書かない」と念押しがあり、システムテストを実施する回には「合否を決めない」とあります。作る担当やテストをする担当に、合否を名乗らせない形です。
完了条件には、終わらなかったときの返し方も入っていた（枠の7）
38本すべてに完了条件があり、そのうち17本は見出しに「1つでも欠けていたら終わりではない」と添えています。37番目の完了条件は4つでした。
- 頼んだ食い違いが直っている（直せなければ「終わらなかった」とし、理由を書く）
- 変えた所と確かめ方の表が報告書にある
- lint・単体試験・文法の確かめが通り、出力が報告書にある
- 報告書の成果物一覧に、報告書自身と作ったファイルが全部書かれている
「直せなければ UNRESOLVED とし、なぜかを書く」と、失敗したときの返し方まで完了条件に入っているのがポイントです。
頼んでいない所まで書き換えられたくないとき：書いてよいファイルと、してはいけないことの書き方（枠の5・6）
38本のうち15本は「出力（書いてよい場所）」、21本は「出していいもの」、2本は「成果物」という節で、書いてよいファイルを列挙しています。37番目の指示書の書き方はこうです（場所の名前は言い換えています）。
- 画面のプログラムの置き場
- 裏側のプログラムの置き場（画面へ知らせるのに要るときだけ）
- 単体試験の置き場
- この回の報告書
- 担当どうしの申し送り書（書くときだけ）
その反対側に「してはいけないこと」が番号付きで並びます。37番目では、たとえば次のとおりです。コミットは、変更をひとまとまりの記録として確定させることです。
- 書いてよい所の外を書き換えない
- 模擬の配信の出し方や一覧の件数の設定を変えて、食い違いを隠さない
- 外部のサイトにつながない、アプリを起動しない
- コミットなどの記録の操作をしない（コミットは進行役がする）
- 新しい部品（依存するライブラリ）を足さない、設定ファイルを変えない
「食い違いを隠さない」のように、近道をふさぐ書き方になっているのが特徴です。試験を通すために試験の条件のほうを変える、という逃げ道を先に閉じています。
書いてよいファイルは、指示書の本文とは別に、入力と出力の一覧ファイル（JSON形式）にも outputs_allowed（出してよいもの）として書かれ、同じファイルに allowed_results（許された判定）と、読む入力の一覧（必須か任意かの印つき）が入っていました。
読むものの書き方（枠の3）
読むものは、多くの指示書で「一覧ファイルのとおり。大きい文書は検索で行を探してから要る所だけ読む」と書かれています。
変わった使い方が16番目の指示書です。「文書だけを読んで機能を足せるか」を確かめる回だったので、「読んでよいもの（これ以外を読まない）」として手引きの文書と見本（ほかは規則や雛形など最小限）だけを挙げ、本体のプログラムや他の文書を読むことを禁じていました。読ませない物を決めることで、試したいことだけを試す形です。
決まっていることには「論じ直さない」と書かれていた（枠の2）
設計やレビューの回の指示書には「着手前に決まっていること（論じ直さない）」が書かれています。要件や前の回で決めたことを、受け取ったAIが蒸し返さないように書く欄です。
返ってきた報告のどこを見ればよいか：先に決めてあった報告書の8つの欄（報告書の枠）
報告書は36本とも、冒頭の表（担当・工程・連番・指示書・実施日・戻り先・判定）のあとに、同じ順で8つの欄が並んでいました。
| 欄 | 書くこと |
|---|---|
| 1. 結論 | 何をして、どうなったかを数行で |
| 2. 成果物一覧 | 作ったり変えたりしたファイルを表で。報告書自身も入れる |
| 3. 参照した入力 | 実際に読んだもの |
| 4. 判定と根拠 | 許された判定のどちらか、と、その根拠 |
| 5. 未決事項 | 決まっていないこと |
| 6. リスク | 気になること、この回でできなかった確かめ |
| 7. 次のpersonaへの依頼事項 | 次の担当にしてほしいこと |
| 8. 完了条件の自己チェック | 指示書の完了条件を1行ずつ写し、合っているかを書く |
36本のうち8本には、成果物一覧の欄に「この表に無いファイルは存在しないものとして扱われる」という一文が入っていました。一覧に無い物は無い物として扱うと決めておけば、一覧に書かずに増やしたファイルは成果物として認められない、という決め方です。
報告書の中には、うまくいかなかったことも書かれています。37番目の報告書には、最初に単体試験を流したら1件が失敗し、古い試験の手順を直してから流し直して12件が通った、と書かれていました。35番目のレビューの報告書には「読むだけで確かめられなかったもの」が並び、試験は指示書のとおり自分では流さず、進行役の記録と前の報告書を使った、と書かれています。
うまくいかなかった所：検査が通っても確かめきれなかった2件と、報告書が出なかった1件
1. 形の検査は全部通ったのに、中身で差し戻された
6番目の工程（テスト項目の設計）のあと、進行役は「出す前の検査」を流し直して、番号の抜け・余り・逃げの書き方などがすべて0件だったことを確かめています。それでも、次の7番目のレビューで4件の指摘が出て差し戻しになりました（画面の文字だけでは合否を決められない項目、要件と反対のことを合格条件にしている項目など）。
検査コマンドが見られるのは「形」まででした。直しの8番目の指示書では、元の検査に3つを足しています。4件の指摘のうち3件について、直したはずの言葉が該当の行に入っているか・消すべき書き方が0件か、を数える検査です（残る1件に当たる検査は足されていません）。8番目の報告書にはその出力が貼られ、進行役が流し直して全部期待どおりと記録しています。
2. 検査がすべて通っても、画面では壊れていた
30番目の直しの後、lint はエラー0、単体試験は12件とも通っていました。ところが進行役がアプリを起動すると、一覧が最初の1回しか描かれませんでした。単体試験で使っていた作り物の画面の部品と、本物の画面の部品とで、振る舞いが違っていたためです（詳しくは全体の記事に書きました）。
実装や直しの回の指示書には、30番目より前の12番目から「アプリを起こさない（画面の確かめは PM補佐がこの回の後にする）」という書き方があり、30番目にも37番目にも同じ文があります。コマンドで確かめる担当と、画面で確かめる担当は、この件の前から分かれていました。30番目の不具合も、その画面の確かめで見つかっています。
3. 報告書が出なかった回（36番目）
36番目は、システムテストのやり直しでした。指示書には「道具が使えず進めないときは、どこで何が出たかを書いて進められるだけ進め、UNRESOLVED で返す」と書いてあります。ところが実際には、テスター役のAIの応答が、AIの提供元の側のフィルターに止められ、結果の記録・画面の画像・報告書のどれも書かれずに終わりました。
記録に残っている扱いは、次の順です。
- 指示を出す道具が、この回を「終わらなかった・報告書が無い」と分類し、行き詰まりの回数を 1（上限3）にした
- 進行役が、テスター役が何をしたかを確かめた。開いたページは手元のパソコンの試験用ページだけ、ファイルの書き込みは0、コマンドは変更の履歴を読むもの1回だけ。試験の結果は残っていない
- 進行役が同じ起動のままアプリを自分で確かめ、食い違いを1件見つけた
- その食い違いを直す37番目の指示書を出し、37番目が終わった時点で行き詰まりの回数を0に戻した
- テスト用に一時的に登録した道具を外し、次のやり直しには人の許可をもう一度取ると記録した
この回で何を書いておけば記録が残ったのか、次のやり直しの指示書がどう変わるのかは、11:32 の時点ではまだ記録がありません。
この枠はどこまで当てにできるか：記録の範囲と、まだ分からないこと
上の枠は、2026-11-10 11:32 時点の記録の型を一般化したもので、実際の作業で使って試してはいません。もとにしたのは1件の開発の記録で、この型が別の開発でもうまくいくかは確かめていません。記録にあったのは次のことです。
- 出す前の検査（作る回では「確かめ方」）は、コマンドと期待値を書き、出力を報告書に写させる形でした。進行役は自分でも流し直しています。
- 報告書は8つの欄で、最後に完了条件の自己チェックが付きます。
- それでも、形の検査が通ったのに中身で差し戻された回、検査が通ったのに画面で壊れていた回、報告書が出なかった回がありました。
開発はまだ途中です。システムテストのやり直しの結果が出たら、この記事にも追記します。
コメント