ディレクトリ構成と合成規約
本連載は執筆時点のハーネス実環境 (設定ファイルの内容、実行記録、ファイル数) を素材にした記録です。ハーネス本体は公開後も改修が続いているため、引用したファイル内容や個数、手順は現在の実体と異なる場合があります。本連載の主眼は個々の値ではなく設計の考え方 (5 関心分離、検証ゲート、成長規律) にあります。
本章は、ここまで扱ってきた 5 facet (takt 由来) + orchestrator (takt 思想採用) が、実際にどんなディレクトリ構造で配置されているかを扱います。
主な内容は次の 3 つです。
- 再構築後のディレクトリ全体像 (何が廃止され、何が新設され、何が usage-driven で増えていくか)
- criticality (重要度) 3 段で配信方式を分ける合成規約
- subagent 経路の context loss を防ぐ設計判断 (path-scoped 禁止 / 絶対パス注入)
4.1. ディレクトリ全体像
~/.claude/ 配下を ls で見ると、次のような構成になっています (rules/skills/hooks/output-contracts/knowledge の中身は usage-driven で増減するため、以下は代表例のみ挙げています)。
~/.claude/
├── CLAUDE.md # 思想と索引のみ
├── rules/ # Policy: verification.md / fact-check.md / git.md / interaction.md など
├── skills/ # Instruction: autodev/SKILL.md / spec-design/SKILL.md / harness-prune/SKILL.md など
├── agents/ # Persona
│ ├── architect.md
│ ├── auditor.md
│ ├── developer.md
│ ├── devil-advocate.md
│ └── plan-reviewer.md
├── hooks/ # Computational Sensor: check-git-commit-gate.sh / check-plain-question.sh など
│ └── tests/ # hook のテストスクリプト
├── output-contracts/ # Output Contract (新設): plan.md / review.md / done.md など
├── knowledge/ # 共通 Knowledge (usage-driven で追加)
├── repos/ # per-repo Knowledge (project-init で生成)
│ └── <repo>/
│ ├── .repo_root
│ ├── CLAUDE.md
│ ├── CONTEXT.md
│ ├── INDEX.md
│ ├── mcp.json
│ ├── specs/
│ ├── adr/
│ ├── knowledge/
│ └── handoff/
├── learnings/ # /learn 出力 (per-domain カテゴリ)
├── plans/ # 計画ファイル (cold-start プロンプト)
├── projects/ # auto-memory (per-project memory store)
└── settings.json
commands/ / references/ / teams/ / scripts/ の 4 dir は廃止しています。理由は次の通りです。
| 廃止 dir | 再構築前の用途 | 廃止理由・移管先 |
|---|---|---|
commands/ | 自作 slash command | 起動キーワードは skills/ の SKILL.md で完結。custom command の独立性が薄いため廃止 |
references/ | Anthropic 公式 doc 抜粋 / Pricing 表 / 業界記事ローカル保存 | on-demand 取得 (WebSearch / MCP) で代替。stale ローカル保存は更新追従できないため廃止 |
teams/ | チーム共通の persona | 1 件のみだったため Persona は agents/ に集約、teams/ は廃止 |
scripts/ | 月次 health check / metrics 集計 | /harness-prune skill に集約。独立 dir は廃止 |
4.2. 構成の変遷 (何が削られ、何が新設され、何が増えていくか)
第 1 章で扱った通り、ゼロ再構築は「圧縮して終わり」の一度きりの act ではなく、その後の usage-driven 追加も含めて評価する必要があります。ディレクトリ単位で見た変化を、3 つに整理します。
変化 1: 規範本体の集約 (rules / agents) → usage-driven 追加で再拡張
再構築前の rules/ には、規範・具体例・手順がしばしば混在し、同じ規範 (verification / fact-check / git / interaction など) が重複していました。bootstrap では「1 ファイル 1 関心」に切り直す形で大きく絞り込み、その後は運用の中で「同じ指摘を手で 2 回出した」事象が起きるたびに facet 化する規律 (第 7 章) に従って、少しずつ増えていきました。agents/ も同様にゼロ再構築で絞り込んだ後、main agent の提示前 critique 用に devil-advocate を追加した経緯があります。
変化 2: enforcement の deterministic 化 (hooks)
再構築前は hook がほとんど無く、規範は rules (Inferential Guide) だけに頼っていました。新ハーネスでは「Inferential Guide で書いた規範のうち、本当に外せないものを Computational Sensor で deterministic に止める」方針に転換し、他の facet より先行して hook を増やしました。投入した hook の例:
check-git-commit-gate.sh(commit 規律 enforcement)check-plain-question.sh(平文質問禁止 enforcement)check-action-completion.sh(完了主張 + 検証不在の検出)check-pre-edit-search.sh(Edit / Write / MultiEdit 前の未 Read 検出、log-only Computational Sensor)
これらは全て、対応する Policy facet が rules/ に存在することを前提に設置しています (= orphan hook 禁止)。例外は say-notify.sh のような、notification 用途で Policy facet と直接対応しないインフラ寄り hook です。check-pre-edit-search.sh は bootstrap 後の usage-driven 追加の例で、rules/search-before-coding.md を追加したのと同タイミングで投入されました (第 7 章 で扱う「hooks は実証後」規律の例外条項 = bootstrap 同時許容を使った導入)。
変化 3: Output Contract 層の新設
output-contracts/ は nrslib/takt 公式 facet (Workflow YAML の各 step が持つ output_contracts: フィールドに相当) を本ハーネスの再構築で独立化したものです。再構築前は存在せず、subagent の出力フォーマットが各 agent body 内で都度書かれていました。新ハーネスでは、
spec.md(spec-design 出力)plan.md(architect 出力)story.md(orchestrator が spec + plan を合成した developer 用単一入力)done.md(developer 実行証跡)review.md(plan-reviewer / auditor の VERDICT)
といった成果物を独立テンプレ化しています。各 agent body には「VERDICT 契約」「先頭行規約」といった参照だけを書けば足り、テンプレ本体は agent body から独立して進化できる構造です。
4.3. 合成規約: criticality 3 段配信
ディレクトリ構造を整えても、それらを どう Claude に届けるか (合成戦略) は別の問題です。Claude Code には composer (= 複数 facet を結合する組立装置) が無く、「全 facet を Read で繋いで合成しようとする」と確率的に silent drop します (第 1 章 症状 4)。
新ハーネスは、重要度 (criticality) で配信方式を 3 段に分けます。
3 段それぞれを掘り下げます。
段 1: gating facet → inline + hooks
ループの合否を左右する規範 (= gating facet、takt 原則 1 "Agents Are Powerful, but Not Authoritative" / 原則 2 "Structure Over Prompting" に対応) は、agent body に inline で本文を書きます。Read 経路に任せると確率的に脱落するため、確率的失敗が許されない規範は本体を agent body に置きます。
具体例として、agents/plan-reviewer.md の出力契約 section を引用します。
## 出力契約 (output-contracts/review.md)
- review.md を handoff dir に Write で書く (先頭行 VERDICT + 一次信号 + 指摘)
- **最終発話の先頭行**にも `VERDICT: PASS|FAIL` を必ず出力する。続けて 1-3 行サマリ
+ review.md の handoff パス
- **発話の先頭行を `VERDICT: PASS|FAIL` にする** (review.md も先頭行 VERDICT)。
VERDICT を出したら説明を続けず即終了してよい (VERDICT 存在は orchestrator が
review.md で最終確認する)
「VERDICT: PASS|FAIL を最終発話の先頭行に必ず出力する」は autodev フローの fail-closed 分岐 (grep '^VERDICT:') を成立させる gating 規約です。これが脱落するとループが進めません。
加えて hook check-action-completion.sh (Stop sensor) で、「完了しました」が出ているのに検証コマンドが走っていない時に警告するなど、Inferential Guide + Computational Sensor の組で強制します。
段 2: Instruction → story.md / spawn prompt への合成・embed
手順 (Instruction、= SKILL.md) は main agent (= orchestrator) 自身がロードして手順通りに動きますが、subagent にはその本文をそのまま渡す経路がありません。orchestrator が必要な手順・受入基準を story.md (または spawn prompt) に合成・embedして届けます。
例として、autodev フローでは orchestrator が developer subagent を spawn する時、spec + plan から合成した story.md のパスと per-repo 知識の絶対パスを spawn prompt に注入します。developer の agents/developer.md 本体には Persona と制約だけが書かれ、具体手順は story.md 側に embed されています。
---
name: developer
description: story.md を単一入力に worktree 内で実装し、pass 条件を実行して証跡を残す。
model: inherit
tools: Read, Write, Edit, Bash
---
あなたは spec に忠実な実装者。story.md を唯一の主入力とし、worktree 内 (HEAD から
分岐) で実装する。
agents/developer.md 本体には Persona と制約だけが書かれ、具体手順は story.md (= orchestrator が plan.md + spec.md を合成した派生物) として注入されます。これにより、agents/developer.md は ≤30 行に収まり、手順の進化は story.md / SKILL.md 側で独立にできる構造です。
段 3: Knowledge / 記述的 Policy → 索引 + on-demand Read
記述的 Knowledge と、走行時に確率的に必要になる Policy は 索引 (CLAUDE.md / INDEX.md) からの参照 + 必要時 Read で届けます。
本文コピーは禁止します (silent drop 回避目的で本文コピーを許容するのは段 1 だけ)。Knowledge の本体は 1 ファイルにだけ置き、他の場所からは参照だけします。
per-repo 知識の場合は、~/.claude/repos/<repo>/INDEX.md が索引の役割を果たします。INDEX.md は 1 行/ファイル + 用途 hook の索引で、/autodev の ⓪' phase で orchestrator が読み込み、タスクに関連するファイルだけを on-demand Read します (push でなく Pull、第 3 章 で takt 公式概念との対応を扱った通り)。
4.4. subagent 経路の context loss を防ぐ 2 つの原則
合成規約に加えて、subagent への規範到達を保証するための原則が 2 つあります。
原則 1: subagent 依存 Policy は path-scoped 禁止
rules/*.md の frontmatter に paths: を書くと、その rule は指定 path に該当する work tree でのみロードされます。これは main agent では便利ですが、subagent には届きません。
理由は、subagent は spawn 時に独自の system prompt 経路で起動し、main agent の paths-scoped rule をロードする経路を持たないためです。autodev フローで developer / auditor subagent に届かない Policy があると、worktree 内での実装規律や監査規律が壊れます。
新ハーネスでは、subagent 到達必須の Policy は paths: なし = 常時ロードにしています。例えば:
rules/verification.md(証跡規範、developer / auditor が依存)rules/git.md(commit 規律、developer が依存)rules/fact-check.md(発言前裏取り規範、全 agent が依存)rules/interaction.md(AskUserQuestion 規範、main agent が依存)rules/search-before-coding.md(シンボル接地、developer / architect が依存)rules/handoff-discipline.md(session 跨ぎ規範、orchestrator / developer / auditor が依存)
rules/ 配下は usage-driven 追加でこの後も増えていきますが、subagent が依存する Policy は例外なく paths: なし常時ロードにするという原則自体は変わりません。本当に常時必要なものだけを Policy にするのが運用上の hygiene で、ドメイン特化 (例: Terraform / Docker) は別経路 (CLAUDE.md 索引から on-demand Read される knowledge) に逃がしています。
@import も agent body で展開されないrules/*.md の frontmatter で @import を使うと「他 rule を取り込める」ように見えますが、Claude Code の現仕様では agent body で @import が展開されません。これも subagent 経路の context loss の典型例で、新ハーネスでは @import は使わない方針です (本ファイルを丸ごとロードする経路に統一)。
原則 2: per-repo 知識は orchestrator が絶対パスで明示注入
~/.claude/repos/<repo>/CLAUDE.md や CONTEXT.md は main agent の workspace root の外 (= ~/.claude/ 配下) にあるため、subagent の自動 path-scoped ロードでは届きません。
実例として、autodev フローの ① architect spawn phase の記述を引用します。
## ① architect spawn (read-only, fresh)
spawn prompt に spec.md + **per-repo 知識を絶対パス注入** (`~/.claude/repos/<repo>/CLAUDE.md`
policy / `CONTEXT.md` 用語 / 選択 knowledge、worktree 越境で自動到達しない上に
**pointer 層 = worktree 外なので developer commit 対象外**) → architect が plan.md を生成
orchestrator は spawn prompt に 絶対パス (/Users/<name>/.claude/repos/<repo>/...) を注入します。~ 展開は subagent の context で効かないことがあるため、フル展開した絶対パスを書きます。
これにより:
- architect は spec + per-repo CLAUDE.md (per-repo Policy) + CONTEXT.md (用語集) を参照しながら plan.md を生成できる
- developer は story.md (orchestrator が embedded した派生物) を単一入力にする → per-repo 知識は story 内に inline 済 (SELECTIVE 抽出)
- auditor は spawn prompt に per-repo 知識の絶対パスを再注入される
この 2 原則によって、subagent 種別が増えても規範到達は構造的に保証されます。
4.5. CLAUDE.md の役割 (索引と思想)
最後に、再構築前は長大だった CLAUDE.md が、再構築後は短いまま維持されている理由を整理します。
新ハーネスの CLAUDE.md には次のものだけが書かれています。
# CLAUDE.md — faceted harness (takt / Faceted Prompting 思想)
## 誰と話すか (Persona 概要)
## どう尋ねるか (正本: rules/interaction.md) (AskUserQuestion 規範)
## どう提示するか (正本: rules/adversarial-review.md) (devil-advocate 起動規範)
## ハーネスの構成 (Faceted Prompting = 5 関心分離) (5 facet 表 + hooks の位置づけ)
## 合成規約 (criticality で配信方式を分ける) (criticality 3 段配信)
## 成長規律 (再肥大化の構造的防止) (5 規律表)
## 自律開発フロー (/spec-design + /autodev の 1 行入口)
書かれているのは 思想と索引だけで、具体的な規範や手順は書きません。
- 規範は
rules/<name>.mdを参照 - 手順は
skills/<name>/SKILL.mdを参照 - 出力契約は
output-contracts/<name>.mdを参照 - Knowledge は
knowledge/<name>.mdまたはrepos/<repo>/...を参照
これにより、CLAUDE.md は「全体像をいつでも見渡せる索引」として機能し、各 facet の本体は独立に進化できます。再構築前は CLAUDE.md に主要規範が直接書かれていたため、改修ごとに CLAUDE.md が膨張するフィードバックループに入っていました。
CLAUDE.md の役割を「索引と思想」に絞ったことで、改修速度が大きく上がりました。新しい規範を追加するときは:
- どの facet に属するかを判定 (5 択 + 1 hooks)
- 該当 facet の本体ファイル (
rules/<name>.mdなど) を改修 - CLAUDE.md は触らない (索引なので、新 rule の存在は subagent には自動到達する)
これにより、改修コストが O(1) (本体 1 箇所のみ) で済みます。
4.6. 本章のまとめ
- ハーネス全体は 5 facet (
rules/skills/agents/output-contracts/knowledge/) + hooks に整理された構成。ゼロ再構築で大きく圧縮した後、usage-driven 追加で規律を保ったまま再成長した。output-contracts/は takt 公式 facet を採用 - 廃止 dir 4 種 (commands / references / teams / scripts) は SKILL や on-demand 取得に移管
- 合成規約は criticality 3 段: gating facet は inline / Instruction は story.md・spawn prompt への合成 / Knowledge は索引 + on-demand
- subagent context loss を防ぐ 2 原則: paths-scoped 禁止 (常時ロード) と 絶対パス明示注入 (per-repo 知識)
- CLAUDE.md は「索引と思想」に絞って短く維持し、改修は本体 facet 側で完結する設計
次章は、ここまでで整理した 5 facet + hooks + knowledge の各層を、実コード引用付きで詳しく見ていきます。rules/ skills/ agents/ hooks/ output-contracts/ knowledge/ それぞれの役割と代表例を辞書的に並べます。