Faceted Prompting で組み直したハーネス: 数十ファイル規模の運用
この連載が記述する時点
本連載は執筆時点のハーネス実環境 (設定ファイルの内容、実行記録、ファイル数) を素材にした記録です。ハーネス本体は公開後も改修が続いているため、引用したファイル内容や個数、手順は現在の実体と異なる場合があります。本連載の主眼は個々の値ではなく設計の考え方 (5 関心分離、検証ゲート、成長規律) にあります。
本連載は、 ~/.claude/ を Faceted Prompting (5 関心分離) で組み直し、数十ファイル規模で運用しているハーネスの設計・使い方・成長規律・改修サイクルを章別に書き留めるシリーズです。
中心思想は nrslib/takt (AI Agent Orchestration Framework、MIT、nrslib 作) が提唱する Faceted Prompting (5 関心分離) と 8 design principles を Claude Code 上に独自移植したものです。一行で要約すると次のとおりです。
- nrslib/takt の公式概念 Faceted Prompting を採用し、プロンプトを Persona / Policy / Instruction / Knowledge / Output Contract の 5 関心に分離する
- 何をどの facet に置くかは takt の正典定義に揃え、合成は重要度 (criticality) で配信方式を分ける
- takt CLI は使わず、思想だけを Claude Code の
skills/+agents/+~/.claude/repos/<repo>/handoff/+hooks/に独自移植する (orchestrator = main agent が takt の Workflow 実行体に相当)
想定読者
- Claude Code を自分の用途で日常的に走らせている、または走らせ始めたい方
- ハーネスを 1 ファイル足すたびに膨張させた経験があり、削除の引力をつけたい方
Agent = Model + Harness/ Guides × Sensors / 4 Quality metrics 等の概念は本連載中で必要に応じて触れますので、初出の方も本連載単体で読み進められる構成にしています。
連載構成
| 章 | テーマ | 概要 |
|---|---|---|
| 01. なぜゼロから組み直したのか | 動機 | 再構築前のハーネスで観測した 4 つの症状と、ゼロ再構築を選んだ判断 |
| 02. Faceted Prompting: 5 関心分離 | 思想 | Persona / Policy / Instruction / Knowledge / Output Contract の境界と振り分けルート |
| 03. takt 思想の採用: nrslib/takt から Claude Code への移植 | 駆動原理 | nrslib/takt の 8 design principles + 5 公式概念 (Workflow / Faceted Prompting / Output Contracts / Worktree Isolation / Repertoire) と本ハーネスでの対応表 |
| 04. ディレクトリ構成と合成規約 | 構造 | ディレクトリ構成の全容と、criticality で配信方式を分ける合成規約 |
| 05. facet 詳解 (rules / skills / agents / hooks / output-contracts) | 各層 | 各 facet の役割と代表例を、責務と境界を実コード引用付きで解説 |
| 06. autodev フローの実走 | 使い方の核 | spec → plan → 人間承認 → developer → auditor の検証ゲートループを実走 transcript 付きで walkthrough |
| 07. 成長規律と逆 ratchet | 規律 | 入口に摩擦・出口に引力をつける 5 規律、反転承認による削除 default 化 |
| 08. 改修サイクルの実例 | 運用知 | bootstrap 後に表面化した silent drop / 二重 worktree / 文言ズレの実例を問題発見 → 分析 → 修正 → 検証で walkthrough |
| 09. まとめと残課題 | 総括 | 3 段要約 / 4 Quality metrics の現状 / これからの道筋 |
読み進め方
- 使い方から知りたい場合: 03 (takt) → 06 (autodev フロー) → 08 (改修サイクル) の順
- 設計判断から知りたい場合: 01 (動機) → 02 (Faceted Prompting) → 04 (ディレクトリ) → 07 (成長規律)
- 特定 facet の実体を知りたい場合: 05 (facet 詳解) を辞書的に参照
この連載で重視している点
- 実例優先: 概念だけで終わらせず、autodev-smoke (scratch repo) で実走した spec / plan / story / done / review の実物、hook 実コード、改修 commit の diff を本文に引用しています
- 思想の出自を明示: Faceted Prompting / Output Contracts / Worktree Isolation / 8 design principles はいずれも nrslib/takt の公式概念を採用しています。本ハーネス独自部分 (5 規律 / 逆 ratchet / Computational Sensor hooks / 理解ゲート 等) は takt 本体には無い筆者整理として明示区別します
- 業界共通標準ではない: 本連載の中身は takt 思想を Claude Code 上に独自移植した筆者個人の運用です (takt CLI は使用していません)。再現性を期待する記事というより、ハーネスエンジニアリングを実際に走らせるとどんな姿になり得るかの一例として参照してください
それでは、まずなぜゼロから組み直したのかから始めます。