---
title: "他人の目は、同じ場所しか見なかった"
description: "エージェントのレビューゲートに人間のレビューの形をそのままなぞったところ、著者が自分で検証していることと同じ場所を見ていました。持ち込めるのは原理で手順ではないという整理と、AI向けに書いた指示は効いているかどうかを人間が読んでも判定できないという話です。"
category: "AI"
tags: ["AI Agent","Documentation","Code Review","Claude Code"]
publishedAt: "2026-09-05"
lastmod: "2026-09-05"
---

エージェントのレビューゲートに人間のレビューの形をそのままなぞったところ、著者が既に自分で検証している場所を見ていました。持ち込めるのは原理のほうで、手順ではありません。ただしAI向けに書いた指示には別の問題があって、効いているかどうかを人間が読んでも判定できません。

::card[https://github.com/LabeeHive/standards]

## なぞったら同じ場所を見ていた

Swiftの開発をタスクから完了まで通すワークフローに、通過しないと先へ進めないゲートを置いています。そこに最初に並べたのは、人間のレビューで見ていた項目でした。テストがあるか、参照を読んだか、TODOが残っていないか。

しばらく回して、並べ方の問題が分かりました。並べた項目は、著者が既に自分で検証していることと重なっています。人間のレビューでこれが成立したのは著者とレビュアーが別人だからで、同じ実行の中で役だけ分けても二度読んでいるだけになります。

見る先を変えたときの記録が残っています（訳は筆者）。

> プロセス遵守に向いていた。テストがある、参照を読んだ、TODOが残っていない。それは著者が既に検証していることそのものだ。著者が自分の変更の内側から構造的に見えない2つの失敗モードへ向け直した。どちらも内側からは正しく見える。

![最初に見ていたのは、テストがあるか・参照を読んだか・TODOが残っていないかという項目で、著者が自分で検証できる範囲の内側に収まっていた。いま見ているのは、局所最適化と離れた流儀の流用という2つの失敗モードで、どちらもその範囲の外側にある](/images/posts/human-workflow-not-transcribed/review-gate-reaim.svg)

レビュー役の定義にも禁止事項を2つ足しました。著者のプロセスを監査すること。フォーマッターとビルドが既に捕まえるものを再報告すること。どちらも「人間のレビューでやっていたから」という理由だけで入っていました。ゲート自体は残しています。検証の段を削れという一般的な助言よりも、ここで欠陥が減った実測を優先しました。

## 持ち込めるのは原理で、手順ではない

Anthropicの公式ドキュメントは、この線引きを両側から書いています。ツールの設計については[Writing effective tools for AI agents](https://www.anthropic.com/engineering/writing-tools-for-agents)がこう言います（訳は筆者、以下同じ）。

> 道具は、同じ基盤リソースへのアクセスが与えられたとき、人間がやるのとほぼ同じやり方でエージェントがタスクを分割し解決できるようにすべきだ

一方、指示の書き方については[Prompting best practices](https://platform.claude.com/docs/en/build-with-claude/prompt-engineering/claude-prompting-best-practices)が逆を言います。

> 規定的な手順よりも一般的な指示を選べ。「徹底的に考えよ」のようなプロンプトは、手書きの段階的計画よりも良い推論を生むことが多い

原理は持ち込め、手順はなぞるな、と同じ会社が書いていることになります。手元の判断もそこに落ちました。見る先を変えたのと同じ機会に、実装前に必ず全文調査を1回通すという段も落としています。1行の修正にまで要求するには割に合わなかったためで、残したのは思い出したAPIを実物と公式ドキュメントに当てる一段だけです。週次のコードベース走査のほうは、定期的にリファクタの時間を取るという原理だけを持ってきて手順を入れ替えました。検知と修正を分ける、出力は差分ではなくチケットにする、起動は週次にする。

::card[/posts/weekly-code-grooming-agent]

なぜ原理のほうが持ち込めるのかは、説明があるだけで裏づけがありません。人間の書いたものから確率で出力しているので、人間の活動の抽象化が意図しない形で学習されている、と考えれば筋は通りますが、測った研究には行き当たっていないので経験則として置いておきます。

## AI向けに書き直せ、という側の言い分

ここまでは手順をどう組み直すかの話でした。人間向けのものをそのまま当てはめるかどうかという問いは、エージェントに読ませる文書の書き方にも出てきます。そしてこちらには、人間向けに書いたものを渡すこと自体が誤りだという反対の立場があります。[llms.txt](https://llmstxt.org/)の提唱ページは、Webページは人間のために作られていて、ナビゲーションや広告に包まれた情報をきれいなテキストに戻すのは難しく不正確だ、と書きます。[AGENTS.md](https://agents.md/)も「README.mdは人間のためのものだ」と始めて、人間の貢献者には関係のない規約を収める場所として自分を位置づけます。

この立場自体は採っています。手元でもAGENTS.mdを単一の情報源にして、ツールごとのファイルはシンボリックリンクで揃えました。一般的なプログラミングの知識は書きません。エージェントが既に知っているからです。

分業として自然に見えます。ただし公式が利点に挙げる分離は、人間の目が届かない場所を作ることと同じものを指しています。そして効いているかどうかは、調べてみると心もとない状態です。

| 調査 | 分かったこと |
|---|---|
| [AGENTS.mdの評価](https://arxiv.org/abs/2602.11988) | コンテキストファイルを与えても作業の成功率は上がらず、推論コストは平均20%以上増える |
| [フォーマットの影響](https://arxiv.org/abs/2411.10541) | GPT-3.5-turboではコード翻訳タスクで、内容を同じにしたままフォーマットだけ変えると性能が最大40%変動する |
| [Ahrefsのログ調査](https://ahrefs.com/blog/llmstxt-study/) | 有効なllms.txtを公開している約38,000ドメインのうち、97%が5月に一度もリクエストされていない |

最後のものは内訳も示唆的です。リクエスト元をカテゴリ別に見ると最大は21.7%のSEO監査ツールで、検索用途で取りに来るAI retrieval botsは1.1%でした。ただしAIエージェントやAI学習クローラーなど別のAI系カテゴリもあり、それらを合算すると2割弱になります。GoogleのJohn Muellerも[同じ趣旨](https://www.searchenginejournal.com/google-says-llms-txt-is-purely-speculative-for-now/577576/)で、ファイルは何年も存在しているのにどのAIシステムも使っていない、としています。

2つめのほうが厄介です。この研究は大きいモデルほどフォーマットの違いに頑健だとも述べているので、変動幅そのものは古い話になりつつあります。それでも最適なフォーマットがモデルごとに違うなら、AI向けの最適化は特定のモデルへの最適化です。効き目はモデルが変われば薄れ、書いたものは残ります。

::card[/posts/workflow-depends-on-behavior]

## 検査が効くのは片方向だけ

どちらに書くべきかは、世の中でもまだ決着していません。決着させなくても、片方向だけ確かなことがあります。Anthropicのゴールデンルールです。

> そのプロンプトを、タスクの文脈をほとんど持たない同僚に見せて、従ってみるよう頼め。彼らが混乱するなら、Claudeも混乱する

人間の可読性を、AI向け指示の検査手段として使えと言っています。ただしこの手続きが検査できるのは、書いてある内容のほうだけです。

![人間向けの書き方については、読ませて内容を確かめる検査がそのまま通用する。逆にAI向けに書いた指示は、それが効いているかどうかを人間が読んでも判定できず、検査の経路が途中で塞がれて戻ってこない](/images/posts/human-workflow-not-transcribed/one-way-transfer.svg)

その塞がれた側に、いま起きている問題があります。スキルの参照ファイルには、必ず読ませたいものを見分ける接頭辞を付ける規約があって、読み込みは本体の側に「このファイルを読むこと」と明示的に書いて指示しています。[Skill authoring best practices](https://platform.claude.com/docs/en/agents-and-tools/agent-skills/best-practices)も、ファイルはオンデマンドで読まれると書いています。

それでも最近の更新以降、この指示はほとんど通らなくなりました。

規約の文面は1文字も変わっていません。人間が読めば「読めと書いてある」としか分かりません。AI向けに書いた指示は、内容を人間が確かめられても、効いているかどうかは読んでも判定できません。実際に呼び出して測るまで分かりませんでした。ゴールデンルールはここに届きません。混乱するかを見る手続きなので、届いているかどうかは同僚が読んでも分かりません。

::card[/posts/standards-that-stopped-being-true]

この参照ファイルについては、そのあと読めと書く形をやめて、本文に注入する形へ替えました。

::card[/posts/skill-references-injected-not-read]

## 論点は誰が気づけるかに移る

人間向けとAI向けのどちらが正しいかは決めません。反対側には実装上の根拠があり、こちらの経験則には測定がないからです。決められるのは別の軸で、人間向けに書いた文章は読み手が読めば効いたかどうかが分かり、AI向けに書いた指示は届いたかどうかが文面に出ません。非対称なのは可読性ではなく、効果を検出できるかどうかのほうでした。

レビューという工程そのものをエージェントに置き換えよという[主張](https://arxiv.org/abs/2606.13175)も出ています。査読前のプレプリントである以前に、置き換えても検出の問題は残ります。置き換えた先が黙って通す側になるだけだからです。

::card[/posts/silence-is-not-a-pass]

## 検証できない前提が規約に残っている

次に手を付けるのは、AI向けに書いた指示の棚卸しです。どの一行が、届いているかどうかを測らないまま効いていることにされているか。参照ファイルの件で分かったのは、指示が通らなくなっても文面はそのままだということでした。

いちばん怪しいものは既に見えています。一般的なプログラミングの知識は書かない、エージェントは既に知っているから、という規約です。何を知っているかを測ったことは一度もありません。

棚卸しそのものは、そのあと公式の監査ツールを当てる形で1周しました。

::card[/posts/prompt-audit-on-our-own-skills]