AI向けの文書（CLAUDE.md や AGENTS.md など）は、書いた本人には通じたかどうかが分かりません。頭の中の前提で、書いていないことまで補って読むからです。この記事を読むと、書いた本人ではない別の起動に文書だけを渡して機能を1つ作らせ、通じなかった点を文書の直しへ戻す確かめを、自分の文書で試せます。ただし実際に試した文書は機能の足し方の文書で、CLAUDE.md ではありません。もとにしたのは、2026-11-10 19:11 に完了として閉じた1件目の開発の記録で、人間による実機での確認はまだ済んでいません。
試した「機能の足し方の文書」は、運営者が自分用に作っているコメント管理のデスクトップアプリ（LiveJazzup）の最初の開発で、AIに書かせたものです。CLAUDE.md の書き方（置き場所・分量・書く項目）そのものは、この記事では扱いません。そちらは検索で上位に出る記事に任せ、ここでは「書いたあとに通じるかをどう確かめるか」だけを書きます。
この開発は 2026-11-09 22:37 に始まりました。この記事で主に使うのは、文書を書いた回と、その文書だけから機能を足させた回（2026-11-10 01:39〜02:03）、その後のレビューの指摘です。
文書を書いたのも、試した側も、Codex（Codex CLI）の実装担当です。試した側は別の製品ではなく、同じ製品の別の起動で、読んでよいものを文書に絞った形です。レビューを受け持ったのは Claude Code の担当です（製品名は 2026-11-10 に運営者に確認）。
指示書の共通の欄（担当・作業場所・書いてよいファイル・完了条件）の書き方は、前の記事に載せました。この記事は、そこに足す「文書を試させる回」の分だけを書きます。塊ごとに実装を確かめる手順は別の記事です。
- 指示書の共通の欄：Claude Code・Codexへのプロンプトに確かめ方を書く：指示書と報告書の枠
- 実装を塊ごとに確かめる手順：Claude CodeとCodexの併用：Codex CLIの実装を塊ごとに別のAIで確かめて受け渡す手順
別の起動に文書だけを渡して確かめる：写して使う手順
ここに載せるのは、記録の指示書を一般化した型です。例は自作で、記録の中身ではありません。「備品の貸し出しを記録する、小さなアプリ」に、機能を1つ足させる場面を想定しています。この型を、私たちが別の開発で使って試してはいません。
先に言葉をそろえておきます。起動は、AIコーディングエージェントを新しく立ち上げて、1回分の仕事をさせることです。書いた側の会話の続きではなく、白紙から始まります。lint（リント）は、プログラムの書き方の誤りや決まり違反を自動で探す道具です。単体試験は、部品1つずつをプログラムで自動的に確かめる試験です。
なぜ、書いた本人に試させないのか
文書を書いた起動が、その文書の試験用の機能も書くと、文書に無いことを知ったまま書けてしまいます。記録では、これを避けるために、文書と仕組みを作る回と、文書だけから試験用の機能を足す回を分けました。
あなたが自分で文書を読み返して確かめる場合も、同じ穴があると考えています。書いた本人は、書いていないことを頭の中で補って読むからです。
確かめの流れ
- 文書を書く回と、試す回を分ける。試す回は、文書を書いた起動ではなく、新しい起動に渡す
- 試す起動に作らせるものを決める。文書が約束していることを一通り通る、小さな機能を1つにする（記録では、設定の項目1つ・コメント1件ごとの受信・自分の画面1つの3つ）
- 読んでよいものを列挙し、それ以外は読まないと禁止する
- 作らせた後に、文書のどの節に従ったかの表と、文書だけでは足りなかったことを、報告書に書かせる
- 確かめ役が、足りなかったことを文書（または lint の設定のような規則）の直しへ戻し、直したことを記録に残す
別の起動に渡す指示文の型
記録で試した起動に渡した指示書（7つの節）を、自作の例に置き換えました。
# 指示書：足し方の文書だけで、機能を1つ足せるかの確かめ
## 1. この回は何か
アプリ（備品の貸し出しを記録する小さなアプリ）には機能を足す仕組みがあり、
足し方は「足し方の文書」に書いてある。
この回は、その文書の手順だけで、試験用の機能を1つ足す。目的は、文書が通じるかを確かめること。
読んでよいものを絞る（§3）。アプリのソースや設計の文書を読んで、仕組みを推し量らない。
文書だけで足りなかったことは、それ自体がこの回の大事な結果になる。
## 2. 作るもの
| # | 決め |
|---|---|
| 1 | 名前は「確認用の機能」。置き場所と登録は、文書が「試験専用」と書くとおりにする |
| 2 | 設定の項目を1つ以上持つ（設定の画面に出る欄） |
| 3 | 貸し出しの記録1件ごとを受け取り、件数を数える。記録は落とさない |
| 4 | ブラウザで開ける自分の画面を1つ持ち、件数を文字で出す |
| 5 | 文書が案内する見本は読んでよい。中身は写さず、自分で書く |
## 3. 読んでよいもの（これ以外を読まない）
1. この指示書
2. 足し方の文書（主の入力）
3. 文書が名指しする見本の機能
4. 足す先の登録の一覧
5. 確かめに要る設定ファイルの、命令の欄だけ
6. 共通の規則と、報告書の雛形
読まない：アプリのソース・単体試験・設計の文書・足し方の文書以外の文書
（lint と試験が画面に出す文言を読むのはよい）
## 4. 確かめ方
lint がエラー 0、元からある試験が通り続けること。出力を報告書に写す。
アプリは起こさない。部品の導入もしない。外へ繋がない。
文書だけでは足りなかったこと（書いていなかった・書き方が分からなかった・
書いてあるとおりにしたら lint や試験が通らなかった、など）は、
どんなに小さくても報告書の「未決事項」に1つずつ書く。
どこで・何が分からなかったか・どう判断したか、を添える。
足りないことのために、§6 の外を直さない。
直さないと通らないなら、そのまま「未解決」で返し、何が足りないかを書く。
足りないことが無ければ「無し」と書く。
## 5. してはいけないこと
§6 の外を書き換えない／外へ繋がない／アプリを起こさない／
変更を確定させない（確かめ役がする）／部品を足さない
## 6. 出していいもの
確認用の機能のフォルダ、登録の一覧、報告書
## 7. 完了条件（1つでも欠けていたら終わりではない）
1. §2 の各行を、文書のどの節に従って満たしたかの表が、報告書にある
2. lint・試験・構文確認の出力が、報告書にある
3. 報告書の未決事項に、「文書だけでは足りなかったこと」の一覧（無ければ「無し」）がある
4. 読んだものを全部、報告書に書いている（§3 の範囲だけであること）自分の文書に写すときは、§1 の文書の名前・§2 の作らせるもの・§3 の読んでよいものを書き換えます。§4 の「足りなかったことを1つずつ書かせる」と「範囲の外を直さない」は、そのまま使えます。
渡してよいもの・渡さないもの
| 区分 | もの | 理由 |
|---|---|---|
| 渡す | 確かめたい文書 | 試す対象。主の入力にする |
| 渡す | 文書が名指しする見本 | 文書が「読むように」と案内しているので読んでよい。写すのは禁止 |
| 渡す | 足す先の登録の一覧、確かめに要る設定の命令の欄 | 作業に要る |
| 渡す | lint・試験が出す文言 | 読んでよい |
| 渡す | 共通の規則、報告書の雛形 | 記録でも渡っていた（下の注） |
| 渡さない | アプリのソース、単体試験 | 読んで仕組みを推し量ると、文書が通じたのかが分からなくなる |
| 渡さない | 設計の文書、文書以外の文書 | 同上 |
注：記録で試した起動には、文書のほかに、共通の規則・報告書の雛形・起動時に自動で渡る案内の文書も渡っていました。だから、記録から「文書1枚だけで通じた」とは言えません。言えるのは、アプリのソースと設計の文書を読ませず、足し方の文書と見本の指定だけを入口にして、作れたところまでです。
通じなかった点の報告のさせ方
指示書の §4 のとおり、「文書だけでは足りなかったこと」の欄を報告書に作り、どんなに小さくても1つずつ書かせます。足りないことが無ければ「無し」と書かせます。書かせる型は、記録で実際に出た1件を、言い換えて写すとこうなります。
## 5. 未決事項（文書だけでは足りなかったこと）
- どこで：文書の「画面の入口」の節と見本は、ブラウザ側で fetch と document を直接書く。
同じ書き方を試験用の置き場所に適用すると、lint が no-undef 3件で失敗した
- 何が足りなかったか：文書に、試験用の画面で lint を通す書き方が無かった
- どう判断したか：globalThis 経由で参照して通した。
文書の追記が要るかは、確かめ役の判断に任せるここで使っている言葉を説明します。fetch と document は、ブラウザの中で動く JavaScript（JS）が、通信と画面の部品を扱うために使う命令の名前です。no-undef は、lint が「定義されていない名前を使っている」と出すエラーの名前です。globalThis は、どこからでも見える全体の置き場で、そこ経由で書くと lint を通せます。
ここで大事なのは、試した起動に範囲の外を直させないことです。lint を通すには lint の設定を直す手もある場面でしたが、記録の起動は設定に触れず、書き方を変えて回避し、足りなかったことを報告しました。直さないと通らないときは「未解決」で返させます。そうしないと、文書の穴が、試す側の手直しで埋まって見えなくなります。
文書へ戻す
報告を受けた確かめ役は、足りなかったことを、文書・規則・その両方のどれの直しにするかを決めます。記録では、上の1件について次のように進みました。
- 確かめ役が報告を受け、「規則の対象に試験用の画面の JS を足し、文書にも一言足す」という方針を記録に書いた
- その後の直しの回で、規則（lint の対象）に、試験用の画面の JS を足した
- 進行役が、文書と規則の食い違いに気づいて再レビューへ渡し、別の担当のコードのレビューが、それを食い違いとして確定した（詳しくは下の記録）
- 直しは、規則を緩めず、文書を規則に揃える形だった
戻し方の決まりは、記録には書かれていません。ここに書いたのは、記録で実際に起きた順です。
CLAUDE.md や AGENTS.md に当てはめるとき
この型を CLAUDE.md や AGENTS.md に当てはめた記録は、この記事の範囲にありません。 試した文書は「機能の足し方の文書」で、「プロジェクトの決まりを毎回読ませるファイル」とは性質が違います。同じ型が使えるかは、あなたが自分で試すときの出発点として書きます。効いたとは書けません。
試すなら、入れ替える所は次の3つです。
- 足し方の文書 → あなたの CLAUDE.md や AGENTS.md
- 作らせるもの → その文書が約束していることを一通り通る、小さな作業を1つ
- 読んでよいもの → その文書と、作業に要る最小のもの
もう1点、確かめていないことがあります。記録では、試した起動に起動時に自動で渡る文書もありました。使う道具によっては、決まりの文書が起動時に自動で読まれることがあるので、「文書だけ」を渡す切り方が変わるかもしれません。これも、この記録では確かめていません。
確かめた日と環境
上の型は、2026-11-10 の記録の指示書を、自作の例に置き換えたものです。記録で lint・単体試験・構文確認を流したのも 2026-11-10 です。npm run lint・npm test・node --check は、そのプロジェクトの設定ファイルに書いた命令の名前なので、あなたのプロジェクトでは違うことがあります。道具の版・料金プラン・設定は確認していないので、書いていません。
根拠にした記録：文書を書いた回と、文書だけから足させた回
ここからは、上の型のもとになった記録です。順番は、確かめた順ではなく、「何を渡して、何が返り、何が通じなかったか」で並べます。
担当の分け方
- 文書と仕組みを作った回・試した回：Codex。記録上の担当名で、動かしている製品は Codex CLI です（2026-11-10 に運営者に確認）。別の製品に試させたのではなく、同じ製品の別の起動です。
- 指示書を書いて結果を受け、次を決める役：進行役のAI（記録上の呼び名は「PM補佐」）。どの製品かは、この記事では確かめていません。
- コードのレビュー：Claude。動かしている製品は Claude Code です（同じく運営者に確認）。実装が終わった後に入りました。
3つの回の流れ
| 回 | 時刻（2026-11-10） | やったこと |
|---|---|---|
| 文書と仕組みを作る回 | 01:39 に始まり 01:53 に終了 | 機能を足す仕組みと見本、そして足し方の文書を作った。試験用の機能は、この回では作らない決めだった |
| 直しの回 | 01:57 に終了 | 画面の不具合を直した（文書の試しとは別の件） |
| 試す回 | 01:57 に始まり 02:03 に終了 | 文書だけから、試験用の機能を1つ足した |
ここで注意があります。文書と仕組みを作る回の指示書には「試験用の機能は次の回で、文書だけを渡された別の起動が作る」と書かれていました。ところが実際には、間に画面の不具合の直しの回が1回入り、その次の回で試しました。「直しの回が試す回だった」ではありません。
文書を書く回の指示書は、足し方の文書に載せる項目として、置き場所と登録の仕方・名乗るもの・受け取れるもの・順と1件を落とせる条件・設定の持たせ方・ブラウザの入口の足し方・失敗したときの扱い・見本の読み方などを挙げていました（指示書が決めた載せる項目で、文書の中身をこの記事のために読み直したわけではありません）。
記録では、足す機能を「拡張」と呼びます。試す回の前に、開発の要件には「足し方の文書の手順だけで、見本のほかに拡張を1つ足せる」という約束がありました。試す回は、この約束を確かめるためのものです。
試す起動に作らせたもの
指示書が決めた作らせるものは6つでした。設定の項目を少なくとも1つ・コメント1件ごとを受け取って件数を数える（コメントは落とさない）・ブラウザから開ける自分の画面を1つ（受け取った件数を文字で出す）・日本語の表示名と順の番号・見本とは書き方を変える（見本は読んでよいが写さない）・置き場所と登録は文書のとおりにする、です。
結果
| 確かめた人 | 見たもの | 結果 |
|---|---|---|
| 試した起動 | 作った・変えた JS 3つの構文確認 | 3件とも終了コード 0 |
| 試した起動 | lint | エラー 0 |
| 試した起動 | 単体試験 | 12件 pass（元からある12件。足したのではない） |
| 試した起動 | 作らせた6項目と文書の節の対応表 | 6項目すべてに、従った文書の節が書かれた |
| 進行役 | 報告書の「読んだもの」と、指示書の範囲の照合 | アプリのソースは読んでいない。進行役の記録は「指示書の範囲だけ」。ただし報告書の一覧には、指示書の一覧に無い文書（共通の規則の1本・入力の一覧・起動時に自動で渡る案内）も載っていた |
| 進行役 | アプリを起こして確かめ | 設定の欄に足した機能が出た。自分の画面に「受け取ったコメント: 13件」が文字で出て、模擬配信で件数が進んだ。ブラウザのコンソール（開発者向けの画面）のエラーは 0 |
| コードのレビュー | 文書が約束の項目を覆っているか | 文書が6つの項目（受け取れるもの・順と落とす条件・設定・ブラウザの入口・見本ほか）を覆い、実際に文書だけから足されている、と確認した |
「受け取ったコメント: 13件」は、進行役が見た模擬配信の、その時点の値です。
通じなかった点は3件。見つけた人が別だった
通じなかった点は、見つけた人ごとに分けないと、混ざります。
| # | 見つけた人 | 通じなかったこと | その後 |
|---|---|---|---|
| 1 | 試した起動 | 文書と見本のとおり、ブラウザ側で fetch と document を直接書くと、試験用の置き場所では lint が no-undef 3件で落ちた。lint の規則が、その置き場所の画面用 JS に掛かっていなかった | 試した起動は範囲の外を直さず、globalThis 経由で参照して回避し、報告書の未決事項に書いた。後の直しの回で、規則の対象に試験用の画面の JS が足された |
| 2 | 進行役（先に気づいた）と、その後のコードのレビュー（Claude Code。食い違いとして確定した） | 文書は「画面の JS も検査される」と名前を限らずに書くが、規則が掛かるのは決まった2つの名前だけだった。別の名前で置くと、同じ失敗に当たる | 規則は緩めず、文書を規則に揃えた。直した後の確認では、見本の置き場所では1つの名前だけが掛かる、という小さな食い違いが、別の指摘として残った |
| 3 | 別のレビュー（インフラ面） | 機能を足した後に、アプリを起こし直す必要があることが文書に書かれていない。登録の一覧は起動時に読まれるので、足しただけでは設定の欄にも入口にも出ない | 試した起動はアプリを起こさない決まりだったので、起こし直しに当たる場面が試しの中に無かった。直しが済んだかは確認していない |
1番は、試す起動に「文書だけで足りなかったことを1つずつ書け」と頼んであったので、報告書の未決事項に残りました。この1件は前の記事（塊ごとの確かめ）にも1段落で載せています。この記事では、試す側への指示と、文書へ戻す側を書いています。
うまくいかなかった所・確かめきれなかったもの
1回の試しでは、文書の穴は全部は出なかった
試した起動が見つけた文書の穴は1件でした。その後、文書と規則の食い違い（進行役が先に気づき、レビューが確定した）と、起こし直しが書かれていない穴（インフラのレビュー）が別に2件出ています。つまり、1回の試しで出ない穴があります。「1回試して通れば、文書は十分」とは言えません。
試す側の条件が、穴を隠した
3番めの穴は、試す側がアプリを起こせない決まりだったので、試しの中では当たりようがありませんでした。ネットを使えない・アプリを起こせないといった試す側の条件が、文書の穴を隠すことがあります。あなたが試す場合は、試す側に何をさせないか（何をさせられないか）を決めるときに、その決めが何を見えなくするかも、一緒に考えてください。
同じ製品の別の起動に試させた
試した側は、文書を書いたのと同じ製品（Codex CLI）の、別の起動でした。別の製品のAIに試させたら通じるか・通じないかは、この記録では確かめていません。
直した文書を、もう一度試したかは確かめていない
直しの後に、直した文書を別の起動に試し直させた記録は、この記事で使った範囲には読んでいません。直しが効いたかを、同じ手順で確かめ直したとは書けません。
人間による実機での確認が済んでいない
この開発は完了として閉じましたが、人間による実機での確認は、閉じた時点で済んでいません。進行役が見たのは、ブラウザで開く試験用の画面と設定の欄で、アプリ本体の窓での確認ではありません。
この型をどこまで当てにできるか
これは、1件の開発・1回の試しの記録です。通じなかった点を試した起動が見つけたのは1件で、進行役とレビューが見つけた2件を足しても3件です。型は記録の指示書を写したもので、別の開発では試していません。CLAUDE.md や AGENTS.md に使えるかは、この記録では確かめていません。
コメント