はじめに
Claude Code に、技術書を1冊作らせました。本文13ファイル・7,739行、最終的に A4 で327ページの PDF になったものです。
その過程で CLAUDE.md は20節まで増えました。増えた節のほとんどは、事故か失敗の後に足したものです。
最初から書いてあったのは目的と対象読者くらいで、あとは「やらかしてから書き足す」の繰り返しでした。
この記事は、その中で実際に効いた10個をまとめたものです。どれも「こう書いたら良さそう」ではなく、書かなかったせいで何が起きたかを添えてあります。
「CLAUDE.md に何を書けばいいか分からない」という方の、たたき台になればと思います。
1. 公開・送信・課金を伴う操作は、人間の承認を必須にする
いちばん最初に書くべきものです。うちではこう書いています。
商品を自動で公開・アップロード・販売・投稿・外部配布してはならない。
さらに、進行状態を表す値を決めて、AI が設定してよい上限を明記しました。
エージェントが設定してよいのは WAITING_FOR_HUMAN_REVIEW まで。
HUMAN_APPROVED は、人間だけが設定できる。
「止まる場所」を値として持たせるのがポイントです。「気をつけて」では止まりません。状態遷移として書くと、AI は自分がどこまで進んでよいかを判断できます。
実際、商品の投稿・公開はすべて人間がやっています。AI は一度も外部に出していません。
2. 「創作するな」を、対象を列挙して書く
AI は、埋められる空欄があると埋めます。何を創作してはいけないかを、名詞で並べるのが効きました。
出典・URL・コマンドの出力・バージョン差異・商品の価格・
競合の機能・市場の事実を創作してはならない。
抽象的に「正確に書いて」と頼むより、列挙のほうが守られます。
書かなかったときに起きたこと
調査担当が作った根拠の資料に、9か所の誤りが見つかりました。しかも見つけたのは人間ではなく、別の AI（レビュー担当）が商品本文と突き合わせたときです。
内容の一部です。
-
systemctl show -p ...のプロパティ名が誤っている可能性が高いのに、確認済みのラベルが付いていた - ある運用手順が、商品本文と逆の内容で書かれていた
- パッケージ削除のオプションの組み合わせが、上流のソースと食い違っていた
そのうち2件は、最後のレビューで最も重い指摘として出てきました。 資料の誤りは、最後まで本文に残りかけていたということです。
3. 確認済みと推論を、ラベルで分けさせる
2 とセットです。うちでは調査資料の各項目に VERIFIED（確認済み）と INFERRED（推論）を付けさせています。
確認できた事実と、推論とを分けて書く。
ただし、この運用には落とし穴があります。上の 2 で書いたとおり、VERIFIED と書いてあるのに間違っている項目が実際にありました。
ラベルを付けたのも同じ AI です。ラベルは「確認した」の証拠にはなりません。
それでも分ける価値はあります。INFERRED が付いている箇所は、人間が優先的に見る場所として使えるからです。ラベルは信頼の根拠ではなく、点検の優先順位として使うのが正しい使い方でした。
4. 直させる回数に、上限を決める
これは書いておいてよかったものの筆頭です。
Writer と Reviewer の修正のやりとりは、3巡までとする。
3巡目も FAIL だった場合、自動の修正をやめ、
Human Review へのエスカレーションを作る。4巡目を試みない。
なぜ上限が要るのか
直すと、直した場所から新しい欠陥が出るからです。
レビューを9回まわしたときの、各回の新規指摘の件数です。
| 回 | HIGH | MEDIUM | LOW | 計 |
|---|---|---|---|---|
| 1巡目 1回目 | 5 | 29 | 26 | 60 |
| 1巡目 2回目 | 2 | 13 | 19 | 34 |
| 1巡目 3回目 | 2 | 7 | 20 | 29 |
| 2巡目 1回目 | 0 | 11 | 33 | 44 |
| 2巡目 2回目 | 1 | 9 | 32 | 42 |
| 3巡目 1回目 | 0 | 10 | 27 | 37 |
| 3巡目 2回目 | 0 | 7 | 24 | 31 |
| 4巡目 1回目 | 0 | 1 | 17 | 18 |
| 4巡目 2回目 | 0 | 0 | 7 | 7 |
| 計 | 10 | 87 | 205 | 302 |
4行目を見てください。3巡かけて直した直後に、指摘が29件から44件に増えています。
記録にはこう書いてあります。
今回の指摘42件は、すべて「修正ラウンドで新しく入った欠陥」または「これまで見落とされていた欠陥」です。修正が次の欠陥を生む傾向は、サイクル2でも続いています。
さらに1巡目では、部分的にしか直っていなかった4件が、次のラウンドで最も重い指摘2件の原因になりました。
上限を決めておかないと、この往復は終わりません。「あと1回直させれば良くなる」は、だいたい外れます。
5. 危険な操作に「そろえるべき要素」を定義する
「危険なコマンドに気をつけて」では機能しません。何がそろっていれば掲載してよいかを、要素として定義します。
うちでは6つ決めました。
- 強い警告
- 実行前の確認
- 影響
- コマンド（診断のコマンドと分けて書く）
- 実行後の確認
- 復旧・ロールバック（戻せない場合はそう書く）
そして、こう締めます。
これらのどれか1つでも欠けていれば、Technical Reviewer は FAIL とする。
要素に分けておくと、機械的に数えられます。うちでは該当する30ブロックすべてに6要素があるかを確認しました。「気をつけたか」は数えられませんが、「6つあるか」は数えられます。
6. 実機に触らせるなら、境界を先に決める
AI に検証用のサーバを触らせるなら、触ってよい範囲を書く前に作業させないほうがいいです。
うちで決めたのは次の形です。
- 対象を名指しする（IP で。それ以外は対象外と明記）
- 実行前に3点を確認する: 今いるのが対象の機械か ／ ホスト側のパスがマウントされていないか ／ スナップショットがあるか
- 公開鍵認証のみ。パスワードは入力させない（人間が許可しても緩めない、と書く）
- 変更するなら、元に戻すところまでを1つの手順にする
- 実行したものは全部ログに残す
パスワードのところだけ補足します。パスワードを渡す運用を一度でも作ると、そのパスワードが通る範囲すべてが AI の作業範囲になります。鍵なら、渡す鍵を変えるだけで範囲を変えられます。
7. 「確認の方法を疑う」ルールを入れる
ここが、個人的にいちばん学びが大きかったところです。
AI は「確認しました」と報告してきます。その確認の方法自体が壊れていても、同じ顔で報告してきます。
実際に4回起きました。
| 使った道具 | 何を見ていたか | 何が起きたか |
|---|---|---|
| grep | マッチ件数 | 行頭前提のパターンで、字下げされた行を拾えず「除去済み」と誤報告 |
| grep | 行数 | 日本語の文字数を数えたら約1.8倍（13,452字と報告、実際は6,313字） |
| grep | マッチ件数 | 「注意書きが抜けている」と誤判定し、既にある段落と重複させた |
| findmnt | 終了コード | 該当が無くても 0 を返すので、判定が常に「安全」になっていた |
そこでルールにこう書きました。
findmnt は終了コードで判断しない（該当が無くても 0 を返す）。
出力が空かどうかで判断する。
一般化するとこうです。
「0件でした」は「無い」ではなく、「そのやり方では見つからなかった」。
件数や終了コードを判定に使わせない、と明文化しておくと効きます。
8. 報告の形を決める
地味ですが、毎ターン効きます。うちでは3つ書いています。
報告は必ず、次にやること・今の状況・ゴールで終える。
人間に開いてほしいファイルは、名前やパスだけでなく
クリックできる Markdown のリンクを本文に入れる。
シェルのツールで cd を実行しない。
3つ目が変に見えると思うので説明します。cd すると作業ディレクトリが動き、そのあとに書いた相対パスのリンクが全部壊れます。
実際にやらかして、リンクが全滅しました。書いてある今でも、うっかりやることがあります（この記事を書いている最中にも1回やりました）。ルールに書いてあると、少なくとも直後に気づけます。
9. 人間が見るファイルの置き場を、1つに決める
AI の作業フォルダは、人間には読めない速度で増えます。人間が触るファイルだけを集めた入口を作っておくと、探す時間がゼロになります。
うちのルールはこうです。
置くのは元のファイルへのショートカットで、コピーは置かない。
名前は日本語にし、人間が作業する順に番号を振る。
人間が読む・判断するファイルを作ったら、同じターンのうちに更新する。
「コピーを置かない」が要点です。コピーにすると、AI が読むのは元ファイル、人間が直すのはコピー、という食い違いが静かに起きます。
10. 数字の扱いを決める
最後は、売り物を作る人向けです。
プラットフォームが信頼できる根拠を出していない限り、販売数を主張しない。
アクセスできない商品の詳細を創作しない。
競合を調べさせると、AI は「人気」「売れている」を書きたがります。でも、販売数を公開しているプラットフォームはほとんどありません。
うちの競合調査には、こう残っています。
販売数量はいずれの対象についても記録していない。BOOTH/note/Zenn/Leanpub とも販売数を明示しておらず、いいね・ランキング・レビュー数からの推測は行わなかった。
「調べたが分からなかった」と書ける AI にしておくのは、地味ですが効きます。
まとめ
| # | 書くこと | 書かなかったときに起きること |
|---|---|---|
| 1 | 公開・送信の承認を必須にする | 外に出てから気づく |
| 2 | 創作してはいけない対象を列挙する | 資料に誤りが9件入る |
| 3 | 確認済みと推論をラベルで分ける | どこを点検すべきか分からなくなる |
| 4 | 直させる回数に上限を決める | 直すたびに新しい欠陥が入り、終わらない |
| 5 | 危険な操作の必須要素を定義する | 「気をつけた」かどうかを数えられない |
| 6 | 実機に触る境界を決める | 作業範囲が事実上無制限になる |
| 7 | 確認の方法を疑うルールを入れる | 壊れた確認が「確認済み」で通る |
| 8 | 報告の形を決める | リンクが壊れ、次に何をするか分からない |
| 9 | 人間が見るファイルの置き場を決める | 探すのに時間がかかり、中身が食い違う |
| 10 | 数字の扱いを決める | 根拠のない「売れている」が書かれる |
正直に書いておくこと
- 1つのプロジェクト・約2週間の記録です。他のテーマや他の使い方で同じ結果になる保証はありません。
- 10項目はどれも、書いたあとに起きた事故を防げたかどうかを厳密に測ったものではありません。 「書いてから同種の事故が減った」という程度の話です。
- レビューをしたのも AI なので、302件は「AI が AI を見て出した件数」です。人間が読めば別の指摘が出ると思います。
-
findmntの終了コードの挙動は AlmaLinux 8.10 / 9.7 での観測です。ご自身の環境で1度確かめてください。
お気づきの点があればコメントで教えてください。特に 3（ラベルの信頼性）と 4（上限の決め方）は、もっと良いやり方がありそうだと思っています。
使っている実物について
この10項目のもとになった CLAUDE.md の全文と、役割を分けた5体のサブエージェントの定義、そして各ルールが生まれた失敗の記録を、note の記事にまとめてあります。そのまま貼って使えるテンプレートにしてあります。