当初公開先： https://www.auklabs.io
あなたは2週間、エージェント型ツールで開発してきました。何かが壊れます。コードを読み、エージェントがあなたに求められていない決定をしたことに気づきます——そしてそれがいつ、なぜ行われたのかも分かりません。変更します。するとまた別の何かが壊れます。さらに別の変更をします。3回目の変更の後には、書いていないコードを読んで、していなかった判断の理解を試みていて、当初やりたかったことの筋が完全に途切れてしまっています。エージェントを使うことで避けるはずだった、まさにこの状態です。
これはバグではありません。埋められていない「ギャップ」です。
エージェント型システムについて私たちが抱える最大級の懸念の1つは、「それが何をしているのか分からない」ことです。私にとってより興味深い問いは、どのような要因が、その意思決定につながるのか——特にタスクが曖昧で、コンテキストが欠けている場合です。
エージェントは正確だ
エージェント型コーディングツールは、あなたが求めたことを実行するうえで驚くほど正確です。エージェントにゴールを与えれば、そのゴールを達成するために必要なすべてのタスクを、許可を求めずに実行できます。これが機能であり、意図です——エージェントは、あなたが欲しいものを完全に指定していると前提にします。そして、どこが不足しているかを見つけた場合、自分が知っていることに基づいて推測（仮定）をします。ですが、まさにその機能こそが、静かに物事を間違った方向へ進める場所でもあるのです。
エージェントが「不注意だから」迷走するのではありません。迷走するのは、「穴埋めをしているから」です。仕様上の穴、指示上の穴、そして「言ったこと」と「本当は意味していたこと」の間の穴。エージェントはそれらの穴を推論で埋め、そのまま次へ進みます。自分が推論した内容を記録しませんし、何が欠けていたかも警告しません。ただ実行するだけです。私たちが「何かがうまくいっていない」ことに気づく頃には、何となぜに答えるのに役立つはずの、状況（コンテキスト）の糸が切れてしまっています。
業界はこれを、構造的な問題として認識し始めています。Thoughtworks などのエンジニアたちはこれを「cognitive debt（認知的負債）」と呼び始めました。AIが生成したコードが、設計上の判断を出力に見えない形で埋め込むことで、共有された理解が侵食され、蓄積していくことです。これは、速く動くことの見えない代償です。
この記事では、別のアプローチについて述べます。意図と実装の間のギャップを、増幅する前に可視化し、誤りを修正できる立場にいるうちに、仮定を明示します。
知らないこと、知らないことを間近で見る
ソフトウェア開発は、根本的には「発見のプロセス」です。人間のエンジニアが複雑なシステムに取り組むとき、彼らはそのシステムのアーキテクチャ、制約、そして書かれていないルールについての深い暗黙知を持ち運びます。どこで立ち止まるべきか、どんな問いを投げるべきか、そしてどんな決定は一人で行うには重大すぎるかを彼らは知っています。
私は、エージェント型ツールが実際に生み出すものと、私が作ろうと意図しているものの間にあるギャップに苛立ってきました——ツールが不正確だからではなく、私がそうだったからです。私が抱く仮定、私が省いた詳細、そして私が与えなかった指示。それらが私にとってコストになるのです。これから述べるのは、私が存在に気づいていなかったギャップが、まさにこうした種類のギャップを見つけるために私が構築している手法によって浮かび上がった物語です。
Test-Driven Design、Spec-Driven Design、そしてパイプライン上の各作業単位を（私が「Slice」と呼ぶ単位として）最小限に実装しようとするプロンプトの組み合わせを使っていたにもかかわらず、これらのSliceのうちの1つの最後に、次のメッセージが返ってきました。
Slice 3の定義で参照されているsystem.mdは設定（config）に存在しません。設定された成果物（artifacts）は system-contract ロールをカバーしています。将来のSliceでsystem.mdを正式な成果物として追加する場合、src/artifacts.tsの ArtifactRole と FOREIGN_RULES を拡張する必要があります。
追跡分析で、注意を払う価値のある何かが明らかになりました。元の設定スキーマは5つのキーで定義されていました。その後、system.md が、今後のすべての作業において何が真であり続けなければならないかを示すためのコア成果物として追加されました。別途作成された標準的な実行プロンプト（canonical execution prompt）も、それについては一切言及していませんでした。つまり、参照ドキュメント system.md は定義されていたのに、コア成果物を説明する設定ファイルである PRD、または標準的な実行プロンプトでは、それが参照されていなかったのです。
3つの文書。1つのギャップ。それを除外するという判断の記録はない。
その欠落は意図的なものではありません。外していたことの根拠が記録されていなかっただけです。単に「ない」だけでした。参照ドキュメントにははっきり書かれています：「エージェントは、守らねばならないことを読み取るために system.md を参照する。」 エージェントは、不完全な仕様に対して正しく実行していたのです——それが、うまくいかなくなるまでは。
私は「知らないことを知らない」状態にありました。しかし、私が実行のために設けたガードレールが、その問題を特定し、何がうまくいかなかったのかを考える助けになりました。実行におけるそのギャップを観察した後、レビューを行うと、エージェントは私がなぜ「知らないことを知らない」のかを説明できました。
これは、ギャップに遭遇したときに実行ループが生成した“そのままの”出力です——クラッシュでもなく、静かな失敗でもなく、何が欠けていてなぜ重要だったのかが構造化された形で説明されています：
## なぜ system.md が raes.config.yaml に入っていないのか
この設定は、実行スライス（2026-04-19、raes-reference.md のセクション11における Gap 1）で設計されました。そのスライスでは、5つのキーが定義されました： `build_intent`、`next_slice`、`durable_decisions`、`execution_guidance`、`validation`。
`system.md` は **当時は含められていません**。参照ドキュメントには、`prd-ux-review.md` が *意図的に* 設定から欠落している（セクション9、明示）と記されています。`system.md` については、そのような明示的な除外はありません。したがって、その欠落は設計判断というより、スキーマが最初に定義された時点からの見落ちに見えます。
この解釈を支持する証拠：
- raes-reference.md のセクション3は、system.md を PRD と decisions.md と並ぶコア・トゥルース成果物として説明している
- raes-reference.md の 67行目：「エージェントは、`system.md` を、守るべきことのために参照する。」
- しかし、標準プロンプト（セクション7、193-260行目）は system.md に一度も言及しておらず、またそれ用の設定キーも含んでいない
- そのため、実行ループには、system.md が提供するはずの制約サーフェスへ向かう明示的な経路が存在しない
ちょうど良いタイミングで止める
そのギャップを浮かび上がらせた手法は RAES（Reusable AI Execution System）と呼ばれます。RAES が何で、何でないのかを明確にしておきたいです。というのも、その名前が、正確ではない前提を誘いやすいからです。
RAES はエージェントのフレームワークではありません。ツール呼び出しをオーケストレーションしたり、自律的な計画ループを管理したりしません。エージェントをより賢くしたり、より能力を高めたりもしません。RAES がやっているのは、それよりも単純で、私としてはより役に立つことです。実行中に人間の判断が必要になるタイミングを構造化し、そのタイミングが記録として残るようにする——それだけです。
中核となる考え方は、AI支援の開発には2種類の失敗モードがあるということです。1つ目は実行失敗——エージェントが間違ったことをする場合です。これは見えます。テストが落ちる、コードが壊れる、問題がすぐに表面化する。2つ目は判断失敗——エージェントが、あなたが意図していたものではない行動を、相手がそうだと思い込んでいる仮定に基づいて行ってしまう場合です。これは、積み重なって増幅するまで見えません。
RAES は、2つ目の失敗モードに対応するために作られています。それを実現するために、3つの仕組みを用います：
1. 構造化された実行ループは、根本的に異なる2種類の作業――実装とレビュー――を分離し、それぞれに異なるルールを適用します。実装ループを通して計画作業を強制すると、質の悪い出力になります。ほとんどのツールはこの違いをしません。
2. 昇格ルールを持つ意思決定記録。実行中に、すべての今後の作業に影響する判断が下されたとき、それは2か所に記録されます。判断の理由はdecisions.mdに入り、その結果生じる制約はsystem.mdに昇格されます――この一連の物語が始まったのは、そのファイルが存在しなかったことがきっかけでした。イメージはこうです：
Decision (2026-04-19):
system.mdを中核の真実アーティファクトとして追加。制約をsystem.mdに昇格: 「今後のすべてのスライスは、ここで定義された制約サーフェスに対して検証しなければならない。」 理由: 実行プロンプトから横断的な制約が黙って排除されるのを防ぐため。
1つのアーティファクトはなぜに答えます。もう1つは何が真であり続けなければならないかに答えます。それらは互いを参照します。今後の作業は、理由を掘り起こさなくても、制約を読み取れます。
3. ギャップの明示的な露出。実行ループが「欠けている」「衝突している」「曖昧である」といった何かに遭遇したとき、それは停止してフラグを立て、推測で通そうとはしません。system.mdで起きたのはまさにそれです。ループは当て推量しませんでした。ギャップに名前を付け、下流への影響を特定し、それを私に返してきたのです。
こう聞きたくなるかもしれません。「じゃあ、きちんと書かれた AGENTS.md や .cursorrules でこれをできないのはなぜ？」
違いは、それらのファイルが静的であることです。エージェントがどう振る舞うべきかは記述しますが、エージェントが何を決めたか、そしてなぜそうしたかは記録しません。それらはルールであって、記録ではありません。decisions.mdはその動的な同等物です。事前ではなく、実行中に更新されます。この区別が重要なのは、system.mdの問題を引き起こしたのが「欠けたルール」ではなく、「明示的には決して行われなかった意思決定の記録の欠如」だったからです。
この規律は、聞こえるよりも構築が難しいものです。私が使ってきたあらゆるエージェント型ツールのデフォルト挙動は、前に進み続けることです。RAESは、「速さで実行するよりも、適切なタイミングで止まることの方が価値が高い」という前提のもとで作られています。
What We Don’t Know We Don’t Know – Yet
system.mdのギャップが最後のものではありません。単に、私がはっきり説明できた最初のものだっただけです。
それが未知の未知（unknown unknowns）の性質です。より慎重になるとか、より徹底することで見つかるわけではありません。それらは「それを見つけるように設計されたシステム」を作ることで見つかります――そして、見つかったときに何かを言えるようにすることです。
RAESはまだ初期段階です。ツールは未完成です。私が今、慎重に組み立てたプロンプトで行っていることを自動化するCLIであるraes-executeは、まだ存在しません。手法が、その手法自身を作るために使われている最中です。これは、うまくいっているサインなのか、あるいは、再帰的な問題に対して異常に高い許容度があるサインなのかもしれません。おそらく両方です。
私が知っているのはこれです。仮定を明示し、意思決定が起きたらその都度記録し、ギャップが増幅する前に表面化させるという規律は、エージェント型ツールでの私の働き方を変えました。もちろん、物事が遅くなるからではありません。意味のある形では遅くなりません。ただし、何を信頼するかが変わるからです。出力の背後にある理由が見えると、より出力を信頼できるようになります。システムが止まって、自分が知らないことを教えてくれるはずだと分かると、よりシステムを信頼できるようになります。
これは、私が比較対象にしたどのツールも最適化している「機能」ではありません。彼らは速度、自治、進捗を感じさせることを最適化しています。RAESは、もっと静かな何かを最適化します。つまり、「作られたものが、あなたの意図した通りに作られたものだ」という確信です。
このギャップがあなたの心に響くなら――もし、「何かがうまくいかなかったこと自体は分かるのに、それを引き起こした仮定がいつ作られたのかは分からない」という、具体的な苛立ちを感じたことがあるなら――ぜひそれについて聞かせてください。リポジトリはgithub.com/aabdullah-bos/raesです。オープンで、MITライセンスで、積極的に開発されています。
この手法が実際にどう使われているかを見るなら、docs/raes-reference.mdから始めてください――それは、この手法自身を作るために使われた文書です。
もしこの領域で何かを作っているのなら、AI支援による開発のための実行規律について考えているなら、あるいは「未知の未知」を自分では気づいていなかったギャップについての話があるなら、連絡してください。より多くの人が「自分が足りないと知らなかったもの」を見つけるほど、手法は良くなっていきます。
未知の未知はまだそこにあります。重要なのは、あなたが見つけられる前に、それらを見つけるシステムを作ることです。
