Rebuilt with Faceted Prompting: running at dozens-of-files scale
This series is a record based on the harness environment as it existed at the time of writing (file contents, run logs, file counts). The harness has kept evolving since this series was written, so quoted file contents, counts, and procedures may differ from the current state. The focus of this series is the design ideas (five-facet separation, verification gates, growth discipline) rather than the specific values.
This series is a chapter-by-chapter record of the design, usage, growth discipline, and iteration cycles of a harness in which ~/.claude/ was rebuilt with Faceted Prompting (5-concern separation) and now runs at a dozens-of-files scale.
The core philosophy is adopted from nrslib/takt (AI Agent Orchestration Framework, MIT, by nrslib) — its Faceted Prompting (5-concern separation) and 8 design principles — ported independently onto Claude Code. To summarize in one line:
- Adopt takt's official concept Faceted Prompting and split prompts into 5 concerns: Persona / Policy / Instruction / Knowledge / Output Contract
- Align what goes in which facet with takt's canonical definitions; split delivery channels by criticality
- Do not use the takt CLI; port the philosophy to Claude Code's
skills/+agents/+~/.claude/repos/<repo>/handoff/+hooks/(the orchestrator = main agent corresponds to takt's Workflow runner)
Intended audience
- Anyone running Claude Code for their own use daily, or starting to
- Anyone who has experienced harness bloat from adding one file at a time and wants to add a pull toward deletion
- Concepts like
Agent = Model + Harness/ the Guides × Sensors cross / the 4 Quality metrics are touched on within this series as needed, so first-time readers can read this series on its own.
Series structure
| Chapter | Theme | Overview |
|---|---|---|
| 01. Why I rebuilt from scratch | Motivation | Four symptoms observed in the pre-rebuild harness, and the decision to rebuild from zero |
| 02. Faceted Prompting: 5-concern separation | Philosophy | Boundaries and routing rules for Persona / Policy / Instruction / Knowledge / Output Contract |
| 03. Adopting takt's philosophy: porting nrslib/takt to Claude Code | Drive principle | nrslib/takt's 8 design principles + 5 official concepts (Workflow / Faceted Prompting / Output Contracts / Worktree Isolation / Repertoire) and the side-by-side mapping table |
| 04. Directory structure and composition rules | Structure | The full directory layout, and the criticality-driven composition rule that splits delivery method |
| 05. Facet deep-dive (rules / skills / agents / hooks / output-contracts) | Each layer | Each facet's role and representative examples, with real-code excerpts, plus responsibilities and boundaries |
| 06. Walking the autodev flow | Usage core | Spec → plan → human approval → developer → auditor verification-gate loop, walked through with a real run transcript |
| 07. Growth discipline and reverse ratchet | Discipline | The 5 disciplines that make the entrance frictional and the exit attractive, with deletion as default via inverted approval |
| 08. Real iteration cycles | Operational wisdom | Post-bootstrap issues (silent drop / doubled worktrees / wording drift) walked through as problem → analysis → fix → verification |
| 09. Summary and open work | Wrap-up | Three-tier summary / state of the 4 Quality metrics / road ahead |
How to read
- If you want to know the usage first: read 03 (takt) → 06 (autodev flow) → 08 (iteration cycles) in that order
- If you want to understand the design choices: read 01 (motivation) → 02 (Faceted Prompting) → 04 (directory) → 07 (growth discipline)
- If you want a quick reference to a specific facet: use 05 (facet deep-dive) as a dictionary
- Examples first: instead of stopping at concepts, the body of each chapter quotes the actual spec / plan / story / done / review files from a real autodev-smoke run, hook source code, and commit diffs from the iteration cycles
- Origins are called out explicitly: Faceted Prompting / Output Contracts / Worktree Isolation / 8 design principles are all adopted from nrslib/takt's official concepts. The author's own additions (5 disciplines / reverse ratchet / Computational Sensor hooks / understanding gates etc.) — which are not in takt itself — are marked distinctly throughout
- Not an industry standard: this series documents an independent port of takt's philosophy onto Claude Code as the author's personal setup (the takt CLI is not used). Read it less as a recipe for reproduction and more as one example of what harness engineering can look like when actually run
With that, let's start from Why I rebuilt from scratch.