claude-code-harness

Claude Code Harness

Designs, bootstraps, audits, and extends the harness around Claude Code — the .claude/ directory and root CLAUDE.md that turn a fresh repository into a high-leverage agentic workspace. Opinionated, and the opinion is one line:

Under a capable model, less harness yields more productivity. Find the simplest setup that works; add a component only when a simpler approach demonstrably underperforms. If a component encodes "the model can't do X" and the model already does X natively, it should not exist. (Model-agnostic principle — don't re-pin it to a version; evidence in references/evidence-base.md.)

When to use

• A project has no .claude/ and wants its harness now → Bootstrap (production-grade default; minimal on explicit request).
• A project has a .claude/ that has accumulated cruft (custom orchestrator subagent, multi-stage pipeline, 500-line CLAUDE.md, mid-thought blocking hooks, prescriptive stack presets, stale model-version pins, duplicate skills) → Audit.
• About to add a hook/skill/subagent/command and want to confirm a built-in doesn't already cover it → Extend.
• Someone asks how Claude Code differs from generic agentic frameworks, or when to use a dynamic workflow → Explain.

Do NOT use when: the operator's own harness already encodes this discipline (this skill is transmittable knowledge, not a self-description for a mature setup); the question is about building a harness inside another framework (OpenAI/Codex/MCP-without-Claude) → point to references/evidence-base.md external sources — an external CLI attached to this harness via MCP is in scope, not an exclusion (references/codex-peer-skill.md); the question is general programming/debugging.

The four modes

Mode 1: Bootstrap (empty .claude/)

Read references/bootstrap-checklist.md. Two things decide the shape before anything else. (1) Does the repo already have AGENTS.md or another agent's rule files? Then CLAUDE.md is a bridge (@AGENTS.md import or symlink), never a paraphrase — Claude Code does not read AGENTS.md, measured. (2) /init with CLAUDE_CODE_NEW_INIT=1 now does interactive discovery, subagent exploration and a reviewable proposal — use it for the draft instead of hand-rolling the same walk, and spend the run on what it does not do: the permission model, the shipped distillation, and cutting the draft down to what cannot be derived from the repo. Run claude --version first (the built-in subagent types you must not recreate are catalogued in references/native-capabilities.md; /agents no longer opens a wizard — inspect configured agents via /context ("Custom Agents") or .claude/agents/ directly; the CLI claude agents lists running background sessions, not types). Default shape is production-grade regardless of project size — which means conventions + documents, not machinery, so it does not contradict the headline principle: root CLAUDE.md ≤ 200 lines + settings.json with sane permissions + the shipped workflow distillation .claude/docs/{workflow,testing,docs-discipline}.md (Phase 2c, verbatim copies from references/project-docs/) + docs/ARCHITECTURE.md as a decision record (no module map, no CODE-MAP.md — the code carries those, and a boundary test pins them where the project has one)

• .claude/rules/ for the domain prohibitions no type or test can express, where the repo actually has any. No custom subagents, hooks, or skills until justified; minimal MVH only on explicit operator request. Greenfield (0 files, 0 commits) is a valid detected state, not a reason to stall: an explicit request for the full harness on an empty repo is informed consent — deploy it with honestly-labelled stubs (never invented facts) whose marker names its own fill trigger. Close every bootstrap by recording it (Phase 8: the run writes its own first episodic entry, in whatever carrier the project's continuity duty names — the layer starts live instead of as a convention nobody has exercised). Then stop.