facet 詳解 (rules / skills / agents / hooks / output-contracts / knowledge)

この連載が記述する時点

本連載は執筆時点のハーネス実環境 (設定ファイルの内容、実行記録、ファイル数) を素材にした記録です。ハーネス本体は公開後も改修が続いているため、引用したファイル内容や個数、手順は現在の実体と異なる場合があります。本連載の主眼は個々の値ではなく設計の考え方 (5 関心分離、検証ゲート、成長規律) にあります。

本章は、ここまで整理してきた 5 facet + hooks + knowledge の各層を、実コード引用付きで辞書的に並べます。

辞書的な並びを取る理由は、本連載を「使い方ガイド」だけでなく自前ハーネスの参考実装カタログとして読めるようにするためです。各 facet の責務・境界・現実例 (実コード) を 1 箇所に集めることで、「自分の用途で似たものが必要なら、ここを引用元にできる」状態を目指します。

以下は agents/ rules/ skills/ hooks/ output-contracts/ knowledge/ それぞれの責務を、代表例に絞って辞書的に並べます (CLAUDE.md settings.json .gitignore docs/ を除く)。usage-driven 追加でこれらの facet は今後も増減するため、ここでの列挙は完全な一覧ではなく、各 facet がどんな種類のパターンを持つかを示す抜粋です。

5.1. rules/ — Policy の代表例

rules/*.md は Policy (規範、how) を集めた facet です。全ファイルが paths: なし = 常時ロード設定で、subagent 経路でも届きます。当初は少数のファイルで bootstrap しましたが、usage-driven 追加 (同じ指示を手で 2 回出して初めて facet 化、本連載 07 章で扱う成長規律) を経て今の形になりました。以下は、異なる種類の規律パターンを示す代表例です。

rules/verification.md

役割: 主張は証跡で裏付け、状態変更操作は実行後の実状態を再確認

配信: paths なし常時ロード (developer / auditor に必須)

冒頭抜粋:

# Policy: verification (検証)

> paths なし = 常時ロード。developer / auditor (subagent) が依存するため
> path-scoped 禁止。

## 主張は証跡で裏付ける
- テスト・grep・コマンドの**出力を証跡として示す**。「直した」「動く」を出力なしで
  断定しない。
- コマンド出力は**全体を確認**してから結論する。`head` / `tail` の打ち切りで
  「該当なし」と誤断定しない。
- **状態変更操作 (削除 / 移動 / 作成 / 上書き / commit / push) は、まず実行結果
  (exit code + 出力) を確認し、破壊的なものは操作後の実状態も独立に再確認してから
  「完了」と報告する** (`ls` / `git status` / 再 Read 等)。

autodev / smi-auto-dev の検証契約 section も同ファイルに含まれており、autodev フローでの spec 凍結 / developer 証跡記録 / auditor 再導出照合の 3 層が規範として書かれています。

rules/fact-check.md

役割: 発言前に一次ソース裏取り、MCP 第一選択

配信: 常時ロード

冒頭抜粋:

# Policy: fact-check (情報の正確性)

> paths なし = 常時ロード。**主に main agent が情報を提示する前**に、外部知識・
> 記憶ベースの主張を一次ソースで裏取りする規範。作業結果・コードの証跡は
> verification.md が正本 (本ファイルは重複させない)。

## 発言前に裏取りする
- 外部知識・記憶ベースの技術主張は「まず検証、それから発言」。裏取りできないなら
  **断定形を避け**「未確認」と明記する。
- **断定形の主張が最も危険** — hedge 語 (「たぶん」「のはず」) がない分「未確認」
  マーカーが付かず誤りが事実として通る。コードの挙動・ファイル/関数の存在・行番号・
  件数・帰属を語る前に Read / Grep / 実コマンド (ls / find) で**開いてから**断定する。

特に「断定形の主張が最も危険」「一次ソースの null-result を memory で埋めない」の 2 つは、本連載執筆中も常に意識する規範です (例: 第 3 章で nrslib/takt 公式 docs の URL を出典として明記したのは本規範由来)。

rules/interaction.md

役割: AskUserQuestion 強制、平文質問禁止、one question at a time

配信: 常時ロード

冒頭抜粋:

# Policy: interaction (人間との対話)

## AskUserQuestion を使う (平文質問禁止)
- 設計判断・方針確認・選択肢提示は、本文中の**平文質問でなく AskUserQuestion** で行う。
- **禁止パターン** (例示であり網羅ではない): 「〜でいいですか? / どうしますか? /
  ご判断ください / 教えてください / 採用しますか? / よろしいですか?」型の確認・
  依頼・暗黙選択肢型の平文。
- 推奨案があれば**第一選択肢**にし、ラベル末尾に「(推奨)」を付ける。

本 Policy の enforcement は hooks/check-plain-question.sh が担います (詳細は本ページの「hooks/」section)。

rules/git.md

役割: Conventional Commits / 明示トリガー語要件 / worktree 規律

配信: 常時ロード (developer / auditor 必須)

冒頭抜粋:

# Policy: git

> paths なし = 常時ロード。developer / auditor (subagent) が commit / diff を扱うため
> path-scoped 禁止。

## コミット
- **Conventional Commits** (`feat:` / `fix:` / `chore:` / `docs:` 等 + scope)。
  本文は「なぜ」を簡潔に。
- commit message / PR title / code / コード内コメントなど**第三者可視テキスト全般**に
  **個人名を入れない**。
- commit / push 実行は人間の**明示トリガー語** (`commit` / `コミット` / `push` /
  `プッシュ` / `マージ` / `merge` / `反映` 等の動詞) が**直近 user turn に存在する時のみ**。

## ブランチ と ## worktree (autodev developer の隔離) の section が後ろにあり、autodev フローの worktree 設計 (baseRef=head / task branch / handoff dir 越境取得) の規律が書かれています。本 Policy の enforcement は hooks/check-git-commit-gate.sh が PreToolUse / Bash で担います。詳細は第 6 章で扱います。

rules/adversarial-review.md

役割: main agent が人間に提示する直前の plan / 実装サマリを devil-advocate subagent で事前 critique する、反復付きのゲート

配信: 常時ロード (main agent 専用、subagent 自身では自己再帰禁止)

冒頭抜粋:

# Policy: adversarial-review (敵対的レビュー)

> paths なし = 常時ロード。**main agent 専用**。subagent (architect /
> plan-reviewer / auditor / developer / devil-advocate 自身) では適用しない
> (自己再帰禁止)。

## いつ devil-advocate を spawn するか
- **plan / 設計案を人間に提示する直前** (3 行以上の方針説明 / 複数選択肢比較 /
  トレードオフ明示)
- **実装結果サマリーを提示する直前**で複数ファイル跨ぎ / 新規ファイル作成 /
  設計判断 / 既存衝突可能性のいずれかを含む場合

## critique の統合 (iteration protocol)
- **critique → 修正 → 再critique → 提示**の反復形。Critical / Major への修正を
  行った場合は再critique必須。再critiqueは各指摘の**解消 / 残存 / 新規**3値判定
  + 根拠1行で行う。
- 終了条件: 残存 Critical/Major と新規 Critical がゼロ / 最大 3 反復 / 停滞、
  のいずれか。

devil-advocate agent そのものの責務定義は本章「5.3. agents/」で扱います。本 Policy はいつ・どう呼び出すかを規律化する側で、autodev フロー内の plan-reviewer / auditor (= subagent 連鎖の中で自動発火する内蔵 critique) と二重発火を避けるため、autodev 連鎖内では本 Policy を適用しない設計にしています。

他の rules/ ファイル (概要)

上記のほかにも、目的ごとに細分化された Policy が並んでいます。例えば:

実装着手前の一次ソース確認 (implementation.md): コードを書く前に、採用するライブラリ/フレームワークの API を context7 MCP 等で確認する
コード書き込み前のシンボル接地 (search-before-coding.md): 既存 API / 関数を grep で実在確認してから呼ぶ
応答の文体・締めくくり (output-style.md): filler 句禁止、編集完了時の 3 軸サマリ
spec の構造化規律 (spec-discipline.md): EARS notation、in-scope/out-of-scope の明示
session 跨ぎの引き継ぎ規律 (handoff-discipline.md): context reset 時に残す必須項目

fact-check.md (発言前) / implementation.md (採用前) / search-before-coding.md (コード書き込み前) / verification.md (実行後) は時系列軸の分割になっているのが特徴です。同じ「裏取り」を時点で分けたことで、1 facet あたりの責務が単純化されています。

5.2. skills/ — Instruction の代表例

skills/*/SKILL.md は Instruction (手順) を集めた facet です。以下は、手順の性質が異なる代表例を選んでいます: 自律開発フロー全体を駆動する autodev、人間との対話手順に特化した spec-design、自分自身の肥大化を防ぐ自己言及的な harness-prune、本体を軽く保ち詳細は別ファイルに逃がす japanese-tech-writing、破壊的副作用を持つため自動起動を禁じている pr-review です。

skills/autodev/

起動: /autodev <spec パス>

役割: 仕様から実装まで subagent 連鎖でオーケストレーション

中核 phase の抜粋:

## ⓪' 起動前 assert + resume 判定
- spec パス引数を realpath で絶対化 → `~/.claude/repos/<repo>/...` から `<repo>`
  抽出 → `.repo_root` Read/trim → repo_root 取得

## ① architect spawn (read-only, fresh)
spawn prompt に spec.md + per-repo 知識を絶対パス注入

## ①' plan-reviewer spawn (read-only, fresh)
spec ⇔ plan 照合 → review.md。`grep '^VERDICT:'` で分岐

## ② 人間承認 (PASS した plan のみ到達)
AskUserQuestion で 3 択 (承認 / 修正指定 / 中断)

## ③ developer spawn (worktree 隔離, baseRef=head)
story.md を単一入力 → 依存 install → 実装 → pass 条件 → done.md → task branch commit

## ④ auditor spawn (read-only, fresh = --bare)
done.md 証跡 ⇔ spec 原本再導出 + code ⇔ spec + doc 更新漏れ → review.md

## ⑤ VERDICT 分岐 (fail-closed)
`grep '^VERDICT:'` のみ Read → PASS: 人間レビュー・マージ / FAIL: ③ 再 spawn

詳しくは第 6 章 (06. autodev フローの実走)で実走実例を walkthrough します。理解ゲート (G1/G2/G3) を上乗せした学習用の派生形として smi-auto-dev もあり、品質ゲートは完全保持したまま人間が読める状態で merge へ進みたい場合に使います。

skills/spec-design/

起動: /spec-design <feature 概要>

役割: 人間 + AI 協働で spec.md を設計、pass 条件を共同確定、承認時に SHA 凍結

冒頭抜粋:

---
name: spec-design
description: 人間 + AI 協働で仕様を設計する。Phase 0 適応的詰問 → spec.md +
             pass 条件を共同執筆し承認時に凍結する。
---
`/spec-design <feature 概要>` で起動。

## Phase 0: 適応的詰問
1. **explicit AC 判定**: 人間の発話に受入基準・判定条件が含まれるか
   - YES → spec 直行 (軽微タスクの摩擦回避)
   - NO → one question at a time の interview
2. 一度に複数論点を並べない

autodev がオーケストレーションの手順型 Instruction であるのに対し、spec-design は「人間との対話手順」を規律化した Instruction です。同じ facet でも中身の性質はかなり異なります。

skills/harness-prune/

起動: /harness-prune

役割: 月次の棚卸し (逆 ratchet の出口ガード)

冒頭抜粋:

---
name: harness-prune
description: 逆 ratchet の出口ガード。30 日参照ゼロ / サイズ超過 / orphan hook /
             参照切れを検出し反転承認 (残す理由を問う) で削除する。
---

## 検出 4 項目
1. **30 日参照ゼロの facet**: rules / agents / skills / knowledge / output-contracts で、
   他ファイル・git 履歴から 30 日参照されていないもの
2. **サイズ上限超過**: CLAUDE.md >100 / policy >30 / persona >40 (gating >60) /
   skill >80 (autodev >100)
3. **orphan hook**: 対応する facet ファイルが無い hook
4. **参照切れ**: rules / skills / agents 内の `~/.claude/<path>` で実在しないもの

## 反転承認 (非対称性の核)
「消していいか?」ではなく「**消す候補リスト + 各々を残す理由**」を AskUserQuestion で
問う (残す方に挙証責任を負わせる)。

詳しくは第 7 章 (07. 成長規律と逆 ratchet)で扱います。このskill自身もサイズ上限と検出項目を固定しており、「棚卸しをする道具が自ら肥大化しない」設計になっています。

skills/japanese-tech-writing/

役割: 日本語技術文書 (書籍原稿 / 章 / 記事 / 解説文) を書く・推敲・リライトするときの文章規範

起動: 自動起動 (description trigger に「日本語で技術文書を書く / 執筆 / 推敲 / リライト / 直す / 整える」が含まれる)

配信: model-invocable

構成:

0. 最上位の原則 (AI っぽさの三層構造: 文体 / 情報設計 / 思考の不在)
1-10. 詳細規範 → regulations.md を on-demand Read
11. 自己点検
12. 日本語作文古典 (木下『理科系の作文技術』/ 本多『日本語の作文技術』/
              結城『数学文章作法』/ 共同通信社『記者ハンドブック』)

skill 本体 (SKILL.md) には 0 章と 11 章 (= 最上位原則と自己点検) のみを置き、詳細 1-10 章 + 12 章は regulations.md を on-demand Read する設計です。SKILL.md を軽く保ち、深掘りは別ファイルに切り出すパターンで、本連載もこの skill 規範下で書かれています。

skills/pr-review/

役割: GitHub PR を多角的にレビューし [must] [imo] [ask] [nit] ラベル付き日本語で各 finding を個別の inline review comment として投稿する

起動: /pr-review [PR番号]

配信: disable-model-invocation: true (PR への comment 投稿という破壊的副作用を持つため、Claude 自身の自動起動を抑止し手動起動でしか動かない)

主な構成:

- 複数 agent を persona inject で流用
- frontend rubric を条件発火で補完 (rubrics/frontend.md)
- [must]/[imo]/[ask]/[nit] の 4 ラベルで finding を分類 (labels.md / label-mapping.md)
- 柔らかい日本語の tone 規範 (tone.md)

本 skill は単独 SKILL.md ではなく複数の補助 doc を伴う複数ファイル skill で、japanese-tech-writing/regulations.md と同じ「SKILL.md を軽く / 詳細は別ファイル」パターンに従っています。

他の skills/ ファイル (概要)

上記のほかにも、目的ごとに独立した Instruction が並んでいます。プロジェクト層を zero-footprint で scaffold する project-init、学習を learnings/ に記録する learn、「次にやるべきこと」を提案する next、次セッションへの引き継ぎプロンプトを生成する next-session-prompt、Backlog への起票や PR レビューコメントの一括処理を担う skill 群などです。skills/ も usage-driven で増減する facet で、現在の完全な一覧はここでは扱いません。

5.3. agents/ — Persona の代表例

agents/*.md は Persona (誰、振る舞いの主体) を集めた facet です。再構築前は多めの顔ぶれがありましたが、「自律開発フローに不可欠な役割」に絞り込んだ後、main agent の提示前 critique 用に devil-advocate を追加した経緯があります。他の facet と違い、agents/ は役割の性質上、増減のペースが緩やかで、以下は現在の全件に近い紹介です。

agents/architect.md

役割: spec から plan.md を設計

tools: Read / Grep / Glob / Write (handoff dir のみ)

Generator/Evaluator: Evaluator-ish (設計だが実装はしない)

---
name: architect
description: 仕様とコード探索から実装計画 (plan.md) を設計する。read-only、実装しない。
model: inherit
tools: Read, Grep, Glob, Write
---
あなたは design-first の実装計画立案者。spec.md と spawn prompt で注入された per-repo
知識を基に、コードベースを read-only で探索し、plan.md を handoff dir に Write で書く
(Write は handoff 専用、コードは変更しない)。

## 責務
- spec の各 pass 条件を実装計画でカバーする
- アーキテクチャ判断は選択肢と trade-off を併記する
- 影響範囲 (touch ファイル / API / DB schema) を列挙する
- **更新すべき doc を plan.md に明記する** (auditor の照合元)

## 制約
- **コードは read-only**。実装しない・worktree も使わない
- per-repo 知識は spawn prompt 注入で受領する
- 不確かなライブラリ仕様は推測で書かず、plan.md に「要裏取り」と明示する

agents/plan-reviewer.md

役割: spec ⇔ plan 照合、VERDICT: PASS|FAIL を出す gating agent

tools: Read / Grep / Glob / Write (review.md のみ)

Generator/Evaluator: Evaluator

---
name: plan-reviewer
description: architect の plan.md を spec 原本と照合する gating agent。
model: inherit
tools: Read, Grep, Glob, Write
---
あなたは critical な plan 検証者。spec.md 原本と plan.md を照合し VERDICT を出す。

## 検証観点
- **仕様カバレッジ**: spec の全 pass 条件が plan の実装計画でカバーされるか
- **敵対 critique 5 観点** (devil-advocate と射程一致): 破綻条件 / 空実装で通る
  pass 条件 / 既存衝突 / 隠れ前提 / 未検討の代替
- **None 判定にも根拠 1 行**: 「問題なし」という結論にも grep 結果や参照行番号を添える

## 出力契約 (output-contracts/review.md)
- 先頭行 VERDICT + 一次信号 + 指摘
- **最終発話の先頭行**に `VERDICT: PASS` または `VERDICT: FAIL` のいずれか一語を
  出力する (`PASS|FAIL` という文字列そのままは不可)

## ratchet surface
同型の指摘を 2 回観測したら末尾 1 行で「ratchet 候補: ...」と報告する

「敵対 critique 5 観点」は、devil-advocate と同じ観点を plan-reviewer 自身にも内蔵させたもので、plan が壊れる条件を能動的に探す責務を担います。

agents/developer.md

役割: story.md を単一入力に worktree 内で実装、pass 条件実行、task branch commit

tools: Read / Write / Edit / Bash

Generator/Evaluator: Generator

---
name: developer
description: story.md を単一入力に worktree 内で実装し、pass 条件を実行して証跡を残す。
model: inherit
tools: Read, Write, Edit, Bash
---
あなたは spec に忠実な実装者。story.md を唯一の主入力とし、worktree 内 (HEAD から
分岐) で実装する。

## 実装フロー
1. 依存 install (`npm install` 等)
2. story.md の実装計画に忠実に実装する (red → green)
3. pass 条件 (story の受入基準の検証コマンド) を **worktree 内で実行**する
4. done.md に証跡記録: pass 条件ごとに cmd + exit code + 出力要約 + PASS/FAIL
5. ドキュメント最新化 (story の「ドキュメント更新義務」列挙分)
6. task branch に commit する

## 制約
- **story.md が唯一の入力** (spec / plan は story に embed 済)
- pass 条件の実行は developer の責務 (auditor は実行しない)
- done.md の証跡は検証の ground truth — **正直に記録**する (exit code 捏造禁止)
- **仕様 (受入基準) を勝手に変えない**。変更が要るなら実装せず orchestrator に差し戻す

agents/auditor.md

役割: done.md ⇔ spec 原本再導出 + code ⇔ spec + doc 更新漏れの 3 本柱で照合、VERDICT を出す gating agent

tools: Read / Grep / Glob / Bash (git diff 用) / Write (review.md のみ)

Generator/Evaluator: Evaluator

---
name: auditor
description: done.md の実行証跡を spec 原本と照合する gating agent。read-only、
             自身は実行しない。
model: inherit
tools: Read, Grep, Glob, Bash, Write
---
あなたは evidence-based な監査者。done.md の実行証跡を spec.md 原本から再導出した期待と
照合し VERDICT を出す。**自身は pass 条件を実行しない** (コードは read-only / fresh
--bare 維持)。

## 照合の 3 本柱
1. **一次信号 (done.md 証跡 ⇔ spec 原本再導出)**: developer が done.md に記録した cmd
   + exit code + 出力を、spec.md 原本の pass 条件から再導出した期待と照合する
2. **code ⇔ spec**: `git -C <repo_root> diff <base-SHA>...<task-branch>` で diff を取得
   (worktree 非侵入)、仕様 / 制約と矛盾がないか
3. **doc 更新漏れ**: story の「ドキュメント更新義務」明示分の未更新 = FAIL、
   未列挙の不整合 = Minor warning

## 出力契約
- review.md を handoff dir に Write で書く (先頭行 VERDICT)
- **最終発話の先頭行**に `VERDICT: PASS` または `VERDICT: FAIL` のいずれか一語を
  出力する (`PASS|FAIL` という文字列そのままは不可)

「自身は pass 条件を実行しない」が takt の "Separation Improves Quality" 原則 (8 design principles の 1 つ) の核心です (第 3 章で扱った通りです)。

agents/devil-advocate.md

役割: main agent が人間に提示する直前の plan / 実装サマリー / 重大決定 AskUserQuestion を敵対的に critique (read-only、修正案は出さず破綻指摘のみ)

tools: Read / Grep / Glob (Bash / Write なし、pass 条件実行不可)

model: inherit

frontmatter 抜粋:

---
name: devil-advocate
description: main agent が人間に提示する直前の plan / 実装サマリー /
  重大決定 AskUserQuestion を敵対的に critique する。read-only、
  修正案は出さず破綻指摘のみ。
model: inherit
tools: Read, Grep, Glob
---

責務 (critique のみ・修正案禁止):

破綻条件:       plan / 実装が壊れる具体 scenario を最低 1 件挙げる
空実装 pass:    受入基準が no-op / mock で素通りしないか
既存衝突:       spec / per-repo policy / 既存 API と矛盾しないか (grep 裏取り)
隠れ前提:       「自明扱い」している前提を明文化させる
未検討の代替:   既存踏襲を採用理由にした箇所に、独立したベストプラクティス
                    比較の形跡があるか

出力契約として、先頭行が CRITIQUE: <破綻 | 不明 | 無し> で、続く各観点 1-2 行に致命度 Critical / Major / Minor を付ける形式が定められています。修正案を禁止しているのは、Generator-Evaluator 分離の核心です。修正案を書かせると main agent の修正主体性が侵食され、ループが二重判断に陥ります。devil-advocate は破綻指摘のみで止め、main agent が「採否・反論・修正方針」を担います。

/autodev 連鎖内の plan-reviewer (architect の plan を spec 原本と照合する gating agent) / auditor (developer の done.md を spec 原本と照合する gating agent) と役割が重なって見えるため、rules/adversarial-review.md は autodev 連鎖内では本 agent を二重起動しないルールを明示しています (本章 5.1 節)。

5.4. hooks/ — enforcement の代表例

hooks/ は Computational Sensor として enforcement 層を担います。Inferential Guide (rule) で書かれた規範のうち、確率的失敗が実害につながるものを deterministic に止めるか log します。以下は block 型と log-only 型それぞれの代表例です (hooks/ も usage-driven で増える facet で、以下は全件ではありません)。

hook	matcher	block/log	enforcement 対象 facet
`check-git-commit-gate.sh`	PreToolUse / Bash	block (exit 2)	`rules/git.md` (明示トリガー語要件)
`check-plain-question.sh`	Stop	block (exit 2)	`rules/interaction.md` (平文質問禁止)
`check-action-completion.sh`	Stop	log-only	`rules/verification.md` (状態変更操作の完了報告)
`check-pre-edit-search.sh`	PreToolUse / Edit・Write・MultiEdit	log-only	`rules/search-before-coding.md` (Edit 前の未 Read 検出)

各 hook は false positive 用の迂回経路を持たせています。check-git-commit-gate.sh は marker file 方式 (touch ~/.claude/.skip-git-commit-gate-once) で、check-plain-question.sh は環境変数 (CLAUDE_HOOK_SKIP_PLAIN_QUESTION=1。ただしセッション内の export は hook プロセスに届かないため、CLI 起動前の export による恒久無効化専用) で迂回します。hook ごとに迂回方式が異なるのは、Claude Code 仕様で環境変数が hook プロセスに継承されないケースがあるためで、commit gate はこの制約に気づいた後 env 方式から marker file 方式へ移行した経緯があります (08 章の改修例で扱います)。

hooks/tests/ 配下には各 hook の単体テストが入っており、hook 自身を「テストされた enforcement」として扱う設計です。検出ロジックを silent 変更しないための安全弁です。

check-git-commit-gate.sh の中身

中核 hook である check-git-commit-gate.sh の検出ロジック (主要部分) を引用します。

# git commit subcommand 検出 (option 経由含む、log --grep=commit は除外)
COMMIT_PATTERN='(^|[^A-Za-z0-9_-])git[[:space:]]+(-[A-Za-z][A-Za-z0-9-]*([= ][^[:space:]]+)?[[:space:]]+)*commit([[:space:]]|$)'
echo "$COMMAND" | grep -Eq "$COMMIT_PATTERN" || exit 0

# 直近 user 由来 message の text 抽出 (lenient parse)
# user role には (a) 人間/orchestrator の発話 と (b) tool_result の 2 系統が混在する。
# subagent transcript では最後の user message が tool_result になりがちで、(a) を取り損ねる
# 対策として、(b) のうち AskUserQuestion の回答 ("Your questions have been answered:"
# で始まる tool_result、= 人間の明示判断と等価) だけは特別扱いで拾い、それ以外の
# tool_result (Bash 出力等) は除外して純 text 由来の user message を取る。
LAST_USER_TEXT=$(
  jq -R 'fromjson?' "$TRANSCRIPT_PATH" 2>/dev/null \
    | jq -s -r '
        def extract:
          .message.content
          | if type == "string" then .
            elif type == "array" then
              [ .[]
                | if (type == "object" and has("tool_use_id")) then
                    if ((.content // "" | type == "string")
                        and (.content // "" | startswith("Your questions have been answered:")))
                    then .content
                    else empty
                    end
                  else (.text // .content // "")
                  end
              ] | join("\n")
            else "" end;
        [ .[]
          | select(.type=="user")
          | extract
          | select(. != null and . != "")
        ] | last // ""
      ' 2>/dev/null
)

# トリガー語: 動詞ベース (commit / コミット / push / プッシュ / マージ / merge / 反映)
TRIGGER_PATTERN='commit|コミット|push|プッシュ|マージ|merge|反映'

if [ -n "$LAST_USER_TEXT" ] && echo "$LAST_USER_TEXT" | grep -iqE "$TRIGGER_PATTERN"; then
  exit 0
fi

cat >&2 <<EOF
Detected: git commit 実行に直近 user turn の明示トリガー語が見つかりません。
規範: ~/.claude/rules/git.md \`## コミット\` 節 (明示トリガー語要件)
EOF
exit 2

tool_result を素朴に全除外するだけでは、AskUserQuestion で「commit する」を選んだ回答も除外されてしまい、直後の commit が block されてしまいます。そこで tool_result のうち AskUserQuestion の回答だけを特別扱いで拾う、という一段複雑な分岐になっています。subagent でも spawn prompt のトリガー語を正しく拾えるようにする工夫は変わらず健在です。詳細な経緯は第 8 章で扱います。

check-plain-question.sh の中身

check-plain-question.sh は複数種類の検出パターン (「どうしますか」等の明示疑問形、婉曲な確認、選択肢の並置、承認前提の進行宣言など) で平文質問を grep します。

EXPLICIT='どうしますか|どうしましょうか|よろしいですか|よろしいでしょうか|いいですか[?？]|修正しますか|実行しますか|進めますか|続けますか|採用しますか|...'
SOFT='(修正|追加|削除|実装|変更|採用|進め|続け|やり|やる|やめ).{0,10}(ましょうか|ますか)[[:space:]]*[?？]?[[:space:]]*$'
QUESTION_MARK='(進め|続け|修正|実行|採用|選び|選択|どちら|どれ|いつ|何|どこ|どう).{0,30}[?？][[:space:]]*$'
IMPLICIT_CHOICE='(\([abcde]\)|（[abcde]）|①|②|③|④)[^。\n]{0,60}(か|なら|または|あるいは)[^。\n]{0,60}(\([abcde]\)|（[abcde]）|②|③|④|⑤)'
CONFIRMATION='(ここまで|これで|この方向で|この内容で|この方針で)?[[:space:]]*(OK|ok|...)...'

承認を前提に「進めます」と平叙文で宣言する型 (承認待ちを明言しないまま先に進む) や、逆に「明示指示までは保留します」と平叙文で待機を宣言する型も、後から検出パターンに加わりました。無限ループ防止として STOP_HOOK_ACTIVE=true の場合は通過、直近 AskUserQuestion / ExitPlanMode tool_use が使われていれば skip する設計です。

check-action-completion.sh の log-only 設計

check-action-completion.sh は他の Stop hook と違い、log-only (= block しない) で運用しています。

# log-only material (block しない)。CLAUDE_HOOK_LOG_DIR は test 隔離用。
LOG_DIR="${CLAUDE_HOOK_LOG_DIR:-$HOME/.claude/logs}"
mkdir -p "$LOG_DIR" 2>/dev/null || true
{
  echo "[$TS] action-completion DETECTED (log-only): kind=$DETECT"
  echo "  claim(head): $(log_head "$LAST_ASSISTANT_TEXT")"
} >> "$LOG_DIR/action-completion.log" 2>/dev/null || true

exit 0

precision 未知の検出は log で蓄積してから block 化判断する方針で、これは Ratchet 運用 (= 失敗 1 件で hook 化せず、material を 2-3 件蓄積してから昇格) と同型です。

check-pre-edit-search.sh の log-only 設計

bootstrap 後に追加された check-pre-edit-search.sh は、rules/search-before-coding.md の「Edit 前にシンボル接地」規範を log-only で観測します。冒頭コメントを引用します。

#!/bin/bash
# Computational Sensor (log-only): Edit / Write / MultiEdit tool 呼び出し前に、
# 対象 file_path が当該 session の transcript 内で Read されたかをチェックし、
# 未 Read なら ~/.claude/logs/pre-edit-search.log に material として記録する。
# 常に exit 0 (block しない)。
#
# 背景: Edit tool description は「Edit 前 Read 強制」だが、Write tool (上書き含む)
# と MultiEdit は強制が弱い。記憶ベースで file_path を組み立てて編集する
# hallucination リスクに対する Sensor。
#
# 正直な限界: jsonl の Read 履歴のみチェック。Glob/Grep で内容確認したケースは
#   未読扱い (FP)。precision 未知ゆえ log-only (block 化は log 蓄積 + 実測後に
#   別判断)。

注目点は 「正直な限界」コメントです。Glob/Grep で内容確認したケースを false positive として扱うことが明示されており、block 化は「log 蓄積 + 実測後に別判断」と保留しています。これは ~/.claude/CLAUDE.md の「hooks は実証後」規律 (= 同型の失敗 2 回 + 対応 facet の存在が前提) を事前に log で precision を測ってから昇格する運用に落とした形です。Computational Sensor は bootstrap 同時許容の例外条項を使って先行投入し、log 結果に応じて block 化または削除を判断します。

5.5. output-contracts/ — Output Contract の代表例

output-contracts/*.md は nrslib/takt 公式 facet "Output Contract" の Claude Code 実装です (takt の Workflow YAML 内で各 step が持つ output_contracts: フィールドに相当)。subagent の成果物テンプレートを格納します。autodev フローの中核をなす代表的な 5 種類を紹介します (この facet も今後増える可能性があります)。

ファイル	用途	産出 subagent	機械判定対象
`spec.md`	受入基準 (pass 条件) を含む仕様	spec-design (人間 + AI 協働)	pass 条件の SHA256 (state.md に凍結)
`plan.md`	実装計画 / アーキ判断 / 影響範囲 / doc 更新義務	architect	plan-reviewer の VERDICT
`story.md`	spec + plan を合成した developer 用単一入力	orchestrator (合成)	(中継ファイル)
`done.md`	実行証跡 (pass 条件ごとの cmd + exit code + 出力 + PASS/FAIL)	developer	auditor の VERDICT
`review.md`	VERDICT 報告書	plan-reviewer / auditor	orchestrator の `grep '^VERDICT:'`

plan.md テンプレ (column 化された doc 更新義務)

plan.md テンプレの全文を引用します。

# plan: <feature 名>

> Output Contract (テンプレート)。architect が spec.md + per-repo 知識から生成し、
> plan-reviewer の VERDICT を通す。

## 実装計画
<step-by-step。各 step が spec のどの pass 条件に対応するか追えること>
1. ...

## アーキテクチャ判断
<選択肢と trade-off を併記。採用案と却下案の理由を明示>

## 影響範囲
<touch するファイル / API / DB schema を列挙>

## ドキュメント更新義務
<列挙: 対象パス + 層 (pointer / 実 repo) + 更新者 (developer / orchestrator 代行)
+ 検証経路を column 化。auditor の照合元、orchestrator が story.md に verbatim 転記する>

| 対象パス | 層 | 更新者 | 検証経路 |
| --- | --- | --- | --- |
| ... | pointer / 実 repo | developer (worktree commit) / orchestrator (代行) |
                       auditor Read / git diff |

「層」列が pointer / 実 repo を区別している点が重要です。pointer 層 (~/.claude/repos/<repo>/ 配下) は worktree から到達不能なため、developer は commit できません。orchestrator が代行更新します。実 repo (worktree 内) は developer が commit します。

このテンプレは bootstrap 時点では column 化されておらず、運用の中の改修で詰めた箇所です (第 8 章)。

review.md テンプレ (VERDICT 先頭行)

review.md テンプレの全文を引用します (先頭行の PASS|FAIL はテンプレート上の記法で、実際の出力では PASS か FAIL のどちらか一語になります)。

VERDICT: PASS|FAIL

> Output Contract (テンプレート)。汎用検証レポート。plan-reviewer (spec ⇔ plan) と
> auditor (done.md 証跡 ⇔ spec 原本) が共用する。
> **最終発話の先頭行**および review.md 先頭行に `VERDICT: PASS` または
> `VERDICT: FAIL` のいずれか一語を必ず置く (`PASS|FAIL` という文字列そのままは不可、
> orchestrator が `grep '^VERDICT:' review.md` で fail-closed 分岐)。

## 一次信号
<plan-reviewer: spec の pass 条件カバレッジ / auditor: done.md 証跡 ⇔ spec 原本から
 再導出した期待の照合結果>

## 照合詳細 (N/A 許容)
- 仕様カバレッジ / 非自明性 (空実装・no-op で通らないか):
- code ⇔ spec (auditor: `git diff <base>...<branch>` と仕様に矛盾がないか):
- doc 更新漏れ (story 明示分 = FAIL / 未列挙の不整合 = Minor warning):
- per-repo policy 違反:

## 指摘 (FAIL 時)
<差し戻し先のパスと具体的な修正指示>

## ratchet 候補 (あれば末尾 1 行)
<同型の指摘を観測したら「ratchet 候補: ...」と報告>

先頭行が VERDICT: PASS|FAIL で固定されていることで、orchestrator は grep '^VERDICT:' のみで分岐判定でき、review.md 全文を context に読み込まなくて済みます。長文 review の context 圧迫を構造的に避ける設計です。

5.6. knowledge/ — 共通 Knowledge プール

knowledge/ は Knowledge (記述的知識、on-demand Read) を集める facet です。bootstrap 時点では空でしたが、運用の中で必要になったドメインの参照プールが少しずつ追加されています (コーディングのベストプラクティス集、API/DB 設計、UI/QA レビューの観点集など)。

代表例として coding-accuracy-2026.md の冒頭を引用します。

# Knowledge: 2026 年コーディング精度ベストプラクティス pool

> Kuro 裁量で作成。本ファイルは規範ではなく**参照プール**。規範執筆
> 時はここを起点に context7 / WebFetch で再裏取りしてから本文化する。
> `/harness-prune` の 30 日参照ゼロ検出対象。

## 一次ソース URL (Step 0.4 spot-check 済)

| URL | 状態 | 用途 |
|---|---|---|
| code.claude.com/docs/en/best-practices | 200 OK | Claude Code 本体 |
| platform.claude.com/.../extended-thinking | 200 OK | manual / adaptive thinking |
| platform.claude.com/.../claude-4-best-practices | 200 OK | prompt-engineering |

重要な設計判断が**「規範でなく参照プール」である点と「規範執筆時はここを起点に再裏取り」である点です。Knowledge は他 facet と違って一次ソースから引いた抜粋**を保持しますが、それを根拠に規範を書くと「いつ変わったか分からない外部仕様への依存」が生まれます。だから本 facet は中継地点として保持し、規範本文化の前に context7 / WebFetch で再裏取りする運用を冒頭注記で明示しています (rules/fact-check.md の「MCP 第一選択」と整合)。

加えて、/harness-prune の 30 日参照ゼロ検出対象に knowledge/ 配下も含まれる点が、Knowledge の暴走 (記憶代わりに肥大化) を構造的に抑える仕掛けです (逆 ratchet については 07 章で扱います)。

5.7. 本章のまとめ

要点

rules: usage-driven 追加で少しずつ増えている Policy 集。全ファイルが paths: なし常時ロードで subagent にも届く。verification / fact-check / interaction / git / adversarial-review など、異なる規律パターンが並ぶ
skills: 自律開発系 (spec-design / autodev / smi-auto-dev / project-init)、保守系 (harness-prune)、学習系 (learn)、orchestration 系 (next / next-session-prompt) など目的別に分かれた Instruction 集
agents: architect (設計) / plan-reviewer (照合) / developer (実装) / auditor (監査) + devil-advocate (提示前 critique)。tool 制約で Generator-Evaluator 分離を構造的に強制
hooks: block 型 (check-git-commit-gate check-plain-question など) と log-only 型 (check-action-completion check-pre-edit-search など) が並存。block 化前に log で precision を測る運用。テスト本体は hooks/tests/ 配下
output-contracts: spec / plan / story / done / review。review.md 先頭行の VERDICT 規約が autodev フローの fail-closed 分岐を支える
knowledge/: 規範でなく参照プール運用で、規範本文化前に context7 / WebFetch で再裏取りする中継地点。usage-driven でドメインが増えていく

次章では、これらの facet が実際に組み合わさって動く autodev フローを、autodev-smoke の anagram-check task を例に最初から最後まで walkthrough します。

5.1. rules/ — Policy の代表例​

rules/verification.md​

rules/fact-check.md​

rules/interaction.md​

rules/git.md​

rules/adversarial-review.md​

他の rules/ ファイル (概要)​

5.2. skills/ — Instruction の代表例​

skills/autodev/​

skills/spec-design/​

skills/harness-prune/​

skills/japanese-tech-writing/​

skills/pr-review/​

他の skills/ ファイル (概要)​

5.3. agents/ — Persona の代表例​

agents/architect.md​

agents/plan-reviewer.md​

agents/developer.md​

agents/auditor.md​

agents/devil-advocate.md​

5.4. hooks/ — enforcement の代表例​

check-git-commit-gate.sh の中身​

check-plain-question.sh の中身​

check-action-completion.sh の log-only 設計​

check-pre-edit-search.sh の log-only 設計​

5.5. output-contracts/ — Output Contract の代表例​

plan.md テンプレ (column 化された doc 更新義務)​

review.md テンプレ (VERDICT 先頭行)​

5.6. knowledge/ — 共通 Knowledge プール​

5.7. 本章のまとめ​

5.1. rules/ — Policy の代表例

rules/verification.md

rules/fact-check.md

rules/interaction.md

rules/git.md

rules/adversarial-review.md

他の rules/ ファイル (概要)

5.2. skills/ — Instruction の代表例

skills/autodev/

skills/spec-design/

skills/harness-prune/

skills/japanese-tech-writing/

skills/pr-review/

他の skills/ ファイル (概要)

5.3. agents/ — Persona の代表例

agents/architect.md

agents/plan-reviewer.md

agents/developer.md

agents/auditor.md

agents/devil-advocate.md

5.4. hooks/ — enforcement の代表例

check-git-commit-gate.sh の中身

check-plain-question.sh の中身

check-action-completion.sh の log-only 設計

check-pre-edit-search.sh の log-only 設計

5.5. output-contracts/ — Output Contract の代表例

plan.md テンプレ (column 化された doc 更新義務)

review.md テンプレ (VERDICT 先頭行)

5.6. knowledge/ — 共通 Knowledge プール

5.7. 本章のまとめ