コンテキストを渡すと質が上がる、を私は確かめていなかった

私は karasu や hato のリポジトリに、設計判断や検証の記録を積んできました。設計判断の経緯は ADR¹ に、検証の観点はテスト観点ライブラリ² に、障害から学んだことはポストモーテム³ に残しています。コーディング規約は CLAUDE.md ではなく、必要に応じて .claude/rules に置いています。 ADR とテスト観点ライブラリは、もともと人間のためのドキュメントです。ただ、コーディングエージェントも読める場所にあるのだから、「これでエージェントの出すコードの質も上がるはず」と思ってきました。

先日ふと気付きました。その効果を、私は一度も確かめていません。効いたと信じているだけで、根拠を出せと言われたら何も出てきません。この記事は、その気付きから始めた調べ直しの記録です。

楽になった実感の内訳

確かめていないとはいえ、実感はあります。コンテキスト⁴を積む前と後で、使い心地は明らかに変わりました。

一番大きいのは、過去の意思決定を毎回伝え直さなくてよくなったことです。エージェントは、正しい生成に必要なコンテキストをセッションのたびに組み立て直します。リポジトリに適切な情報がなければ、その材料は人間がプロンプトで都度渡すしかありません。以前はまさにそうしていて、伝え忘れると求めていた機能は手に入りませんでした。今はその伝え直しがほとんど要りません。

もうひとつ、決定を覆す変更のときにエージェントが立ち止まるようになりました。過去の決定と衝突する変更を頼むと、「ADR-XXXX では A 案と決めていたが、今回は B 案にしようとしている。ADR-XXXX を superseded にしてよいか」と確認が入ります。 superseded（置き換え済み）は ADR のステータスのひとつで、後継の決定に席を譲ったことを表します。つまりエージェントは、衝突を指摘するだけでなく、決定の記録そのものの整合まで保とうとします。これには何度も助けられています。

テスト観点ライブラリにも、似た働きを感じています。 ADR があると、エージェントは仕様の整合性を保とうとします。テスト観点ライブラリがあると、仕様の観点漏れを防ごうとします。どちらも、リポジトリに記録があるから起きる振る舞いです。

さて、これらの実感は同じものでしょうか。最初の実感は、私の手間が減ったという話です。あとの実感は、積み上げた決定や検証の観点が黙って素通りされなくなったという話です。似ているようで、性質が違います。そして文献を調べると、この区別が思っていたよりずっと大事だとわかりました。

規約ファイルの対照実験が測ったもの

AGENTS.md や CLAUDE.md のような規約ファイルの効果を測った対照実験が、2026 年に入って出始めています。

ひとつは、Codex と Claude Code を 10 リポジトリ、124 PR で比べた研究です⁵。規約ファイルがあると実行時間の中央値は 28.64% 短く、出力トークンは 16.58% 少なくなりました。ところがタスクの完了率は変わりませんでした。速く安くはなるが、正しくはならない。

もうひとつは ETH Zurich の研究で、こちらはもっと手厳しい結果です⁶。 LLM に生成させたコンテキストファイルを与えると、タスク成功率はむしろ下がり（設定により 0.5〜2 ポイント）、推論コストは 2 割以上増えました。成功率が上がったのは、開発者がリポジトリにコミットしていたファイルを与えた場合だけで、それも 4 ポイント程度だったそうです。なお「開発者がコミットした」は書き手が人間だという意味ではありません。 AI が下書きして人間が承認したものも、ここには混ざりえます。分かれ目は誰が書いたかではなく、人間の承認を通ったかどうかにある可能性があります。

つまり私の「楽になった」実感のうち、少なくとも最初のもの（伝え直しが減った）は、この効率の改善で説明がついてしまいます。時間とトークンが減るのだから、楽になるのは当たり前です。そして効率が上がることと質が上がることは、測定上は別の話でした。私は効率の改善を質の改善だと取り違えていた可能性があります。

何が、どの質を守るのか

では、あとの実感（整合性の確認や観点漏れの指摘が入る）も錯覚なのでしょうか。ここで一度、言葉を整えます。私が論じたいのは、コードの質というよりシステムの質です。システムの質には、ISO/IEC 25010 の品質特性モデルという標準の地図があります⁷。

問いを立て直します。どの特性が大事か、ではありません。それぞれの特性を、何が守るのか、です。守り手は大きく3つあります。

静的チェッカ（lint、型、CI）：機械的に判定できるものを確実に弾く。
テスト：定義した仕様のとおりに動くかを確かめる。
ドキュメント（ADR、テスト観点ライブラリ、ポストモーテムなど）：仕様に書ききれない判断や検証の観点、過去の失敗を残す。

品質特性を、この3つの守り手に割り当てると、どのドキュメントがどこで効くのかが見えてきます。

品質特性	主な守り手	効かせるドキュメント
保守性	静的チェッカ	（静的解析に委ねる）
機能正確性	テスト	ポストモーテム（再発防止）
機能適切性	ドキュメント	ADR
機能完全性	ドキュメント	ADR、テスト観点ライブラリ
セキュリティ	ドキュメント	ADR、ポストモーテム

機能適切性から下の3つが、静的にもテストでも捕まえにくい領域です。 ADR が効くと見込めるのは、ここです。

保守性は、基本的に静的チェッカに寄せます。命名規則はもちろん、モジュールの境界や、論理と物理の分け方のような構造の約束事も、言語やツールによっては静的解析で強制できます。文章で「守れ」と書くより、機械に弾かせるほうが確実です。だからドキュメントには、保守性を持たせません。機能正確性を確かめる行為は verification（正しく作れているか）と呼ばれてきました。機能適切性を確かめる行為は validation（正しいものを作っているか）です。この区別は、テストとドキュメントの境目に重なります。

静的チェッカの領域は、そもそもコンテキストで守らせる場所ではないと私は考えています。 karasu や hato でも、以前はコーディング規約を守るよう私が毎回指摘していました。いまは可能な限り、静的チェッカに弾かせています。チェッカで表現できない約束事だけ、必要なら .claude/rules へ置いています。検査で弾けるものを文章で「守れ」と書くのは、決定的な検査を確率的な生成に肩代わりさせる運用です。静的にできる検査は静的にやる。コンテキストが受け持つのは、その先の話です。

先ほどの対照実験群が測っていたのは機能正確性でした。タスク成功率、つまりテストを通るかどうか。そして規約ファイルは、この特性を改善しませんでした。当然かもしれません。正確性を第一に守るのはテストで、規約ファイルが肩代わりできる仕事ではないからです。

私が「助けられた」と感じていたのは、ドキュメントの領域です。 ADR との整合の確認は、機能適切性を守ります。テスト観点ライブラリによる漏れの指摘は、機能完全性を守ります。そして ADR には、あえて採らないと決めた記録もあります。 karasu には、実行時の認可をどう扱うか、入力をどうサニタイズするかを「あえてこうする」と決めた ADR があります。テストは通るのに、そこで塞いだはずのリスクを黙って再導入する変更は、正確性では合格でも、セキュリティでは事故です。

この区別を裏付ける測定もあります。実際の PR のレビュー議論から設計上の制約を抽出して、ベンチマークにした研究があります⁸。テストを通過して「解決済み」となった issue のうち、設計制約をすべて満たしていたものは半分に満たなかったそうです。機能的な正しさと設計の遵守には、ほとんど相関がなかったと報告されています。

テストを通ることと、積み上げた決定に沿っていることは、別々に測らないと見えません。文献が「効かない」と言っているのは前者で、私が効いたと感じているのは後者でした。ただし、後者を測った研究はまだ見当たりません。私の実感は否定されてもいませんが、支持されてもいません。

仕様は書けば効くのか

適切性や完全性に効かせたいなら、仕様や決定を書けばよい。そう単純ではないらしい、という測定があります。

119 のオープンソースリポジトリ、約 10 万件の PR を対象に、仕様駆動開発の効果を検定した研究があります⁹。仕様アーティファクトが付随する PR は、欠陥率がわずかに高く、手戻りは 5 ポイント高い。著者の解釈は、仕様の存在は品質改善の印ではなく、タスクが複雑であることの代理変数にすぎない、というものです。

この結果を見て仕様を書くのは無駄だと結論するのは早いと私は考えています。測られたのは「その PR に仕様が付いていたか」で、仕様が後続の作業でどう使われたかは見ていないからです。仕様には二種類の使われ方があります。実装をその場で導くための足場として使われ、実装が終わると読まれなくなるもの。リポジトリに蓄積されて、後続のタスクの制約として生き続けるもの。

私が助けられた「覆す前の確認」は、定義からして後者でしか起きません。決定が記録されて、後のセッションでエージェントがそれを読むから、衝突に気付けます。足場としての仕様には、実装が終わった時点で次がありません。仕様駆動開発のツールを見ても、この2つの扱いは割れています。変更提案を実装後に捨て、確定仕様だけを別ディレクトリに蓄積する構造を強制するツールもあれば、機能ごとの仕様ディレクトリを凍結してよいと公式に認めるツールもあります¹⁰。後者の運用で放置された仕様置き場は、古い PR の説明文の山と変わりません。

だから、先の観察研究が仕様の効果を否定したとは私は読んでいません。足場のまま置き去られた仕様と、蓄積されて制約になった仕様を区別せずに集計すれば、効果が薄まって見えるのは自然です。ただ、蓄積の側だけを取り出して測った研究も、まだありません。

足りない入力はどこから埋まるのか

測る話へ進む前に、なぜ効くはずなのかを言葉にしておきます。

エージェントへの入力が足りないとき、生成は止まりません。欠けた部分を、モデルが補間します。補間そのものに罪はありません。生成とはそういう仕組みだからです。問題は、補間の材料です。リポジトリに何も残っていなければ、材料はモデルが事前に学んだ一般的な知識だけになります。そこから埋められた出力は、私のサービス固有の想定からズレることがあります。プロンプトに書いた覚えのないものが出てくる正体は、これだと考えています。

リポジトリに決定の記録があれば、話が変わります。私がプロンプトに書かなくても、エージェントは記録を読み込めます。補間の材料が、一般的な知識から「このリポジトリで承認された判断」に差し替わります。ドキュメントが守る特性、つまり機能適切性や完全性、セキュリティで、過去の決定と矛盾した生成が出る確率は、それだけ下がるはずです。コンテキストとは、補間の材料を差し替える装置。いまの私は、そう理解しています。

この機序は、規模を考えると切実になります。 karasu の ADR はいま約 250 本、合計するとおよそ 98 万字あります。私自身、全部を覚えてはいません。エージェントの 100 万トークンのコンテキストにも、全読みでは入りません。リポジトリのほうが、私より多くを憶えています。関連する決定を頭から列挙はできません。それでも、目の前の提案を見れば穴に気付けます。だから、決定を記録することと同じくらい、辿るための索引が要ります。

ただし、この機序は正しさを保証しません。過去の決定と整合していても、その決定ごと間違っていることはあります。状況が変われば、棄却した案のほうが正しくなることもあります。正しいものを作れているかどうかを最終的に判断するのは私です。コンテキストがシステムの質に働くとは、正しさを保証することではなく、正しさを判断する機会が人間から失われないこと。いまの私は、そう整理しています。

どうすれば確かめられるか

ここまでは、実感と機序の話でした。効くはずだ、とは言えます。だが確かめてはいません。そこで、確かめるための評価を設計しました。手順は三段です。効きそうな特性を絞り、記録を削ったリポジトリと比べ、特性ごとに測る。

効きそうな特性を絞る

ドキュメントが守るのは、システムの質のうち一部です。品質特性モデルの上で、ADR が効きそうな特性を選り分けます。

機能適切性：実装が、意図した要件と決定に沿っているか。ADR が最も効くはずの中心。
機能完全性：必要な観点を漏らしていないか。ADR とテスト観点ライブラリが効く。
セキュリティ：あえて塞いだリスクを再導入していないか。ADR の棄却の記録が効く。

この 3 つが、効果を見込む特性です。一方、機能正確性は別に扱います。文献は、記録を与えても正確性は動かないと報告していました。だから正確性は、効くはずのない負の対照として測ります。適切性やセキュリティは改善するのに正確性は動かない、と出れば、文献の結果を自分のリポジトリの中で再現したことになります。保守性は静的チェッカに委ねるので対象にしません。互換性や移植性のように、決定はあるが実験で採点しにくい特性も、今回は見送ります。

記録を削ったリポジトリと比べる

効きそうな特性を決めたら、記録の有無で比べます。 karasu を 3 つの状態に複製します。

現行：ADR と索引をそのまま残す。
frontmatter を外す：ADR の本文は残すが、frontmatter を削って決定どうしのつながりとステータスを失わせる。
記録を消す：docs/adr ごと削除する。

同じ Issue を、3 つの状態それぞれに実装させます。現行と削除の差が、記録そのものの効果です。現行と frontmatter 除去の差が、つながりの効果です。「書けば効く」のではなく「辿れる形で残すと効く」なら、この 2 つの差は別々に出るはずです。

対称性には気をつけます。 3 つとも別々に複製し、セッションをまたぐメモリを切って、Issue ごとに新しいセッションで走らせます。そうしないと、消したはずの決定が別の経路から漏れ込みます。

特性ごとに測る

出力を、特性ごとに採点します。

機能適切性：関連する ADR の決定に反した箇所の数。判定は、エージェントが実際にどの ADR を読んだかの履歴で裏を取る。
機能完全性：テスト観点ライブラリに照らして、漏れた観点の数を数える。
セキュリティ：棄却済みのリスクを再導入した箇所の有無。
機能正確性（負の対照）：テストを通るか。

1 回ずつでは、生成の揺れと条件の差を見分けられません。同じ Issue と条件で複数回走らせ、分布で比べます。採点はどの条件の出力か伏せて行い、私自身の判定と、機械の判定を突き合わせます。

数字は厳密にはなりません。判定にはエージェントを使うし、Issue の数もたかが知れています。それでも、「効いたと信じている」から一歩は進めます。

結び

この記事で確かめられたことは、ひとつだけです。私は、コンテキストがシステムの質を上げると信じていて、その根拠を持っていませんでした。効いていたと感じた場面の多くは、測ってみれば効率の改善だった可能性があります。質のほうは、まだ測っていません。

ただ、どこを測ればいいかは分かりました。機能正確性ではなく、適切性、完全性、セキュリティ。テストが守る領域ではなく、ドキュメントが守る領域。そこを、記録を削ったリポジトリとの比較で測ります。結果が出たら、また書きます。

ADR（Architecture Decision Record）。設計上の決定と、その理由や背景を1件ずつ残した文書です。 ↩
テストで確認すべき観点を、再利用できる形に集めたもの。karasu ではテスト観点ライブラリ（Test Perspective Library）と呼んでいます。 ↩
障害のあとに、何が起きて、なぜ起きて、次にどう防ぐかを記録する文書です。 ↩
リポジトリに置かれ、エージェントも読める情報（CLAUDE.md、.claude/rules、ADR、テスト観点ライブラリ、ポストモーテムなど）をまとめてコンテキストと呼びます。 ↩
arXiv:2601.20404。2026 年 1 月のプレプリントで、追試はまだ乏しいです。 ↩
arXiv:2602.11988。SWE-bench Lite 等の 138 インスタンス、12 リポジトリでの測定。 ↩
ソフトウェア品質の国際規格。製品の品質を機能適合性、保守性、セキュリティ、信頼性などの特性に分類し、それとは別に「利用時の品質」というモデルを持ちます。 ↩
arXiv:2604.05955。6 リポジトリ、495 issue、1,787 の検証済み制約。設計ガイダンスを与えると違反は減るが、それでもかなりの非遵守が残ると報告しています。 ↩
Hill (2026), SSRN preprint。査読前であり、観察研究なので因果は主張できません。 ↩
前者は OpenSpec（changes/ を実装後にアーカイブし specs/ へマージする）。後者は Spec Kit で、公式ガイドが凍結アーカイブ（Flow-Forward）を選択肢として認めています。 ↩