takt 思想の採用: nrslib/takt から Claude Code への移植
本連載は執筆時点のハーネス実環境 (設定ファイルの内容、実行記録、ファイル数) を素材にした記録です。ハーネス本体は公開後も改修が続いているため、引用したファイル内容や個数、手順は現在の実体と異なる場合があります。本連載の主眼は個々の値ではなく設計の考え方 (5 関心分離、検証ゲート、成長規律) にあります。
本章は、本連載のもう 1 つの核である takt 思想の採用 を扱います。
「takt」は nrslib/takt という AI Agent Orchestration Framework (CLI tool, MIT License, 作者: nrslib) が提唱する設計思想です。本ハーネスは takt CLI は使わず、takt が定義する Faceted Prompting / Output Contracts / Worktree Isolation / 8 design principles などの思想を、Claude Code の skills/ + agents/ + ~/.claude/repos/<repo>/handoff/ + hooks/ という独自の構成要素に移植して運用しています。
本章では、まず takt 本体が何かを紹介し (3.1-3.3)、その思想を本ハーネスがどう Claude Code に独自移植したか (3.4-3.6) を対応表付きで掘り下げます。
3.1. takt とは何か
nrslib/takt は AI コーディングエージェントを「構造化された再現可能な開発ワークフロー」に変える OSS CLI です。
| 項目 | 内容 |
|---|---|
| リポジトリ | github.com/nrslib/takt |
| 作者 | nrslib |
| License | MIT |
| 種別 | AI Agent Orchestration Framework (CLI) |
| 対応 provider | Claude Code / Claude SDK / Codex / OpenCode / Cursor / GitHub Copilot CLI / Kiro |
| 主な CLI | takt (タスク登録) / takt run (実行) / takt list (結果管理) |
語源
README より verbatim:
"The name TAKT comes from the German word for 'beat' or 'baton stroke,' used in conducting to keep an orchestra in time."
つまり「指揮者がオーケストラの timing を保つ baton stroke (拍)」が由来です。製造業の生産ライン用語としての takt time とは無関係で、指揮者比喩で名付けられています。
解決する問題
README より要旨:
AI エージェントは長時間の作業で「指示を忘れる / context が汚染される / 実装と review の責任が混ざる」という構造的問題を抱えます。takt はこれを、エージェントを自律判断する主体としてではなく、定義されたプロセスの中で外部制御される実体として扱うことで解決します。
3.2. takt の 8 design principles
takt design philosophy より、第 1 列の原則名のみを verbatim 引用します。第 2 列の説明は原文の趣旨を筆者が要約したもので、verbatim ではありません (原文は同 doc を参照)。第 3 列に本ハーネスでの対応を併記します。
| # | takt 原則 | 本ハーネスでの対応 |
|---|---|---|
| 1 | Agents Are Powerful, but Not Authoritative — AI output is probabilistic; process structure, not plausibility, validates decisions | VERDICT: PASS|FAIL 出力契約 + grep '^VERDICT:' で機械判定。LLM の plausibility に依存しない |
| 2 | Structure Over Prompting — Explicit workflow definitions and rules replace reliance on agent memory | skills/autodev/SKILL.md で ⓪'-⑤ 手順を明示。memory 依存を排除 |
| 3 | Separation Improves Quality — Distinct roles and knowledge domains prevent conflicts of interest | architect / plan-reviewer / developer / auditor の 4 subagent + tool 制約で Generator-Evaluator 分離を構造的に強制 |
| 4 | Feedback Loops Are First-Class — Review, fix, and arbitration cycles have defined boundaries | plan 差し戻し最大 1 / 実装差し戻し最大 2 / 同一 error_signature 2 回で停滞検出 |
| 5 | Human Judgment Is an Escalation Path — Humans decide when uncertainty or permission gaps emerge | ② 人間承認 / AskUserQuestion 3 択 (承認 / 修正指定 / 中断) / 停滞時の人間エスカレーション |
| 6 | Workflows Are Process Assets — Processes are stored as YAML and shared across teams | 本ハーネスは個人運用なので YAML 化はしていないが、skills/*/SKILL.md を versioned (~/.claude/ が git repo) で個人内 process 資産化 |
| 7 | Traceability Matters — Records enable inspection and continuous improvement | ~/.claude/repos/<repo>/handoff/<task>/ に spec / plan / story / done / review / state.md を保全 |
| 8 | Practical Automation Over Full Autonomy — Systems remain observable and interruptible | ② 人間承認で必ず停止 / 中断時の handoff dir 保全で resume 可能 |
8 原則すべてを忠実に踏襲しているのが核心です。本ハーネスは takt 公式 OSS の「直接コピー」ではないものの、設計思想レベルで完全に整合させる意図で構築しています。
3.3. takt の主要概念 (本連載で扱う 5 つ)
takt README と Faceted Prompting docs から、本連載で扱う takt の主要概念を 5 つ紹介します (takt 公式には他にも Step Types / Loop Monitors / Promotion / Subworkflow 等の概念があり、ここでは本ハーネスの対応に必要な範囲に絞っています)。
(1) Workflow YAML
takt の中核データ構造です。step (= phase) のシーケンスを YAML で宣言的に書きます。
steps:
- name: analyze
persona: planner
edit: false
rules:
- condition: Analysis complete
next: implement
- name: implement
persona: coder
edit: true
pass_previous_response: true
rules:
- condition: Implementation complete
next: review
- name: review
persona: reviewer
edit: false
rules:
- condition: Approved
next: COMPLETE
各 step が persona / policy / knowledge / instruction / output_contracts / edit / rules を持ち、rules の condition (tag / ai("...") / all("...") / any("...")) で次 step への transition を決定します。next は次 step 名か COMPLETE / ABORT。
(2) Faceted Prompting (5 facets)
各 step が持つ 5 つの関心。正典 より verbatim:
| facet | what kind of (takt 公式定義) |
|---|---|
| Persona | Who makes the judgment? — Role definition, expertise |
| Policy | What to uphold? — Prohibitions, quality standards, priorities |
| Instruction | What to do? — Goals, step-specific procedures |
| Knowledge | What to reference? — Domain context, reference materials, API specs |
| Output Contract | How to output? — Output structure, report templates |
設計根拠も verbatim:
"Apply Separation of Concerns — a foundational software engineering principle — to prompt design. Instead of one monolithic prompt per agent, decompose it into independent, reusable files organized by what concern they address. Then compose them declaratively per workflow step."
これが本連載 第 2 章 で扱った 5 関心分離の出自です。本ハーネスは takt 公式の 5 facets を Claude Code の rules/ (Policy) / skills/*/SKILL.md (Instruction) / agents/*.md (Persona) / knowledge/ + repos/<repo>/ (Knowledge) / output-contracts/*.md (Output Contract) にマッピングしています。
(3) Output Contracts
各 step が何を成果物として出すかを template 化したもの。workflow YAML の中で各 step の output_contracts: フィールドで宣言します (field reference は docs/workflows.md §Output Contracts (Report Files))。takt 全体としての位置付けは README で次のように要約されています。
"TAKT enforces phase transitions declaratively as a YAML state machine, formalizes the artifact of each phase with output contracts, and routes deviations back via parallel review and fix loops." (出典: README)
本ハーネスでは output-contracts/*.md (spec / plan / story / done / review) として独立 facet 化しています。これは takt 公式概念のそのままの採用であり、本連載執筆中の旧版で「今回新設」と書いたのは誤りでした (実際は takt 由来)。
(4) Worktree Isolation
"Tasks run in isolated worktrees, and each step leaves logs and reports so the path from task to PR remains traceable." (出典: README "Why TAKT")
各 task は独立 worktree で実行され、main branch を保護する設計です。本ハーネスも autodev SKILL ③ で developer が自前で git worktree add する形で同型を実現しています (第 6 章 6.7 節)。
takt 本体は task 設定上「worktree」という呼称を使い続けていますが、内部実装は実際の git worktree ではなく git clone --shared (独立した .git を持つ軽量クローン) に移行済みです (出典: docs/task-management.md)。一方、本ハーネスの developer / auditor フローは文字通り git worktree add / git worktree remove を実行します。同じ「worktree」という語が指す実装は takt 本体と本ハーネスで異なる、という点は区別しておく価値があります。
(5) Repertoire
"Repertoire packages let you install and share TAKT workflows and facets from GitHub repositories."
GitHub からインストール可能な workflow / facet の再利用パッケージシステム。@owner/repo/facet-name の scoped 記法で参照します。
本ハーネスは個人運用のため Repertoire 形態は採用しておらず、~/.claude/skills/ 配下に直接 facet を置く独自運用です。将来的に teams 共有が必要になれば Repertoire 形式への移行が検討候補になります。
3.4. 本ハーネスでの独自移植 — CLI 不使用、Claude Code 上に再現
本ハーネスは takt CLI を使いません。理由:
- 本ハーネスは Claude Code (= 単一 LLM provider) に特化した個人運用で、takt の multi-provider orchestration は不要
- Claude Code の subagent / skill / hook 機構で takt の思想を再現できる
- 個人の
~/.claude/構造を versioned (private git repo) で管理する方が、takt の workflow YAML + Repertoire を導入するより身軽
代わりに、takt の思想を Claude Code の各機構にマッピングして再現します:
| takt の機構 | 本ハーネスでの代替 |
|---|---|
~/.takt/workflows/*.yaml | ~/.claude/skills/autodev/SKILL.md (orchestrator が ⓪'-⑤ を手順として実行) |
step (name / persona / rules) | subagent spawn (architect / plan-reviewer / developer / auditor) |
rules: condition で transition | VERDICT: PASS|FAIL 出力契約 + main agent の grep '^VERDICT:' 分岐 |
output_contracts: フィールド | output-contracts/*.md (spec / plan / story / done / review) |
edit: true/false 権限 | agents/<name>.md frontmatter tools: でツール制約 (architect / plan-reviewer / auditor は Write を handoff dir のみに制限) |
| Worktree Isolation | autodev SKILL ③ で orchestrator が git worktree add /tmp/<repo>-<task> を手動作成、state.md で worktree_path を pin |
quality_gates: type: command | developer subagent が pass 条件を worktree 内で実行し done.md に証跡記録 |
Repertoire (@owner/repo/...) | 採用せず (個人運用、~/.claude/skills/ 直置き) |
pass_previous_response: true | handoff dir 内の派生物 (plan.md → story.md) を orchestrator が合成して次 subagent に渡す |
~/.takt/personas/ | ~/.claude/agents/*.md body (system prompt) |
本ハーネスの自律開発フロー全体図 (再掲):
ノード横に併記した persona= / edit= は takt の workflow YAML 用語との対応です。本ハーネスは YAML ではなく agents/<name>.md frontmatter で同じ意味の制約を表現しています。
3.5. takt 公式 ⇔ 本ハーネス対応表 (詳細)
各 takt 公式概念に対し、本ハーネスでの具体実装を対応づけた表です。
Faceted Prompting (5 facets)
| takt facet | 本ハーネスの場所 | サイズ上限 | 配信 |
|---|---|---|---|
| Persona | agents/*.md body + CLAUDE.md 冒頭 | ≤40 (gating ≤60) | agent body inline |
| Policy | rules/*.md | ≤30 | paths: なし常時ロード |
| Instruction | skills/*/SKILL.md | ≤80 (autodev ≤100) | trigger word で main agent がロード。subagent へは story.md / spawn prompt への合成・embed経由 |
| Knowledge | knowledge/*.md + ~/.claude/repos/<repo>/ | (上限なし、個別管理) | 索引 + on-demand Read |
| Output Contract | output-contracts/*.md | ≤30 | agent body の ## 出力契約 section が名指し、subagent 自身の Read で参照 |
Workflow (plan → implement → review)
| takt YAML 表現 | 本ハーネスでの autodev step (⓪'-⑤) | 担当 subagent |
|---|---|---|
persona: planner / edit: false | ① architect spawn | agents/architect.md |
persona: reviewer / edit: falserules: Approved → next | ①' plan-reviewer spawn | agents/plan-reviewer.md |
| (takt にはない人間承認 step) | ② human approval (AskUserQuestion 3 択) | main agent |
persona: coder / edit: truepass_previous_response: true | ③ developer spawn (worktree 内) | agents/developer.md |
persona: reviewer / edit: falserequired_permission_mode: readonly | ④ auditor spawn (read-only fresh --bare) | agents/auditor.md |
rules: Approved → COMPLETE | ⑤ ff merge + cleanup | main agent |
Output Contracts
| takt の概念 | 本ハーネスでの実装 (output-contracts/*.md) |
|---|---|
| 各 step が出す report file 形式 | spec.md (受入基準 / SHA 凍結) / plan.md (実装計画 + column 化 doc 更新義務) / story.md (developer 単一入力) / done.md (実行証跡) / review.md (先頭行 VERDICT: PASS|FAIL) |
Worktree Isolation + 関連 step 設定
| takt の挙動 / 設定 | 本ハーネスでの実装 |
|---|---|
| 各 task は isolated worktree で実行 | orchestrator が git worktree add /tmp/<repo>-<task> で手動作成、agents/developer.md で isolation: worktree を使わない設計 (二重 worktree 回避、第 8 章 改修 3) |
allow_git_commit: false (default、step 設定) | 本ハーネスは逆に developer に commit を委ねる代わり、hooks/check-git-commit-gate.sh で commit 暴発を防御 (第 8 章 改修 1) |
3.6. 本ハーネスでの独自部分 (takt 本体にはない筆者整理)
本ハーネスは takt 思想を踏襲しつつ、いくつか独自の規律を上乗せしています。これらは takt 本体にはなく、本ハーネス固有の運用整理です。
| 独自部分 | 内容 | 該当章 |
|---|---|---|
| 5 規律 (成長規律) | usage-driven 追加 / サイズ上限 / 1 ファイル 1 関心 / 逆 ratchet / hooks は実証後 | 第 7 章 |
| 逆 ratchet と反転承認 | 月次 /harness-prune で 30 日参照ゼロ等を検出し「残す理由を問う」 inverted approval | 第 7 章 |
| Computational Sensor (hooks) | takt は CLI で workflow を強制するが、本ハーネスは Claude Code の PreToolUse / Stop / PostToolUse hooks で個別規範を deterministic に強制 (commit gate / 平文質問検出 / Edit 前未 Read 検出等) | 第 5 章 の hooks section |
| 理解ゲート (smi-auto-dev) | autodev 品質ゲートに G1/G2/G3 理解ゲートを上乗せ (学習用フロー) | ~/.claude/skills/smi-auto-dev/SKILL.md |
| per-repo zero-footprint scaffold | チーム repo を一切汚さず ~/.claude/repos/<repo>/ に個人 layer を置く /project-init skill | ~/.claude/skills/project-init/SKILL.md |
| subagent への規範到達設計 | paths: なし常時ロード + 絶対パス明示注入 (Claude Code 固有の context loss 対策) | 第 4 章 4.4 |
3.7. 出典と License 表記
本連載で参照した nrslib/takt の一次ソース:
- nrslib/takt GitHub (MIT License)
- README (語源 / 解決する問題 / CLI 使い方)
- Faceted Prompting (5 facets の正典定義)
- Design Philosophy (8 design principles)
- Workflows (YAML schema)
- Builtin Catalog (builtin workflows / personas)
- Repertoire (再利用パッケージ)
本ハーネスは nrslib/takt の MIT License を尊重し、思想 (5 facets / 8 design principles / Workflow Output Contracts / Worktree Isolation) を採用しています。コードレベルでの依存はなく、Claude Code 上での独自移植 (skills + agents + handoff dir + hooks) として再現しています。
3.8. 本章のまとめ
- takt = nrslib 作の AI Agent Orchestration Framework (CLI, MIT)。語源は「指揮者の baton stroke」(製造業の takt time とは無関係)
- 8 design principles (Agents Are Not Authoritative / Structure Over Prompting / Separation Improves Quality / Feedback Loops / Human Judgment Escalation / Process Assets / Traceability / Practical Automation) を本ハーネスは原則レベルで完全踏襲
- 本連載で扱う 5 つの公式概念 (Workflow YAML / Faceted Prompting / Output Contracts / Worktree Isolation / Repertoire) のうち、本ハーネスは YAML / Repertoire は採用せず、思想だけを Claude Code 上に独自移植
- 対応表で takt → 本ハーネスのマッピングを可視化 (Faceted Prompting → 5 facet ディレクトリ / Workflow step → subagent spawn / Output Contracts → output-contracts/ / Worktree Isolation → autodev SKILL ③)
- 独自部分 (5 規律 / 逆 ratchet / Computational Sensor / 理解ゲート 等) は takt 本体にはない筆者整理として明示
次章では、ここまでで扱った 5 facet + orchestrator (takt 思想) が実際にどんなディレクトリ構成で配置されているかを、ディレクトリ構成の全体像と合成規約 (criticality 3 段) で詳しく扱います。