人間のオフィスにロボットを入れるな

Image: AI generated

一つの問い

あなたのプロジェクトで最も長いファイルを開いてみよう。関数はいくつ入っているか？

AIエージェントにそのファイルの関数を一つ修正させてみよう。エージェントはファイル全体を読む。関数一つのために開いたのに、19個の不要な関数がついてくる。

これが問題の始まりだ。

人間が読むコード、エージェントが作業するコード

これまでコードは人間が読むものだった。変数名を丁寧につけ、コメントを書き、ドキュメントを整えるのはすべて人間の認知負荷を減らすためだった。

エージェント時代には問いが変わる。人間が読みやすいコードとエージェントが作業しやすいコードは同じか？

同じではない。

人間AIエージェント
探索方法ディレクトリツリーを目で追うgrepで検索する
ファイルを開くIDEでスクロールread file – 全体をロード
コンテキスト判断直感 + 経験コンテキストにあるものだけ知っている
不要なコード無視するコンテキスト予算を消費する
2,000行のファイル必要な部分だけ見る全部処理する

人間は2,000行のファイルをスクロールしながら「この部分は触るな」という直感が働く。エージェントにはそんな直感がない。2,000行を読めば1,950行がコンテキスト汚染だ。

研究がこれを確認している。不要な情報が混ざるとAIの性能が30~85%低下する。不要なトークンが空白であっても性能は劣化する。コンテキストが短いほど良いというのは直感ではなく実験結果だ。

人間のオフィスにロボットを入れてはならない。ロボットが働ける工場を作らなければならない。

エージェントに必要な三つのこと

エージェントがコードベースで安定的に作業するには、三つの条件が必要だ。

1. 読めなければならない – ノイズなしで

1ファイルに1コンセプト。ファイル名がそのままコンセプト名。

before: utils.goをread → 関数20個、19個不要
after:  check_one_file_one_func.goをread → 関数1個、まさに必要なもの

filefuncがこの問題を解決する。22個の構造ルールでコードを意味単位に分離する。Honoフレームワーク(star 23k+)で186ファイルを626ファイルに分割した。テスト4,419個、一つも壊れなかった。ファイルは3.4倍に増えたがロジックは一行も変わっていない。

「ファイルが多すぎないか？」 – エージェントはディレクトリを開かない。検索する。ファイルが500個でも1,000個でもgrepを一回打てば終わりだ。必要な5個を取るより、不要な295個を開かないことの方が重要だ。

2. 検証できなければならない – 機械的に

テストのない関数を修正すると何が壊れるか誰にも分からない。エージェントにも分からない。doom loopに陥る。

before: テスト0個、修正すると何が壊れるか不明
after:  527個の関数にテスト、動作変更を即座に検知

tsmaがこの問題を解決する。プロジェクトの全関数をインデックスし、テストの有無を検知し、カバレッジを測定し、未カバーの分岐を行番号でフィードバックする。

フィードバックなしにLLMにテストを書かせると、カバレッジは60~70%で止まる。「line 41, 44, 70 未カバー」と伝えれば100%に到達する。同じモデルだ。違いはフィードバックの解像度だけだ。

527関数プロジェクトでの実験結果：TODO 0まで完走。自律エージェントは40個で「完了しました」と宣言した。ラチェットを適用すれば527個を完走する。

3. 仕様が交差検証可能でなければならない

APIスキーマ、DBスキーマ、セキュリティポリシー、状態遷移が互いに一致するか機械的に確認できなければならない。一つを変えたとき他と食い違うかコンパイル前に分からなければならない。

before: 200エンドポイント、仕様間の整合性を人間が確認
after:  operationId一つで全レイヤーをチェイニング、ドリフトを機械が検知

yongolがこの問題を解決する。10個のSSOT(OpenAPI, DDL, sqlc, SSaC, Rego, Hurlなど)をoperationId一つでチェイニングし、~287個のルールで交差検証する。OpenAPIではuser_idがstringなのにDDLではBIGINT – このようなレイヤー間の矛盾は既存のツールでは捕捉できない。

三つのツールを貫く一つの構造

filefunc, tsma, yongolは独立したツールだが共通の構造がある。

filefunc:  22個の構造ルール → validate → 修正 → 繰り返し
tsma:      カバレッジ測定 → 未カバー分岐フィードバック → 修正 → 繰り返し
yongol:    交差検証 → ドリフト検知 → 修正 → 繰り返し

すべて同じループだ。

LLMが生成する → 決定論的ツールが判定する → 結果をLLMに返す → 繰り返し

Symbolic Feedback Loop。LLMの確率的生成を決定論的ツールが校正する循環構造。AIがAIを検証するのではなく、機械がAIを検証する。

意見を与えればお世辞を言い、事実を与えれば修正する。「コード大丈夫？」と聞けば「はい、良いです」と答える。「line 41: field name mismatch」と伝えれば即座に直す。お世辞の対象がないフィードバック – 数字と位置は感情ではないからだ。

レガシーからagent-operableへ

既存のコードベースを一度に変える必要はない。基礎工事ではなく耐震補強だ。営業中の店を閉めずに建物を補強する。

第1段階 – 読めるようにする

最も長いファイルから分割する。filefunc validateを実行し、違反を0にする。既存のテストがすべて通ること。

第2段階 – 検証できるようにする

tsma nextを繰り返す。テストのない関数にテストを追加し、未カバーの分岐を埋める。エージェントが途中で死んでも進捗は保存される。新しいエージェントがtsma nextを叩けば続きから再開する。

第3段階 – 交差検証する

SSOTを導入しyongol validateをかける。レイヤー間の矛盾を機械が捕捉する。

各段階は独立している。第1段階なしに第2段階だけでもいいし、第2段階なしに第1段階だけでもいい。しかし三つが合わさればエージェントの自律作業範囲が飛躍的に広がる。

オペレーティングシステムを変えること

Agent-operable codebaseは単なるlintやtoolingレベルではない。コードベースのオペレーティングシステムを変えることだ。

human-readableagent-operable
ファイルサイズ人間がスクロール可能な範囲コンセプト一つ
テストあれば良い、なくても直感で全関数に必須
仕様ドキュメント、Wiki、口頭伝達宣言的、交差検証可能、機械が読む
フィードバックPRレビュー（時間単位）verifier実行（秒単位）
完了判断人間が「もういい」機械が「まだ487個残っている」

多くの人が列車を速くしようとしている。より大きなモデル、より賢いエージェント、より良いプロンプト。

列車が速くなるほど線路が重要になる。線路を敷く人はまだほとんどいない。

関連記事

根拠資料

  • Stanford, “Lost in the Middle: How Language Models Use Long Contexts” (2024) – 関連情報がコンテキスト中間に埋もれると30%+性能低下
  • Amazon, “Context Length Alone Hurts LLM Performance” (2025) – 不要なトークンが空白でも13.9~85%性能低下
  • Honoフレームワーク実証 – 186ファイル → 626ファイル分離、テスト4,419個全通過
  • tsma 527関数実証 – PASS 246個(46.7%)、DONE 281個(53.3%)、TODO 0個
  • Ratchet Pattern実験 – 自律エージェント 40/527 (7.6%) vs ラチェットCLI 527/527 (100%)