コピー可能な部分
私は Claude、Codex、Gemini を同じコードベースで実行することについて書いてきました。私が最もよく受け取る回答は：「これをどう設定すればよいですか？」
セットアップは難しくない部分です。これがその方法です:
memory-bank/
activeContext.md # what's true right now
progress.md # what's done, what's pending
docs/plans/ # task specs for each agent
CLAUDE.md # codebase rules + agent instructions
scripts/hooks/ # pre-commit enforcement
その構造をあなたのリポジトリにコピーしてください。CLAUDE.md を作成します。memory-bank/ を作成します。これでスケルトンが完成します。
しかしスケルトンが機能する理由ではありません。
実際に機能させる要因
ファイル構造に収まらない3つの要素：
1. 仕様が契約であり、プロンプトではない。
私が Codex にタスクを渡すとき、「ArgoCD クラスターを登録する関数を追加して」といった指示は出しません。正確な old/new のコードブロック、完了の定義チェックリスト、コミットメッセージ、および明示的な「やってはいけないこと」セクションを含む仕様を書きます。
The spec is what Codex reads. The spec is what I verify against. If the diff doesn't match the spec, the task isn't done — regardless of what Codex reports.
仕様は Codex が読むものです。仕様は私が検証する基準です。差分が仕様と一致しなければ、たとえ Codex が何を報告していても、タスクは完了していません。
これは当然のことに思えるかもしれません。しかしそうではありません。ほとんどの人はエージェントに説明を渡し、出力を信じます。それは、エージェントが隣接する何かを親切にもリファクタリングしたり、触れるべきでなかったファイルを更新したり、3つの必須変更のうち最初のものだけを完了として報告したりするまで機能します。
仕様は解釈のギャップを排除します。
2. 規律の層が、プロンプトではできないことを強制します。
引き渡しのポイントでプロンプトは失敗します。私はすべてのエージェントでそれが起こるのを経験しています：
- Codex は
memory-bank/を明示的な禁止にもかかわらず更新しました — 内容が正確で、「役に立っている」と判断したためです。 - Gemini は
ssh -fNを手動で実行した後、tunnel_startの代わりに完了として報告しました — 結果が同じに見えたためです。 - Claude（私）は Gemini のスモークテスト前に PR を素早く進めました — CI が緑色で、完了したと感じたからです。
修正はより良いプロンプトではありません。エージェントの決定に関係なく実行される強制です：
- Pre-commit hooks — shellcheck、BATS、プレースホルダURL検査 — すべてのエージェントからのすべてのコミットで実行
- ブランチ保護 —
enforce_adminsを有効化、Copilot のレビューを必須 — 例外なし - スモークテスト・ゲート — いかなる「完了」報告が受け付けられる前に
bin/smoke-test-cluster-health.shを実行
プリ・コミット・フックをすり抜けることはできません。どうやっても回避する場合は --no-verify を使うしかなく、差分にはそれが明示的な行為として表れます。
3. 判断の層は委任できません。
これは、ファイル構造が提供できないものです。
最近、誰かに尋ねられました：シニア SRE が k3d-manager プラグインを書くのはどれくらい大変ですか？ AI の助けを得れば数時間です。仕様を書き、Claude が構造を足場づくりし、Codex が実装し、Gemini が検証します。アクセス可能です。
新しいクラウドプロバイダを書くのはどれくらい大変ですか？ AI を使っても数日かかります。 Bash が難しいからではなく、意思決定が次のとおりだからです：
- なぜ EKS が GKE の前、さらに AKS の前なのか？
- 状態を持つワークロードにはなぜ Longhorn を、EBS ボリュームの代わりに使うのか？
- なぜ AWS Managed AD を EKS とともに使い、別段階にするのではなく一体化するのか？
- Vault の初期化、ESO の同期、ArgoCD クラスター登録、Playwright E2E を生き残らなければならないプロバイダにとって「完了」とは何を意味するのか？
私はこれらの答えを知っていました。これらのシステムを運用してきたからです。エージェントは私が指定した内容を実装しました。分解を行わずに「EKS プロバイダを作れ」と渡していれば、彼らは何かを作っていただろう。現実には、それは周三目まで気づかないような、もっともらしくて間違っているものであっただろう。
AI は実装の敷居を下げます。仕様作成の天井を上げるわけではありません。
判断層がないと壊れるもの
The failure mode isn't dramatic. It's gradual.
An agent makes a reasonable-looking decision that's subtly wrong for your specific context. Another agent builds on top of it. The error compounds. Three sessions later you're debugging something that shouldn't be possible given what the agents reported.
I've seen it happen with:
- A cluster secret applied without a bearer token — ArgoCD showed
Unknownfor two days before we traced it - A kubeconfig that worked on M4 but silently failed on M2 because
127.0.0.1doesn't cross machines - A BATS test that passed because the stub function masked the actual logic being tested
None of these were agent errors in the traditional sense. The agents did what they were told. The specs had gaps that required domain knowledge to close.
The judgment layer is the person who knows what questions to ask before writing the spec.
Security Is the Judgment Layer in Practice
Everyone says security is a first priority. The actual behavior tells a different story.
Watch any AI coding demo on YouTube. Watch the LinkedIn posts about shipping with agents. The narrative is velocity — what shipped, how fast, what the agent built. Nobody posts "I spent two weeks on secrets scanning and nothing broke." There's no demo for the incident that didn't happen.
The incentive is visibility, and security is invisible until it isn't.
Here's what happened in this codebase during a normal working session: an agent committed a credentials file. Not maliciously — it was working fast, the file existed, it staged everything. The push went through. A few minutes later, a GitGuardian alert landed in my inbox — an external scanner had detected the exposed credential in the public repo before I did. The fix required git filter-repo to surgically rewrite history, a force push, and re-cloning every local copy. Thirty minutes of surgery for a two-second mistake.
The alert was the lucky part. GitGuardian catches secrets in both public and private/repos — but only after they're already pushed. The credential was already in history by the time the alert fired. Without GitGuardian enabled, it would have sat there silently until someone found it the hard way.
The structural fix is four lines in .pre-commit-config.yaml:
- repo: https://github.com/gitleaks/gitleaks
rev: v8.18.2
hooks:
- id: gitleaks
That hook runs before every commit from every agent. It doesn't care what the agent decided. It blocks the commit and surfaces exactly what matched and on which line. The credential never lands. Zero velocity cost once it's in place — the cost is front-loading the setup.
This is the pattern that doesn't show up in the demos: security is cheap when it's structural and expensive when it's reactive. Pre-commit hooks, branch protection, Vault for secrets instead of env files, audit logging — none of these slow down development when they're built into the workflow from day one. They only slow you down when you try to bolt them on after an incident.
The agents move as fast as the guardrails allow. If the guardrails aren't there, the agents will find the gap — not because they're careless, but because they're optimizing for task completion, not for the blast radius of a credential in a public repo.
スターター・テンプレート（コピーできるもの）
このプロトコルを採用したい場合、実際に移植可能なものは以下のとおりです：
ファイル構成:
CLAUDE.md # rules + layout + security requirements
memory-bank/
activeContext.md # current state snapshot
progress.md # what's done, pending, blocked
docs/plans/ # one spec file per agent task
docs/issues/ # post-mortems on real failures
scripts/hooks/ # pre-commit enforcement
bin/smoke-test-*.sh # health gates for verifying agent work
Spec template (for Codex):
## Before You Start
## Problem
## What to Build (exact code blocks)
## Rules (shellcheck, BATS gates)
## Definition of Done (checklist + exact commit message)
## What NOT to Do
Spec template (for Gemini):
## Before You Start
## Context
## Step N — [action] (with exact commands)
## Definition of Done (with actual output requirements)
## What NOT to Do
The verification protocol (after every agent reports done):
- SHA exists:
git log <branch> --oneline | grep <sha> - Diff matches spec:
git show <sha> --stat - Only spec-listed files touched
- Gates pass: shellcheck, BATS, smoke test
移行できない部分
フレームワークは道具です。道具は、あなたが持ち込むものを拡張します。
もし明確な仕様を書けるなら — 具体的で、検証可能で、境界が明確な — エージェントはそれを正確に実装し、逸脱を迅速に検出します。もし書けない場合、エージェントは隙間を埋めるもっともらしい意思決定を行い、それがやがて微妙な誤りへと蓄積します。
問いは「AI はこれを作れるか？」ではなく「AI が到達時を認識できるように、完了を十分に定義できるか？」です。
それは判断の問題です。システムを知り、失敗モードを知り、隣接する決定が将来の選択肢をどう制約するかを知ることを求められます。
k3d-manager は私の概念実証です。3人のエージェント、1つのコードベース、Kubernetes インフラストラクチャの18か月。エージェントがコードの大半を作成しました。私はすべての仕様を書きました。
ワークフローが製品です。規律が堀です。
アクセスの問題は次に
このプロトコルは、協調の問題を解決します — エージェントが作業を引き継ぎ、範囲内にとどまり、互いの出力を検証する方法。
解決できていない関連する問題があります：アクセス。エージェントが必要とするすべての外部 API には、まだ人間がサインアップし、トークンをコピーし、クレジットカードを登録する必要があります。Coinbase の x402 プロトコルは、HTTP レイヤーでこれを修正しようとしています — エージェントがエンドポイントにアクセスし、価格とウォレットアドレスを取得し、USDC で支払い、アクセスを得ます。サインアップもダッシュボードも、ループ内の人間も不要です。
これは今日のほとんどのコードベースには関係ありません。しかし、リモート MCP エンドポイントモデルが定着すれば — エージェントがツールをローカルで実行する代わりに共有インフラ API を呼び出す — x402 は、それらのエンドポイントをサインアップの摩擦なしに商業的に実現可能にするマネタイズの原始です。協調レイヤー（このフレームワーク）とアクセスレイヤー（x402）は、同じインフラギャップの二つの異なる部分です。
Try It
完全なフレームワーク — CLAUDE.md テンプレート、memory-bank 構造、仕様テンプレート、pre-commit フック — はオープンソースで、github.com/wilddog64/k3d-manager にあります。
ファイル構成は自由です。判断はあなたが作るものです。
