Principles

The “golden principles”: opinionated, mechanical rules that keep an agent-generated codebase readable and coherent for the next agent run. Taste, encoded once, applied to every line.

The Mini constraint

What keeps harness-mini mini— every addition must clear a high bar, or it doesn't go in:

• Shell-or-doc first. Prefer a Markdown convention or a few lines of POSIX shell over a program. The harness is the environment, not an app to run.
• No environment dependence. No build step, no runtime, no services to stand up — it works wherever a shell does.
• No complex languages. Glue stays thin and readable; nothing that needs a toolchain just to execute.
• Delete before you add. The default answer to “add this?” is no — subtract until what remains is load-bearing.

That is the whole method: question the requirement, then try to delete it before adding code. The harness keeps that discipline plain — no named algorithm and no mandatory intake gate.

Golden principles (mechanical, enforce-able)

1. The repo is the system of record.If knowledge isn't in a version-controlled file, it doesn't exist to the agent. Push context into the repo (decisions, conventions, the “why”).
2. A map, not a 1,000-page manual. AGENTS.md is a table of contents. Progressive disclosure beats a wall of instructions every time.
3. Optimize for agent readability. The next reader is an agent with no memory. Make the repo navigable cold.
4. Constrain boundaries, free the interior. Enforce invariants (layers, schemas, naming) mechanically; allow freedom in how a solution is expressed inside those boundaries.
5. Type the boundary; never guess the shape. Depend on a typed SDK/client — acquire types from the source. Where no typed SDK exists, parse and validate at the seam; nothing downstream may build on a guessed or untyped structure.
6. Prefer shared utilities over hand-rolled helpers, so invariants live in one place.
7. Pay technical debt in small, continuous installments — the garbage collector (garden), not a once-a-quarter cleanup.
8. Correct, maintainable, readable beats stylistically human. Agent-written code need not match human style; it must be right and clear for the next run.
9. Spend emphasis from a budget.Emphasis is signal only when it's rare. Reserve ALL-CAPS for a small set of load-bearing imperatives — MUST / NEVER / ALWAYS — on safety- or invariant-critical lines; default to bold + structure everywhere else. If every line shouts, nothing does.

Question stale assumptions (the harness is not the model)

Almost every mechanism here is a patch for a presumed model gap — the 40% line, the anti-self-praise eval firewall, the explorer fan-out, progressive disclosure, caps-for-emphasis (#9), the status ready: verdict (A6), and the plan-stage write ban (A7). Each was true when written; each may quietly stop being true as models improve. So harness-mini holds them as hypotheses, not law.

• Register the assumption. Every load-bearing constraint is logged in docs/assumptions.md with the model-gap it patches and a concrete test if stale — an experiment read off harness.sh report.
• Re-test on a trigger, don't trust forever. The garden sweep audits the register pre-release and whenever the builder model tier moves. A constraint that no longer earns its keep is deleted— the Mini constraint's delete-first discipline applied to the harness's own beliefs, not just its features.

Distilled from Anthropic's Scaling managed agents: a harness encodes assumptions about what the model can't do on its own, and those assumptions go stale as models improve.

Clean Code & Refactoring (the quality spine)

• clean-code is the forward constraint (write it right the first time): intention-revealing names, small single-responsibility functions, no duplication, comments that explain why not what.
• refactor is the recovery constraint (smell → named refactoring, always under green tests): never refactor on red; one named move at a time.

Together they are principle #7 in action — taste applied to every line, every run, so entropy never compounds.