1
0

Delete article

Deleted articles cannot be recovered.

Draft of this article would be also deleted.

Are you sure you want to delete this article?

Claude Codeの手順書は、指定しても読まれない——教訓を「読ませる」から「貼る」「止める」へ変えた3か月の記録

1
Last updated at Posted at 2026-11-15

この記事の要点: Claude Codeでエージェント組織を運用していると、教訓を「書き残す」仕組みは自然に増えていく。だが書いた教訓が「読み出される」かどうかは、置き場所ごとにまったく違う。2026年8月6日、私は自分の環境で、作業種別ごとの手順書(Playbook)が「委任する側が指定したときだけ読まれる」置き場所になっていることに気づいた。その後の約3か月(11月13日まで)の記録を読み直すと、指定しても読まれない場面が残っていた。ある2日間の委任の記録では、指定した手順書が読まれたのは12回中2回だった。効いた対策は、当初考えていた「読み込みを強制するフック」ではなかった。受け手に読ませるのをやめて、渡す側が該当箇所を抜き出して貼ることと、同じ型が繰り返す領域は機械で止めることの2つだった。

教訓を書く仕組みと、読み出す仕組みは別物

結論から書くと、教訓の価値は「何件書いたか」ではなく「必要な場面で、誰の判断にも依存せずに読み出されるか」で決まる。書き込み経路をいくら増やしても、読み出しが受け手の判断に任されている限り、その教訓は書いた時点で効かないことがある。

気づいたきっかけは、Zennで読んだえださんの記事「Sonnet・Opus で Fable 5 相当の成果物を再現するハーネスの設計と検証」だった。上位モデルの単発実行と同等の品質を、下位モデルの組み合わせで出せるかを検証した実験レポートで、ハーネスは6工程で組まれている。その工程①が「教訓の読み出し」で、記事には「実装前にメモリから関連する教訓を読み出して計画・検証・攻撃役に渡す」と書かれている。

なお、同記事の結論は「API 経由で Fable 5 を利用できる場合は、現状では Fable 5 単発を使うほうが、時間・コスト・品質のバランスで有利」というものだ(Fable 5 は、同記事が再現の目標にしている上位モデル)。この記事も「ハーネスを組むべきだ」とは主張しない。扱うのは、ハーネスやルール文書を組むなら教訓の読み出しをどう確実にするか、という設計の話に限る。

最初は「自分の環境のほうが仕組みとして作り込んである」と思った。自分の環境にも、事故から教訓を抜き出してルールに書き戻すループがある。だが比べてみると、中身はほぼ同じで、違いは1点だった。えださんのハーネスでは、教訓の読み出しが工程として固定されている。タスクを回せば必ず発火するので、忘れようがない。私の環境では、読み出しが置き場所ごとにばらばらだった。

Claude Codeの教訓は誰の判断で読まれるのか——置き場所5種を点検する

最初にやるべき点検は、教訓の置き場所を全部書き出し、それぞれ誰の判断で読まれるかを横に書くことだ。8月6日時点の私の環境はこうなっていた。

置き場所 読まれるタイミング 誰の判断に依存するか 確実性
CLAUDE.md・ルールファイル 毎セッション自動で読み込まれる 誰にも依存しない 高
自動メモリ 関連しそうなときにシステムが想起させる システムの想起 中
Playbook(作業種別ごとの手順書) 委任する側が「読むべき手順書: 〇〇」と指定したとき 委任する側 低
事故記録 参照経路なし。ルールへ転記された分だけ効く 転記した人 低
ルール候補のメモ(正式ルールになる前の置き場) 週次レビューで照合したとき 週次レビューを開く人 週1

※ここでの「確実性」は、置き場所の性質から私が付けた分類で、発火率を測った値ではない。

問題は3行目だった。Playbookのファイル数は8月時点の95から今日の93へとほぼ変わらないが、字数は約31万字から約42万字に増えた(どちらも全ファイルの文字数を同じ方法で数えた値。今日の値は2026年11月13日の計測)。この量の手順書が、委任する側がその場で「この作業にはこの手順書」と思い出せたときにしか読まれない。

実際、5月29日には、記事執筆を委任するときに文章ガイドラインの手順書を指定し忘れ、そこに書いてあった既出ルール2件(冒頭の要約段落の欠落・問題提起型記事の締めの宙吊り)と、自動メモリに書いてあった書名の誤記がまとめて再発している。ルールは文書に存在していたのに、指定を忘れた瞬間に存在しないのと同じになった。手順書の量が少ない環境でも事情は同じで、このときの再発は手順書1本の指定忘れから起きている。

自分の環境を点検するときは、表の「誰の判断に依存するか」の列に受け手(または送り手)の名前が入る行を探すとよい。そこが、書いたのに読まれない教訓の溜まり場になる。

Claude Codeで教訓が効かない失敗は、少なくとも4段に分かれる

8月6日の時点では、穴は「指定忘れ」だけだと思っていた。その後3か月で、事故記録は22件から29件に増えた(記録ファイルの数)。それらとルール候補のメモを読み直すと、読み出しの失敗は少なくとも4段に分かれていた(以下の段の分け方は、事故記録とルール候補のメモから私が整理したもの)。

段 何が起きるか 実例
1. 指定忘れ 送り手が「読むべき手順書」を書かない 5月29日(文章ガイドライン)、9月13日(公開リリース手順)
2. 指定しても読まれない 受け手が指定された手順書を開かない 10月17〜18日の実装委任
3. 読んでも効かない 読んだ当日に、書いてある型の誤りを犯す 8月16日の公開リポジトリへの混入
4. 出力が見えていても作用しない その場の検査は走り、問題の行を出力しているのに止まらない 9月13日の同じ行の再混入(1段目とは別件)

1段目: 指定忘れは、8月以降もドメインを変えて起きた

9月13日、公開しているOSSリポジトリのリリースで、内部向けの語6件(エージェントの役割名4件と、個人環境に固有の参照2件)を含むコミットをpushしてしまった。公開されていたのは8分19秒で、気づいて除去した。

事故記録の結論は「ルール不備ではなく、既存の手順書が参照されなかった」だった。リリース用の手順書は事故の前日に、内部語の検査スクリプトの実行を3か所で必須と明記していた。しかもその中には「手動 grep はその場で思いついたパターンしか検査できない」という一文があり、起きたことがほぼそのまま予告されていた。

見落としは二重だった。委任する側が「読むべき手順書」を書かず、委任された実装担当のエージェントも、自分の役割定義にある「公開リリース → この手順書」の対応を自分から引かなかった。事故記録の再発防止欄には「ルールの追加ではなく、遵守の問題」と書かれ、ルールファイルへの追記は「なし」となっている。ルールを書き足しても解決しないことを、記録自身が認めている。

2段目: 指定しても、読まれない

8月の時点では「指定さえすれば読まれる」と思っていた。10月17〜18日の実装委任の記録が、その前提を崩した。

ある委任では、実装担当のエージェントが指定された手順書を読まずに実装し、報告に「手順書との乖離なし。ただし手順書は読んでいない」と書いてきた。そこで完了報告に「読んだ手順書と、そこから適用した注意点」の欄を必須にしたところ、未読は見えるようになった。だが、読ませる効果はなかった。

ルール候補のメモに残っている2日間の記録を数えると、指定した手順書を読んだかがわかる委任は12回あり、読まれたのは2回だった。

  • 読んだ: 2回
  • 読まなかった: 10回(うち7回は、後述の「抜き出して貼る」方式に切り替えた後の委任で、一連のリファクタリング委任6回を含む)

先に書いておくと、この7回は、手順書が読まれなかったからといって失敗したわけではない。必要な注意点を委任文に貼って渡していたので、手順書を読まなくても、貼った注意は守られていた(うち1回は、貼らなかった範囲で見落としが出た。詳しくは後述)。

この数字は率として一般化できるものではない。2日間・1種類のエージェントに偏ったサンプルで、記録は委任する側が書いたものだ。記録に残りやすいのは目立った回だけ、という偏りもある。ここでは「12回中2回」という回数として読んでほしい。

3段目: 読んでも、その場で効かない

8月16日、オーケストレーター役のエージェントが委任せず自分で公開リポジトリへファイルを同期するとき、ファイルごとの同期モードの定義を読まずに丸ごとコピーし、内部向けの1行をpushした。

この日は週次レビューの日で、同じセッションの中で、まさにその定義ファイルを名指しして「差分を見たら先にこれを読め」と書いたルール候補を照合していた。事故記録には「読んだ当日に同じ型の誤りを犯した」とある。読み出し自体は成功していたのに、その後の作業には作用しなかった。

4段目: 検査の出力が見えていても、作用しない

9月13日(1段目とは別件)、8月16日と同じ1行が、同じ経路でもう一度公開リポジトリに混入した(作業したのがオーケストレーター役本人か委任先かは、記録からは特定できていない)。今度は公開状態が11時間19分続いた。

このとき、その場で書いた内部語の検索(grep)は実際に走っていた(用意してあった専用の検査スクリプトは使われていない)。事故記録によれば、その出力の1行目が混入した行そのもので、検査の2分52秒後にpushされている。記録の見出しは「検査は走っていたが、その出力が作用しなかった」だった。何が画面に表示され、どう読まれたかまでは履歴に残っていないため、なぜ見落としたかは断定できない。ただ「検査が走らなかったから漏れた」という説明は成り立たない。

少なくとも3段目は委任を挟まずに起きており、渡す相手がいない場面では後述の対策1(注意点を貼る)では塞がらないので、対策2(機械で止める)が要る。

効かなかった対策: ルールの書き足しと、読了の申告

4段を並べると、効かなかったものの共通点が見える。

  • ルールの書き足し: 1段目の事故には、該当するルールが事前にあった。追記しても「指定を忘れる」ことは防げない
  • 完了報告での読了申告: 未読を見えるようにはしたが、受け手が読むようにはならなかった(2段目)
  • 週次の照合: 照合の当日に同じ型の誤りが起きた(3段目)

ルールの書き足しについては、私自身が8月以降も続けていた。8月11日には記事執筆の委任で投稿先のタグの規約を、8月16日にはスクリプトを書かせる委任で手順書の「既知の注意点」の節を、9月23日にはTypeScriptの委任で型チェックの手順を、それぞれ「読ませる」項目として委任のルールに足している。そして8月16日に「読ませる」と書き足したその手順書が、10月17日の委任(2段目の記録)では読まれずに実装が進んだ。書き足しが効かなかったことの、いちばん直接の証拠になる。

どれも、最後は受け手(またはその場の作業者)が自分の判断で教訓を思い出して適用することに頼っている。読み出しが受け手の判断に依存している限り、置き場所をいくら整えても、どこかの段で落ちる。

効いた対策1: 手順書を読ませず、注意点を委任文に貼る

効いたのは、読み出しの責任を受け手から送り手に移すことだった。「〇〇を読むこと」と書くのをやめて、今回の作業に当てはまる注意点の本文を、委任する側が手順書から抜き出して委任文に貼る。

抜き出すのは私ではなく、委任する側のオーケストレーター役のエージェントだ。私が毎回手で手順書をめくっているわけではない。なお、受け手に手順書を丸ごと読ませる場合と比べてトークン量がどう変わるかは測っていない。

10月17日に、ルール候補のメモにこの方式を記録した。きっかけは、オーケストレーター役がある委任の差分を手順書の注意点の見出し一覧と照合する作業が、数分で終わったことだった。記録には「読む側に任せるより、渡す側が抜き出すほうが確実で安い」とある。

委任文の形

実際の委任文は作業ごとに違うが、形はこうなる。

## 今回の作業に当てはまる注意点(手順書から抜粋)

1. macOS 標準の bash 3.2 では、裸の $VAR の直後に非ASCII文字が
   続くと、その文字が変数名の一部として解釈される(set -u 有効時は
   unbound variable で停止)。変数展開は ${VAR} の形で書く
   NG: echo "対象: $ENTRY_ID($COUNT件)"
   OK: echo "対象: ${ENTRY_ID}(${COUNT}件)"
2. 読み取れなかったデータを「問題なし」扱いにしない。
   取得に失敗したらエラー終了する
3. (当てはまる項目がなければ「該当なし」と書く)

## 完了報告に含めること
- 上の各項目について、どう対応したかを1行ずつ

ポイントは2つある。抜き出すのは見出しではなく**本文(NG/OK例を含む)**であること。そして、当てはまる項目がない場合も「該当なし」と明記すること。何も書かないと、受け手からは「確認したうえで該当なし」なのか「確認を忘れた」のかが区別できない。

完了報告は、たとえば次の形で返ってくる(説明のための形式の例)。

- 項目1: 対応済み。非ASCII文字の直前の変数展開を ${VAR} 形式にした
- 項目2: 対応済み。取得失敗時に終了コード1で止め、テストを追加した

実績

記録に残っている結果は次のとおりだ。

  • ある委任では、貼った4項目すべてに1行ずつ対応が報告され、うち1件は実装とテストに反映された
  • 別の委任では、実装担当は手順書の本体を読まなかったが、貼られた注意(非ASCII文字の直前の変数展開)を実装中に実際に踏み、その注意を根拠に自分で修正した
  • 一連のリファクタリング委任6回でも、貼った項目はすべて守られた。一方で、手順書の本体は6回とも読まれていない

つまり2段目の「12回中2回」の残り10回は、全部が失敗ではない。7回は、手順書を読ませる代わりに抜き出して渡したことで、貼った注意は守られていた(うち1回は、貼らなかった範囲で見落としが出た。次の段落で書く)。貼った範囲については、受け手が手順書を読むかどうかは問題にならなかった。

ただし限界もある。上の2つ目の委任では、貼らなかった範囲(どのファイルが正本で、どれが公開用か)で見落としが出た。抜き出しは、送り手が「今回はこれが当てはまる」と判断できた範囲しかカバーしない。また、この方式はまだルール候補の段階で、正式ルールには昇格していない(2026年11月13日時点)。

効いた対策2: 同じ型の事故が2回起きた領域は、機械で止める

抜き出して貼る方式は、送り手の判断に依存する。送り手が抜き出しを忘れれば、1段目と同じことが起きる。そこで、同じ型の事故が繰り返した領域は、人の注意力に頼らず機械で止めた。

公開リポジトリへの内部語の混入は、8月16日と9月13日に同じ経路で2回起きた。この型を扱っていたルール候補には、記録されてから約1か月の間に、必要だと示す事例が5件たまったが、それで事故を防げた例は1件もなかった。そこで9月14日に、同期スクリプト・push前のゲート・週次の監査を実装し、9月19日の記録で「人の注意力へ戻さない」と位置づけた。それ以降、事故記録に公開リポジトリへの混入は追加されていない(事故記録がないことは、起きていないことの証明にはならない点は断っておく)。

別の領域でも同じ判断をしている。作業を次の段階へ進めたときに元の状態を片付け忘れる型は、4回の週次レビューで検出されたのに、予防には転じなかった。機械検知へ移したときの記録の結論は、「根本原因は、検知ロジックの不在ではなく『検知結果が確実に見られる経路の不在』だった」というものだ。この記事で言っていることを、別の領域で記録自身が言い直している。

どちらを使うかの目安

私の運用からの目安は次のとおりだ(実測した基準ではなく、3か月の記録から引いた経験則)。

状況 手段
作業ごとに当てはまる注意点が違う(スクリプトの書き方の落とし穴など) 送り手が抜き出して貼る
同じ型が同じ経路で2回以上起きた 機械で止める(ゲート・検査スクリプト)
検査はあるが、結果が見られずに素通りする 結果が「必ず見られる場所」に出るよう配線し直す

前の記事「CLAUDE.mdは書いても守られない」の主張を、自分で更新する

前の記事「CLAUDE.mdは書いても守られない——ルールが効かなくなる3つの理由と、22件の事故から学んだハーネスエンジニアリング」で、私は「本当に守らせたいルールはテキストではなく、command実行の仕組みに落とす」と書いた。テキストのルールは説得にとどまる、という主張だ。

3か月後の記録で見ると、この主張は半分当たり、半分外れていた。

  • 当たった側: 公開リポジトリへの混入は、機械で止めて以降、事故記録に追加されていない。その間も公開リポジトリへの同期は続いていた(9月14日以降、公開リポジトリへの同期を記録したコミットは21件、うち10月18日だけで12件)。前の記事の処方箋が、自分の環境では効いていると見ている
  • 外れた側: 委任時の手順書の読み出しについては、当初考えていた「委任の直前に手順書を機械的に引くフック」は作っていない。作らなくても、抜き出して貼るという仕組みではない、テキストの対策で、貼った範囲の注意は守られた。前の記事で「説得にとどまる」と退けたテキストが、置き場所を変えたら効いた。フックが効かなかったのではなく、フック以外にも手段があった、という更新になる

分かれ目は「テキストか仕組みか」ではなかった。読み出しが受け手の判断に依存するかどうかだった。フックは受け手の判断を不要にする手段の1つで、委任文に本文を貼るのはもう1つの手段だ。後者はテキストだが、受け手が開くかどうかに関係なく、作業の指示そのものの中に入っている。

前の記事を読んで検査の仕組みを入れた人には、4段目の話を補足しておきたい。検査の結果を画面に出すだけでは、出力が見えていても素通りすることがある。機械で止めるなら、結果を表示するのではなく、pushそのものを止めるゲートにする。私が9月14日に入れたのも、この形だ。

まだ塞がっていない2つの穴——送り手の指定忘れと、週次レビューの停止

最後に、塞がっていない穴を2つ書いておく。

1つ目は、送り手の指定忘れ。 抜き出して貼る方式は受け手の未読を解消したが、送り手が「何を貼るか」を思い出せなかったときの穴は残っている。5月29日と9月13日の事故は、まさにこの穴から起きた。

この記事を書く準備の中でも、同じことが起きた。8月以降の変化について、オーケストレーター役のエージェントは、調べる前の見立てとして「8月以降に対策ルールがいくつか入った」と私に説明した。ところが、調べる作業を任された別のエージェントが変更履歴で確かめると、8月以降の変更と見られていた項目のうち、文章ガイドラインを読ませる項目は5月29日、ルール候補を週次で照合する仕組みは7月9日の導入で、どちらも8月6日より前からあった。記録されたルールがいつからあるかを、そのルールで動いている側も思い出せていなかった。

2つ目は、想起経路を載せている行事そのものが止まること。 ルール候補の週次照合は、週次レビューが開かれた回では毎回発火していた。8月11日〜10月17日の週次レビュー記録10件すべてに、ルール候補を照合した記述がある。ところが週次レビュー自体が、10月17日を最後に約4週間止まっていた。理由は単純に忙しかったからだ。この空白は、記録ファイルが途切れていることから見つかった。行事が止まれば、そこに載せた想起経路も一緒に止まる。

次の一手は、送り手の判断を減らす方向になる。具体的には、作業種別から「貼るべき注意点」を機械的に候補として出し、送り手は選ぶだけにする形を考えている。これはまだ作っていない。それまでの間は、次の3つを続ける。

  • 教訓の置き場所ごとに「誰の判断で読まれるか」を書き出し、受け手の判断に依存する行を把握しておく
  • 委任するときは「〇〇を読め」と書かず、当てはまる注意点の本文を貼る。当てはまらなければ「該当なし」と書く
  • 同じ型が2回起きた領域は、人の注意力に戻さず機械で止める

教訓を読み出す責任を受け手から送り手へ移すと、次の問いが出てくる——では、送り手であるオーケストレーター役には、何をどこまで持たせ、何を仕組みに渡すべきなのか。

権限・ガバナンス・ルールファイルの層構造まで含めて、その線引きをどう組み立ててきたかを書いたのが、Zenn Books Vol.4「コードを書けない私がClaude Codeに「仕組み」を渡すまで」だ(序章無料)。書名はコードを書かない人向けに見えるが、中身はCLAUDE.md・Playbook・メモリ・権限など7つの置き場所を1章ずつ扱う設計の話で、この記事の点検表の行と重なる。エンジニアの方にもそのまま読んでもらえると思う。

関連記事


この記事は はてなブログ からのクロスポストです。

1
0
2

Register as a new user and use Qiita more conveniently

  1. You get articles that match your needs
  2. You can efficiently read back useful information
  3. You can use dark theme
What you can do with signing up
1
0

Delete article

Deleted articles cannot be recovered.

Draft of this article would be also deleted.

Are you sure you want to delete this article?