The-Ideal-Harness: Instructions file for Claude Code

AGENTS.md

Instructions for AI coding agents contributing to The Ideal Harness, and for the humans operating them.

If you are a human, read CONTRIBUTING.md instead — it covers the same ground for people. This file exists because a growing share of contributions arrive via Claude Code, Cursor, Codex, Aider and similar, and an agent that hasn't been told this project's constraints will confidently violate all of them.

---

Read this before you write code

This repo is an enforcement floor that runs below other people's models, in production. A defect here is not a broken feature — it is a security incident on someone else's machine. Hold yourself to a higher bar than you would on an ordinary codebase.

Four constraints are non-negotiable. They are checked in review and a PR that breaks one will be rejected regardless of how good the rest is.

1. Enforce below the model

Any safety or scope rule must be deterministic code — a hook, a gate, a scanner. Never a sentence in a prompt asking a model to behave.

If your instinct is "add an instruction telling the agent not to do X," stop. That is the exact pattern this project exists to replace. The rule belongs in guard as code that runs whether the model cooperates or not.

2. Zero overlap

Each capability has exactly one home. Before adding anything, check DESIGN.md §6 and decisions.md. If a capability already exists, extend it. Do not add a second mechanism that does the same thing differently — that is how a codebase becomes four competing notions of "state."

3. Clean-room

Lift ideas, not code. If you have seen a good implementation elsewhere, implement the algorithm fresh with your own tests. Do not vendor, do not copy files, do not paste from another project. This applies to code you may have memorised from training data as much as to code you fetch during a session — if you are reproducing a specific implementation rather than solving the problem, stop.

4. Honest by construction