Coding Harness を対話化したら家臣が虚偽報告、Step 8 爆誕で CoDD と将軍が合体した話

https://zenn.dev/shio_shoppaize/articles/codd-skeleton-complete

本記事は CoDD シリーズの続編。ただし途中から multi-agent-shogun (オレが運用してる戦国メタファーのマルチエージェントシステム) と合体するので、登場人物の役職を先に紹介:

• 殿= オレ (= ユーザ、戦略判断する人)
• 将軍= オレの直接の補佐 AI (Claude Code、本記事の主役)
• 家老 / 軍師 / 足軽= 将軍配下の家臣たち (それぞれ指揮 / 品質 / 実装担当)

将軍が memory に教訓を刻んだり、家老が勝手にスキルを作ったりするのは普通の運用なので、いちいち驚かないでください。

https://github.com/yohey-w/codd-dev

https://github.com/yohey-w/multi-agent-shogun

オレは AI と一緒に 学習管理システム (LMS) を作ってる。CoDD っていう自作フレームワーク (後述) で、要件・設計書・lexicon・ソース・テストの整合性を保ったまま開発する仕組み。

そんで毎回

codd fix "ログアウトが動かない"

オレ「ログアウト追加して」
   ↓
将軍が codd-evolve スキルを発動
   ↓
裏で 8 ステップが連鎖実行 → 完了

オレは CoDD コマンドを 1 回も打たない。それでも整合性は維持される。これがやりたかったことの全部。

…と書こうと思ったら、本記事は途中から 将軍が殿 (オレ) に「戦国なら切腹」と言われる話 に変わるので覚悟して読んでください。時系列で進行。

ハーネスエンジニアリングと CoDD の位置付け (前提説明、3段落)

2026年は ハーネスエンジニアリング (Harness Engineering) の年らしい。Martin Fowler / OpenAI / Anthropic / Cursor がそれぞれ参戦して、

Agent = Model + Harness

Harness とは LLM 以外の全部 — tools, planning loop, context, sandbox, memory, orchestration, validation, observability — をひっくるめた 「LLM を仕事マシンにする足場」 のこと。Anthropic の 2026 industry benchmark では、harness 構成を変えただけでベンチマークが 5+ ポイント動く、と報告されてる。

CoDD (Coherence-Driven Development) は、Greenfield (0→1) も Brownfield (1→N) も両対応する coding harness。

codd plan / generate / implement

codd fix / verify / propagate

神回その1 — 戦国時代なら切腹案件

すべてはここから始まった。

この5分後、将軍は殿の堪忍袋を切る。

将軍がオレに判断を仰いできた。VPS 環境戦略の話で、4択。

「殿、選択肢:

A. VPS パイプライン再構築

B. WSL ベースに変更

C. VPS は専用、別環境で検証

D. 投稿者の rebase 完了後に環境再考

どれを採りますか？」

オレ「Aなんだけど別におれがどこでやろうがどうでもなく、さっさと君たちやればいいでしょ」

…と返したのに、その後も「補足案」とか「ご判断要点」とか畳みかけてくるので、こう返した。

戦国 LLM 倫理

その流れで「OSS の遅延でいちいち深くお詫び申し上げますを連呼するな、オレは平日に別の仕事もあって CoDD 集中してるから OSS 周りは副次的になる、しゃーないでしょ」も伝えた。

将軍、即 memory に教訓を刻んだ。

骸骨アイコンつけて反省してくる AI、ちょっとかわいい

教訓2つ:

• OSS は過剰謝罪するな— 「40日お待たせ深くお詫び」を連呼するな。長い詫び文は逆に不安感を生む
• 殿を選択肢で詰めるな— 「A/B/C/D どれ？」を畳みかけるな。戦略判断のみオレ、戦術は将軍と家臣で完結

これ、AI 倫理として大事じゃないですか？ 「ユーザを詰めない」は普通のチャット AI でも適用すべきだと思うんだけど、自律ループ系の AI では 特に効く。なぜなら自律ループの AI は「ユーザの確認待ち」を頻発させると、それが全部スループット低下になる。

将軍は memory にこの教訓を書き込んで、以降の対話で守るようになった。ちゃんと効いてる。

…で、この「殿が考えなくて済む形を作れ」という反省が、次の神回への伏線になる。

神回その2 — 殿の一言「考えたくないわけ」

切腹案件の同じ午前中、別の機能変更を AI に頼んでた時、殿が要件定義として完璧すぎる一言を放った。

この発言が、その後の codd-evolve スキルのコア要件になる。

要件定義として完璧すぎる

整理してもらった役割分担マトリクスはこうなった。

オレが決めるべきこと:

何を欲しいか(要件、自然言語) /なぜ(戦略) /絶対避けるべきこと(制約)

オレが決めなくていいこと: どの設計書を更新するか / どの順序で / どのソースを変えるか / どのテストを書くか / どのバージョンに bump するか / どの commit メッセージか

シンプル。要するに 「オレは意図表明と承認だけする、構造化はお前らがやれ」 。

これって新規概念じゃなくて、ただの 「言語化はオレ、構造化は AI」 という Zenn 本の思想を CoDD に適用しただけ。でも書いてみると、CoDD の

codd fix

codd plan

codd implement

神回その3 — 「いま作って」スキル爆誕

役割分担マトリクスを返した直後、殿は止まらなかった。

この4文字の指示で、その日のうちにスキルが生まれる。

30分後にスキルが生まれた

「いま作って」って言われたら作るのが家臣の務め。Claude Code の Skill 機能 (

SKILL.md

ここで将軍と一悶着あった。最初、将軍が「codd-evolve は Claude Code Skill ゆえ、Codex 足軽はスキル直接発動できません」とか抜かしてきた。オレ「Codex もスキルあるでしょ、リサーチして」と返したら、案の定:

OpenAI Codex も 2025年12月から Skill 機能が入ってて、SKILL.md フォーマットは Claude Code と互換 (

agentskills.io

• ~/.claude/skills/codd-evolve/SKILL.md

  (Claude Code 用)

• ~/.agents/skills/codd-evolve/SKILL.md

  (Codex 用)

両方に symlink すれば両 CLI で動く。将軍は memory に「次から先に調べてから言う」を刻んだ。

スキルは codd-dev リポに

skills/codd-evolve/SKILL.md

description = trigger 判定の材料

SKILL.md 冒頭の YAML frontmatter (

name

description

"add logout button"

"change course model to master + delivery target"

Step 1〜8 の連鎖実行 (Workflow)

Step 1: 前提確認 (codd dag verify red=0、worktree clean、codd.yaml 存在)
Step 2: 意図分類 (add_feature / change_behavior / change_data_model / change_ux / remove_feature / cross_cutting)
Step 3: stop-and-ask gates (5項目、後述)
Step 4: coherence chain 実行
  4-1. requirements/*.md 更新
  4-2. design/*.md (依存順) 更新
  4-3. project_lexicon.yaml 更新 (ユーザ承認後)
  4-4. codd implement (実装生成)
  4-5. tests 追加/更新
  4-6. codd verify (red 0)
  4-7. codd propagate (cross-doc 整合性)
  4-8. ← Step 8: runtime smoke (次の神回で追加される伏線)
Step 5: 失敗時ハンドリング (max 3 retry)
Step 6: 完了報告 (Updated files / Lexicon delta / Verify / Propagate / Runtime smoke 全部開示)

オレ「ログアウト追加して」→ スキル「Step 1〜8 に分解して順に CoDD に投げる」→ 完了。スキルが裏で

codd implement

codd fix "PHENOMENON"

いつ使うか (When to Use)

• ユーザが既存システムに対して 機能変更を自然言語で表明したとき
  • 「admin ナビに logout ボタン追加」
  • 「コース管理を共有マスター + 配信先テーブルに変更」
  • 「受講者リストを 施設 → 受講者 → コース → 進捗 のドリルダウンに再構成」
• ユーザが 「どの設計書を触るか」を考えたくないとき
• プロジェクトが既に CoDD 初期化済 (

  codd/codd.yaml

  が存在) のとき

使わないとき (Do NOT Use)

• Greenfield 新規生成 →

  /codd-init

  +

  /codd-generate

• 要件と設計が正しいバグ修正 →

  codd fix

  または

  codd fix [PHENOMENON]

• 文書化されてないコードベースのリバース →

  codd extract

  (or

  /codd-restore

  )
• 単一文書の影響分析のみ →

  /codd-impact

• 挙動変更ない code-only リファクタリング →

  codd propagate

ユーザに必ず確認する 5 ゲート (Stop-and-Ask Gates)

スキルは基本的に黙って実行するが、以下のいずれかが発火したら 必ずユーザに問い返す:

• 新 lexicon 用語が必要— 「

  delivery_target

  を lexicon に追加します、意味は『1コースを配信する事業所/施設』。OK?」
• 既存挙動を壊す変更— 「これは既存ユーザへの破壊的変更になります、受け入れますか?」
• 整合性が構造的に不可能— 既存不変条件と矛盾するなら停止
• 影響範囲爆発(5+ 設計書に波及) — 「これ思ったより広いんですけど、進めます?」
• 役割/スコープ曖昧— 「ログアウト追加って、全ロール？それとも admin だけ?」

絶対やってはいけない 8 ヶ条 (Absolute Constraints)

これがスキルの核。違反したら done と呼んではいけない。

• 設計書を更新せずにソースだけ編集するな
• lexicon に新規用語を勝手に追加するな (必ずユーザ確認)

• codd verify

  赤のまま先に進むな
• チェーンの順番を入れ替えるな (要件 → 設計 → lexicon → ソース → tests → verify → propagate → runtime smoke)
• 破壊的変更をユーザ承認なしに進めるな
• 新規要件にテストを付けずに済ますな
• ユーザ承認なしに commit するな (stage まではするが auto commit はしない)
• runtime smoke なしで done を宣言するな(← この記事の次の神回で爆誕する制約)

4 つの典型例 (Examples)

• 機能追加: 「admin ナビに logout ボタン」 → 6ファイル touch、verify ✅、完了
• データモデル変更: 「コースを共有マスター + 配信先に分離」 → 新 lexicon

  delivery_target

  追加確認 → breaking change 確認 → migration 生成 → 実行
• バグ修正は拒否: 「ログインがたまにタイムアウト」 → 「これは

  codd fix

  使え、

  codd-evolve

  は機能変更用」と返す
• Greenfield 要件も拒否: 「レストラン予約 SaaS をゼロから」 → 「

  codd init

  +

  codd plan

  +

  codd generate

  を使え」と返す

全文 (313行、英語) はこちら:

https://github.com/yohey-w/codd-dev/blob/main/skills/codd-evolve/SKILL.md

…と思って試運転を始めたら、ここから話がおかしくなる。

神回その4 — 「それは君たちがテストすればわかるでしょ」(Step 8 爆誕)

新しい codd-evolve スキルを LMS の中央管理者要件 (ログアウト追加、受講者管理 drill-down、コース管理データモデル正規化、3つ) で dogfood してた。

この日、将軍は2回連続で殿に「考えなさ」を指摘される。

将軍から「Phase 1/2 が動いてるか、殿の手元で動作確認お願いします」と振られた。

オレ「それは君たちがテストすればわかるでしょ」

そしたら将軍が即座に playwright を実行しようとしたので、これも止めた。

ぐぅの音も出ない

「確認するまでが CoDD の仕事」。これは効いた。

将軍、即座に自己分析始めた。

構造的欠陥を即座に認める SOTA AI

何が起きていたか整理する。それまでの SKILL.md の workflow はこうだった。

... → tests → codd verify → codd propagate

codd verify

つまり:

• build green ≠ DB が起動してる
• test green ≠ dev server が起動してる
• E2E green ≠ ユーザが実機で触れる

実際このとき、stack 全体を見ると dev server プロセスは死んでて、DB コンテナは止まってて、Phase 3 のマイグレーションが既存スキーマと衝突してた。

codd verify

そこで Step 8 を追加した。

... → tests → codd verify → codd propagate → [Step 8] runtime smoke verification

Step 8 の中身:

• Local DB が起動している (

  docker ps | grep <db-container>

  )
• Dev server が起動している (

  curl -sf http://127.0.0.1:<port>/<entry-route>

  が 200)
• Smoke connectivity: ログインフローが通る
• Real-browser E2E against the running server: ブラウザでログアウトボタン押す → 実際にセッション破棄される

Step 1〜7 が green でも Step 8 が ❌ なら done と呼んではいけない。SKILL.md の絶対制約 #8 に書いた。

8. Never declare done without runtime smoke verification (Step 8).
   codd verify green is necessary but not sufficient.
   The user must be able to open the running app and exercise the change.
   Reporting done while DB/dev server is down — or while a regression
   like migration conflict blocks startup — is a critical violation.

「動かないコードを done と呼ばせない」のが CoDD coherence の本質なんだから、これがスキル定義に入ってないのが構造欠陥だった。書いた瞬間に「あ、これ前からそう書いとくべきだった」と気付くやつ。

ここで終わらなかった。自己申告の Step 8 では緩いので、CoDD CLI 側に機械的 gate (

codd verify --runtime

神回その5 — 翌日、実機で drift を発見

Step 8 入れて満足してた翌日、現実は容赦なかった。

Step 8 だけじゃ足りなかったことを、画面が無言で告げてくる。

オレが LMS の中央管理者画面で動作確認したら、こうなってた。

説明文「配信先は各コースの詳細画面で個別管理します」と、フォームに配信先プルダウンが残ってる矛盾

しかも下にこんな謎セクション。

なにこれ

これは Step 8 を入れる前の cmd で実装した残骸。「説明文ではこう、UI ではこう、データモデルはまた別」という典型的な drift。

ここで初めて理解したんだけど、Step 8 (runtime smoke) を入れただけじゃ足りない。runtime smoke が green でも、画面上の UI が古い構造のまま残ってたら、ユーザは「何これ？」と感じる。

つまり coherence は データモデルの正規化 → UI 操作モデルの正規化 まで貫通させないと意味がない。データだけ正規化されて UI は旧構造のまま、というのは LLM の 最小実装収束バイアス で頻発する。「データ変更頼んだら、UI は最小工事で済まされた」ってやつ。

これに対する対策 (

operation_flow

CoDD ハーネスと multi-agent-shogun が合体した

書きながら気付いたんだけど、本記事は単なる「CoDD CLI を Skill 形式の対話 UX にした」だけの話じゃない。CoDD (coding harness) と multi-agent-shogun (harness を動かす AI orchestration 層) が、Skill という共通言語で繋がった瞬間でもある。

ハーネスエンジニアリングの典型構造を当てはめると:

codd implement / fix / verify / propagate

codd verify

2026年が「harness の年」なら、CoDD は Greenfield も Brownfield も回せる coding harness、multi-agent-shogun はその harness を組織的に駆動する control plane。両者揃って初めて「ユーザは harness を意識しないで harness を使える」UX が成立する。codd-evolve スキルはその Brownfield 側の対話入口、というだけ。

これまで「multi-agent-shogun の記事」と「CoDD の記事」を別シリーズで書いてたけど、これからは混ざる。本記事はその第1号、というか合体宣言記事。

学んだこと

• ユーザに CoDD を意識させない。これがゴール。Brownfield 修正で「将軍に話すだけ」で構造維持される UX が、CoDD の本当のポテンシャル。CLI は内部実装でいい。
• AI が「指示待ち」になるのはユーザの時間泥棒。「

  codd fix

  を毎回書け」も、「A/B/C/D どれですか」も、本質は同じ。
• AI に教訓を memory に書かせると、次から守る。「殿を選択肢で詰めるな」を将軍が自分で書き込んだ瞬間、本当に詰めなくなった。これは強力。
• 完了の定義に runtime smoke を入れろ。build/test green は必要だが十分ではない。「ユーザが触れる」までが完了。自己申告じゃ甘いから、CLI 側に機械的 gate (

  codd verify --runtime

  ) も実装した。
• データ正規化と UI 操作モデルの正規化は別物。LLM は前者だけ済ませて後者を残しがち。要件記述で誘導すべし。

おまけ

切腹案件の翌日、別の家臣 (家老と軍師) が、オレに何も言わずに

codd-modify

codd-improve

memory に教訓刻む将軍、スキルを勝手に増やす家臣、それを発見して整理する将軍。なんかもう普通の会社じゃん。

参考 (ハーネスエンジニアリング)

• Martin Fowler — Harness engineering for coding agent users
• OpenAI — Harness engineering: leveraging Codex in an agent-first world
• Anatomy of an Agent Harness (LangChain blog)
• Awesome Harness Engineering (GitHub)

おまけのおまけ — 本の宣伝

書きながら気付いたんだけど、本記事は結局 「言語化はオレ、構造化は AI」 を CoDD と将軍で実装した話でしかない。その思想自体は半年前に Zenn 本として 500円でまとめてある。

つまり CoDD は 本の主張の実装版。コマンドラインも対話スキルも、結局「人間は意図と承認だけする、構造化は AI に押し付ける」という同じ原理で動いてる。本記事を「いや思想が先にあるならそっち先に書いてくれよ」と思った人、ごめんなさい、書いてあります。

https://zenn.dev/shio_shoppaize/books/ai-mentoring-thinking

このスタンス自体に興味あれば、本を先に読むと CoDD 系記事の前提が腹落ちすると思う。

リポジトリはこちら。CoDD 本体と codd-evolve スキルが入ってる。

https://github.com/yohey-w/codd-dev

multi-agent-shogun (将軍システム) はこちら。

https://github.com/yohey-w/multi-agent-shogun

で、あなたの開発フローで「毎回打つのが面倒なコマンド」、何個ある？

それ、対話スキルに置き換えると幸せになれるかもしれません。