Skillは並べた。動かなかった。契約で繋いだ。— 65個のSkillから、自走する開発サイクルへ

Skill・MCPを65個並べても、AIエージェントは自走しなかった。
"呼び忘れ"、"順序ミス"、"Skill同士が互いを知らない" — 点と点を繋ぎ、線にするには、
プロンプトの"お願い"ではなく、機械可読な"契約"が必要でした。

【話すこと】
■ Phase 1 - 並べた: 開発サイクル全フェーズへのSkill配置 (企画9 / 設計8 / 実装10 / テスト3 / レビュー5 / リリース4 / UI 10 / 横断16)
■ Phase 2 - 動かなかった: AGENTS.md / CLAUDE.md が"お願い"で終わる理由
■ Phase 3 - 契約で繋いだ:
・約束(文書) — 3層契約 PRD / SPEC / CONTEXT、6層 ai_contract.schema.json
・縛り(コード) — Hook 20+個による PreToolUse / PostToolUse / Stop での決定論的停止
・線(パイプライン) — pipeline-definition.json / state_machine.transitions / DoD 12項目
■ 運用知見: 契約自身も腐る — 見直し期限を契約に書く
■ 明日から始める3ステップ

前回 Claude Code Meetup Japan #4「人間は意図、AIは実装」の運用編です。
"AI駆動開発の概念図"から、"運用で回るハーネス"へ。

#ClaudeCode #AI駆動開発 #AIDD #Skill #MCP #Hook #ContractDriven

Transcript

1. Skill は並べた。 動かなかった。 契約で繋いだ。 65 個のSkill から、自走する開発サイクルへ じゅん @buddypia · CyberAgent · AI オペレーション室
2. @buddypia じゅん @buddypia 所属 CyberAgent AI オペレーション室 AI を使った業務効率化や自動化、開発生産 性の向上など AI 何でも屋 前回登壇 Claude Code Meetup Japan #4 「人間は意図、 AI は実装」 今日はその運用編 前回は AI 駆動開発の " 概念図 " 。 今日は " 運用 " の話をします。 2
3. 今日の 10 分、 3 幕で話します Phase 1 並べた Skill ‧ MCP を 65 個作りました Phase 2 動かなかった それでも自走しなかった Phase 3 契約で繋いだ 約束 + 縛り で線にした 点と点だった開発パイプラインを繋ぎ、開発サイクルという線に組み直した話 3
4. 並べた。 Skill ‧ MCP を 65 個作った。 開発サイクルの全フェーズに、対応する道具を揃えた。 4
5. 開発サイクルの全フェーズに、 Skill を配置 企画/ 発見 9 設計/ 仕様 8 実装 10 テスト 3 レビュー 5 リリース 4 UI/Design 10 横断/ メタ 16 " 企画から実装、レビュー、リリースまで " — AI エージェントがつ開く道具はこれで揃っ たはず。 5
6. 期待していた世界 AI に頼めば、 専門スキルを利用し、企画から実装、テスト、 PR 作成まで開発サイクルの全てを勝手に進んでくれるはず Skill ‧ MCP の道具を揃えれば、 AI は自走する。 — そう信じていました。 6
7. 動かなかった。 Skill ‧ MCP は点で散らばっていた。 点と点の間に、約束がなかった。 7
8. 自走しなかった、 3 つの理由 01 呼び忘れ 「 〇〇スキル って、なんだっけ ? 」 人間だから 65 個あれば、確実に 1 つは忘 れる。 02 順序ミス 仕様書を書く前に実装が走り出す。設 計がコード後に動く場合がある。 順番を守るのは人間の責任だった。 03 Skill 同士が互いを知らない 仕様書を、 AI が認識しないと意味がな い。 " 見る保証 " がなかった。 8
9. AGENTS.md / CLAUDE.md は " お願い " だ った 書いたこと AGENTS.md - 必ず 仕様書を参照すること - DB スキーマは触らないこと - prisma/ は read-only - git commit は git関連スキル 経由のみ - アーキテクチャ違反は禁止 現実 長文の禁止事項は、コンテキストの奥に埋もれる 「絶対」と書いても、たまに破る AI が守るかは、モデルの気分次第 " プロンプトで縛る " には限界がある 書いた約束は、 守らせる仕組み がないと意味がない。 9
10. 気づき : Skill 自身が、すでに " 約束 " を持っ ていた 各 SKILL.md の Phase 0 = 「これがないと私は動かない」 ### Phase 0: CONTEXT.json検証 (Context Validation) > 必須前提: feature-architectが生成した CONTEXT.json が存在しなければなりません。 1. CONTEXT.json存在確認: docs/features/<機能ID>/CONTEXT.json 存在有無確認 ├── 存在 → Phase 1へ進行 └── 未存在 → エラー: "CONTEXT.jsonがありません。 feature-architectを先に実行してください。" この Phase 0 こそ、最初の " 契約 " の芽 でした。 10
11. 契約で繋いだ。 Phase 0 の芽を、システム全体に広げる。 " 約束 " を文書に。 " 縛り " をコードに。 11
12. 契約 = 約束 + 縛り + 線 約束 ( 文書 ) 3 層契約 — PRD/SPEC/CONTEXT 6 層契約 — ai_contract.schema.json ADR — PADR-007 人間とAIが交わす、機械可読な約束書 縛り ( コード ) Hook 20+ 個 PreToolUse / PostToolUse / Stop 違反は deny() で即停止 約束違反を機械的に止める仕組み 線 ( パイプライン ) pipeline-definition.json state_machine.transitions DoD 12 項目 + harness-loop Skillとgateを順序で繋ぐ宣言文 12
13. 設計判断として残した : PADR-007 docs/architecture/adr/PADR-007-ai-contract-driven-delivery.md AI Contract-Driven Delivery " 既存の API 契約だけでは、 AI 機能の長期運用に必要な品質属性を保証できない。 AI 機能を " 賢い内部実装 " ではなく " 契約で囲われたプロダクト能力 " として扱う必要がある。 " 問題だったこと モデル /Prompt 変更の影響が追えない 認可‧ PII の扱いが不安定 ツール呼び出しが文書化されない 幻覚率‧拒否率が観測できない 採択した解 6 層の契約を機能ごとに定義 約束‧契約 を機械検証 CI で違反は merge ブロック Tier 制で過剰を防ぐ 13
14. 約束① : 1 機能 = 3 つの契約書 PRD.md 人間の意図 Problem / Why / User Stories / Acceptance Criteria / DoD (§7) human → AI SPEC.json 機械可読契約 FR + API 契約 + UI Flow + approval_gate → 約束‧契約を機械検証 AI machine CONTEXT .json 実行時状態 + 完了契約 current_state / progress / completion_contract.verdict AI → human completion_contract.verdict: "passed" = AI が最後に結ぶ " お約束の手形 " 26 機能 × 3 文書 = 78 通の契約書が、リポジトリに署名済み 14
15. 約束② : AI 機能を 6 層 で縛る L6 Operations Feature Flag / Canary / Tracing / Runbook 運用契約 L5 Evaluation オフライン eval / オンライン KPI / regression_gate 評価契約 L4 Safety 認可 / PII redaction / 秘密情報 / ユーザー確認 安全契約 L3 ★ Execution model_policy (provider/model/temperature/timeout) prompt_policy (prompt_version/system_prompt_path) / tool_policy (allowed/forbidden) 実行契約 L2 Interface HTTP API / イベント / エラー / 互換性 API契約 L1 Product ⽬的 / 成功条件 / ⾮⽬標 / Persona プロダクト契約 AJV 2020 validate CI で違反は merge ブロック 例 : execution.tool_policy = allowed / forbidden tools + side_eÙect_class 15
16. 縛り : Hook 20+ 個 が違反を即停止 SESSION START SESSION END SessionStart session-start auto-checkpoint UserPromptSubmit keyword-detector PreToolUse (Edit/Write) ★ 8 Hooks qa-write-guard feature-change feature-boundary design-guard import-arch svg-locale adr-compliance PreToolUse (Bash) ★ 3 Hooks merge-guard destructive-git commit-guard PreToolUse (Skill) 3 Hooks pipeline-guard quality-gate-pr dod-complete PostToolUse 6 Hooks edit-error-recovery web-format docs-consistency esp-consistency test-coupling Stop 5 Hooks stop-handler feature-sync analyze-guard feature-drift deliverables-fresh ハイライト Hook ( 代表 3 つ ) feature-boundary-guard ── CONTEXT .json 無きコード → deny + /feature-pilot 誘導 commit-guard ── 直接 git commit → deny + /create-pr 誘導 (.tmp/create-pr-active 連動 ) import-architecture-guard ── Feature-First 違反 import → deny feature-drift-guard ── Stop 時にコード - ⽂書ドリフトを検知 → セッション block Hook は " モデルの解釈 " に依存しない。決定論的に 違反を止める。 16
17. 縫い目 : Hook が " 次の Skill 名 " を返す ① USER ACTION Edit src/features/new_feature/ index.ts ② HOOK FIRES (PreToolUse) feature-boundary-guard 機能 new_feature の docs/features/ 対応 ディレクトリ → NOT FOUND ③ deny() with message [FEATURE BOUNDARY GUARD ― DENY] 機能 "new_feature" は docs/features/ に未登録です。 措置: 1. /feature-pilot を 使用してこの機能の文書 を先に生成してください。 2. その後コードを作成できます。 次に呼ぶ Skill 名 を返す = 縫い⽬ (stitch) ④ CLAUDE READS deny → AUTO-ROUTES Claude が deny メッセージから /feature-pilot を読み取り⾃動実⾏ ⑤ /feature-pilot ORCHESTRATES 単⼀進⼊点 → 全パイプライン⾃⾛ Step 1: feature-architect PRD + CONTEXT 生成 Step 2: feature-spec-generator SPEC.json Step 3: contract-codegen Zod + 型 Step 4: readiness-gate Go/No-Go Step 5: implement (turbo-mode) 並列実装 Step 6: quality-gate (max 5 retry) make q.check Step 7: DONE ✓ verdict: passed 17
18. 線の本体 : パイプラインの状態遷移 architect PRD + CONTEXT ⽣成 spec SPEC.json ⽣成 contract_codegen Zod + 型 + MSW ⽣成 ui_approval ⚐ ⼈間の承認 readiness_gate Go/No-Go 判定 implement turbo-mode 並列 contract_test Zod 検証 wiring export/ ルート quality_gate make q.check dod_veri fication DoD 12 項⽬検証 deploy_gate ⚐ ⼈間の承認 DONE completion_contract: passed DoD 未達 → revert_to: implement 凡例 ⾃動連鎖ステージ gate ステージ ( 検証 or 承認待ち ) 契約連動ステージ ⚐ ⼈間の承認必須 compensation: revert_to ( 失敗時の戻し先 ) Tier 別 ステップ数 ▸ Tier S: 9 ステップ ( 最⼩機能 ) ▸ Tier M: 14 ステップ ( 上記 ) ▸ Tier L: 15 ステップ (+ discovery_full, priority_calc) ▸ Tier XL: 15 ステップ ( ⼤規模機能 ) 18
19. 完了の証 : DoD 12 項目 を機械が観測 MACHINE 観測 (9) AI 観測 (3) VERDICT (1) FT-01 全 FR の DoD 通過 progress 100 FT-02 make q.check Critical 全通過 exit 0 FT-04 Feature-First 依存関係準拠 check-arch FT-05 変更ファイルにテスト追加 test-exists FT-06 TypeScript strict エラーなし npm build FT-10 CONTEXT .json state = Done fs read FT-11 契約テスト全通過 test:contract FT-12 Zod ↔ SPEC JSON Schema ⼀致 codegen check FT-03 SPEC §0 ↔ 実装⼀致 AI が SPEC §0 vs 実装を⽐較 FT-07 i18n ハードコーディングなし AI が JSX ⽂字列リテラルをスキャン FT-08 ⽇本語 JSDoc ( 公開関数 ) AI が export 関数の JSDoc 存在を確認 passed = AI が結ぶ「お約束の⼿形」 completion_contract.verdict passed | failed .pass_rate 100 = 12 項⽬すべて通過 .last_verified_at 2026-05-19T19:00... harness-loop (Make file) Phase 1: 3 回⾃動修正 lint -- fix + prettier --write Phase 2: fail-fast tsc + check-arch + test (1 発勝負 ) 19
20. 運用してわかった : 契約自身も腐る ① WRITE 契約を書く PRD/SPEC/CONTEXT ② USE パイプライン実⾏ Hook + Skill が動く ③ ROT 契約が腐る drift / 古さ / 不整合 ④ HEAL ⾃動検知 + 修復 drift-guard + harness-gc 契約⾃⾝に ⾒直し期限を書く feature-drift-guard トリガー : Stop event src/features/ ↔ docs/features/ マッチング、 CONTEXT .json 不整合検知 Critical → セッション block esp-consistency-guard トリガー : PostToolUse (Write/Edit) SKILL.md ↔ MANIFEST .json ⼀貫性 同⼀警告 60 秒内 3 回でループ防⽌ 違反 → additionalContext で警告注⼊ doc_contract.review_interval_days 場所 : 各 SKILL.md frontmatter 90 ⽇ : 35 個 / 30 ⽇ : 8 個 / 7 ⽇ : 1 個 期限超過 → skill-health-check が検出 契約の⾒直しを、契約⾃⾝で約束 " 契約の見直し期限 " を、契約自身に書いておく。 ハーネスは、作って終わりではなく、育て続ける もの。 20
21. 明日から、 3 ステップで " 契約 " を始める 1. Skill の呼び出し順を 1 枚の YAML に書く → .claude/pipelines/your-pipeline.yaml で stages を宣言。 順序が " 暗黙の口伝 " から " 機械可読 " に。 2. " 呼ばれて当然 " の 1 ステップを PreToolUse hook に昇格 → AGENTS.md の " 禁止事項 " を 1 つだけ hook.mjs に書き換える。 deny メッセージに " 次に呼ぶ Skill 名 " を含める。 3. 機能契約 のうち 1 つだけ 契約として運用開始 → CONTEXT .json で十分。 1 機能だけ completion_contract を書く。 全部一度に やろうとしない。 21
22. Skill は 点。 線にするのは、 約束と縛り。 " 契約で繋いだ開発サイクルは、もう自走している。" @buddypia じゅん · CyberAgent · AI オペレーション室