エージェントのレビューゲートに人間のレビューの形をそのままなぞったところ、著者が既に自分で検証している場所を見ていました。持ち込めるのは原理のほうで、手順ではありません。ただしAI向けに書いた指示には別の問題があって、効いているかどうかを人間が読んでも判定できません。
GitHubGitHub - LabeeHive/standards: Shared standards repository for Labee LLC projects — a Claude Code plugin marketplace of skills, agents, and workflowsShared standards repository for Labee LLC projects — a Claude Code plugin marketplace of skills, agents, and workflows - LabeeHive/standardsなぞったら同じ場所を見ていた
Swiftの開発をタスクから完了まで通すワークフローに、通過しないと先へ進めないゲートを置いています。そこに最初に並べたのは、人間のレビューで見ていた項目でした。テストがあるか、参照を読んだか、TODOが残っていないか。
しばらく回して、並べ方の問題が分かりました。並べた項目は、著者が既に自分で検証していることと重なっています。人間のレビューでこれが成立したのは著者とレビュアーが別人だからで、同じ実行の中で役だけ分けても二度読んでいるだけになります。
見る先を変えたときの記録が残っています（訳は筆者）。
プロセス遵守に向いていた。テストがある、参照を読んだ、TODOが残っていない。それは著者が既に検証していることそのものだ。著者が自分の変更の内側から構造的に見えない2つの失敗モードへ向け直した。どちらも内側からは正しく見える。
レビュー役の定義にも禁止事項を2つ足しました。著者のプロセスを監査すること。フォーマッターとビルドが既に捕まえるものを再報告すること。どちらも「人間のレビューでやっていたから」という理由だけで入っていました。ゲート自体は残しています。検証の段を削れという一般的な助言よりも、ここで欠陥が減った実測を優先しました。
持ち込めるのは原理で、手順ではない
Anthropicの公式ドキュメントは、この線引きを両側から書いています。ツールの設計についてはWriting effective tools for AI agentsがこう言います（訳は筆者、以下同じ）。
道具は、同じ基盤リソースへのアクセスが与えられたとき、人間がやるのとほぼ同じやり方でエージェントがタスクを分割し解決できるようにすべきだ
一方、指示の書き方についてはPrompting best practicesが逆を言います。
規定的な手順よりも一般的な指示を選べ。「徹底的に考えよ」のようなプロンプトは、手書きの段階的計画よりも良い推論を生むことが多い
原理は持ち込め、手順はなぞるな、と同じ会社が書いていることになります。手元の判断もそこに落ちました。見る先を変えたのと同じ機会に、実装前に必ず全文調査を1回通すという段も落としています。1行の修正にまで要求するには割に合わなかったためで、残したのは思い出したAPIを実物と公式ドキュメントに当てる一段だけです。週次のコードベース走査のほうは、定期的にリファクタの時間を取るという原理だけを持ってきて手順を入れ替えました。検知と修正を分ける、出力は差分ではなくチケットにする、起動は週次にする。
ブログ見つけさせて、直させないPRのレビューで担保しきれずに漏れるものを拾うため、週次でコードベースを走査するだけのサブエージェントを立てています。修正はさせず検知と報告に限り、報告はレビュー側で裏を取る運用を1か月ほど回した記録です。なぜ原理のほうが持ち込めるのかは、説明があるだけで裏づけがありません。人間の書いたものから確率で出力しているので、人間の活動の抽象化が意図しない形で学習されている。筋は通りますが、測った研究には行き当たっていないので経験則として置いておきます。
AI向けに書き直せ、という側の言い分
ここまでは手順をどう組み直すかの話でした。人間向けのものをそのまま当てはめるかどうかという問いは、エージェントに読ませる文書の書き方にも出てきます。そしてこちらには、人間向けに書いたものを渡すこと自体が誤りだという反対の立場があります。llms.txtの提唱ページは、Webページは人間のために作られていて、ナビゲーションや広告に包まれた情報をきれいなテキストに戻すのは難しく不正確だ、と書きます。AGENTS.mdも「README.mdは人間のためのものだ」と始めて、人間の貢献者には関係のない規約を収める場所として自分を位置づけます。
この立場自体は採っています。手元でもAGENTS.mdを単一の情報源にして、ツールごとのファイルはシンボリックリンクで揃えました。一般的なプログラミングの知識は書きません。エージェントが既に知っているからです。
分業として自然に見えます。ただし公式が利点に挙げる分離は、人間の目が届かない場所を作ることと同じものを指しています。そして効いているかどうかは、調べてみると心もとない状態です。
| 調査 | 分かったこと |
|---|---|
| AGENTS.mdの評価 | コンテキストファイルを与えても作業の成功率は上がらず、推論コストは平均20%以上増える |
| フォーマットの影響 | GPT-3.5-turboではコード翻訳タスクで、内容を同じにしたままフォーマットだけ変えると性能が最大40%変動する |
| Ahrefsのログ調査 | 有効なllms.txtを公開している約38,000ドメインのうち、97%が5月に一度もリクエストされていない |
最後のものは内訳も示唆的です。リクエスト元をカテゴリ別に見ると最大は21.7%のSEO監査ツールで、検索用途で取りに来るAI retrieval botsは1.1%でした。ただしAIエージェントやAI学習クローラーなど別のAI系カテゴリもあり、それらを合算すると2割弱になります。GoogleのJohn Muellerも同じ趣旨で、ファイルは何年も存在しているのにどのAIシステムも使っていない、としています。
2つめのほうが厄介です。この研究は大きいモデルほどフォーマットの違いに頑健だとも述べているので、変動幅そのものは古い話になりつつあります。それでも最適なフォーマットがモデルごとに違うなら、AI向けの最適化は特定のモデルへの最適化です。効き目はモデルが変われば薄れ、書いたものは残ります。
ブログ削れと言われたのは、道しるべではなかった「規定的な作り込みを削れ」という助言は、禁止形や思考手順のことを指しています。ヒントやフックやワークフローまで削れと読むと、裁量を渡したのに黙るエージェントが残ります。制約と整備を分けた上で、依存していた挙動を数え直した記録です。検査が効くのは片方向だけ
どちらに書くべきかは、世の中でもまだ決着していません。決着させなくても、片方向だけ確かなことがあります。Anthropicのゴールデンルールです。
そのプロンプトを、タスクの文脈をほとんど持たない同僚に見せて、従ってみるよう頼め。彼らが混乱するなら、Claudeも混乱する
人間の可読性を、AI向け指示の検査手段として使えと言っています。ただしこの手続きが検査できるのは、書いてある内容のほうだけです。
その塞がれた側に、いま起きている問題があります。スキルの参照ファイルには、必ず読ませたいものを見分ける接頭辞を付ける規約があって、読み込みは本体の側に「このファイルを読むこと」と明示的に書いて指示しています。Skill authoring best practicesも、ファイルはオンデマンドで読まれると書いています。
それでも最近の更新以降、この指示はほとんど通らなくなりました。
規約の文面は1文字も変わっていません。人間が読めば「読めと書いてある」としか分かりません。AI向けに書いた指示は、内容を人間が確かめられても、効いているかどうかは読んでも判定できない。実際に呼び出して測るまで分かりませんでした。ゴールデンルールはここに届きません。混乱するかを見る手続きなので、届いているかどうかは同僚が読んでも分かりません。
ブログ規約は、規約について嘘をつくエージェントに読ませる規約が、実際の挙動と食い違ったまま残っていました。参照ファイルを読めと明示的に書いた指示が、その通りには動いていなかった件を起点に、規約そのものを検査した記録です。論点は誰が気づけるかに移る
人間向けとAI向けのどちらが正しいかは決めません。反対側には実装上の根拠があり、こちらの経験則には測定がないからです。決められるのは別の軸で、人間向けに書いた文章は読み手が読めば効いたかどうかが分かり、AI向けに書いた指示は届いたかどうかが文面に出ません。非対称なのは可読性ではなく、効果を検出できるかどうかのほうでした。
レビューという工程そのものをエージェントに置き換えよという主張も出ています。査読前のプレプリントである以前に、置き換えても検出の問題は残ります。置き換えた先が黙って通す側になるだけだからです。
ブログ沈黙は語らない「誰も何も言わない」を問題なしと読む運用が、エージェントを入れたあとで最初に壊れました。沈黙がそのまま通っていたのは、読み手がコストを払っていたからではなく、払ったと信じられる与信が相手に積まれていたからだった、という整理です。検証できない前提が規約に残っている
次に手を付けるのは、AI向けに書いた指示の棚卸しです。どの一行が、届いているかどうかを測らないまま効いていることにされているか。参照ファイルの件で分かったのは、指示が通らなくなっても文面はそのままだということでした。
いちばん怪しいものは既に見えています。一般的なプログラミングの知識は書かない、エージェントは既に知っているから、という規約です。何を知っているかを測ったことは一度もありません。