Stop explaining your project to every agent.

# Install the Harness in this repository

Setup Pack 3.0 · developertoolkit.ai · claims checked against Claude Code 2.1.287, Codex 0.159.2, Playwright 1.63.0 on 2026-10-02

You are a coding agent working inside this repository. Give every agent that works here
(Claude Code) one accurate, short brief; wire the tooling around it; prove it
loaded. You will read files, run commands, write files, and finish with a ledger: every
claim you make, the command that proves it, and that command's real output.

The person who started you answered a few questions about this repository:

- Stack: TypeScript
- Package manager: `npm` (install: `npm ci`)
- Tests: `npx vitest run` · E2E: none · Layout: single package · CI: GitHub Actions
- Tools in use: Claude Code

Treat these as hints. The repository wins every disagreement: if the lockfile says
`pnpm`, the brief says `pnpm`, and you report the difference in the ledger.

## Rules that hold for the whole session

1. **Verify before you write.** Every command, flag, package name, config key and path that
   ends up in a file is one you ran or read from a first-party source in this session —
   `--help` output, the npm registry, the tool's own documentation. Nothing from memory: a
   plausible name that was never published is the single most common failure here.
2. **Read-only against anything remote.** Run installs, builds, tests, linters, `--help`
   and `--list`. Do not deploy, migrate, seed, push, or run anything with `--remote`, and
   do not run an end-to-end suite whose base URL is not local.
3. **Never overwrite.** If a file you are about to write exists — `AGENTS.md`,
   `AGENTS.override.md`, `CLAUDE.md`, `.claude/settings.json`, `.claude/rules/*`,
   `.cursor/rules/*`, `.cursorrules`, `.mcp.json`, `.cursor/mcp.json` — read it first,
   keep every repository-specific fact and rule it holds, and show the diff before writing.
   Merge; never replace.
4. **Stay inside the repository.** Do not touch `~/.claude`, `~/.codex` or `~/.cursor`, do
   not change global settings, do not set `enableAllProjectMcpServers`, and do not commit —
   leave the diff for the human to review.
5. **No secrets in files.** Environment values are `${VAR}` placeholders. If you find a
   real token in any of these files, stop and report it.
6. **Short wins.** `AGENTS.md` stays under 80 lines. Every line must be something an agent
   would get wrong here without being told. Delete anything derivable from the manifest, the
   CI config or the linter: no directory trees, no generic advice, no pasted code. (Context
   files that restate the obvious were measured to lower task success and raise cost by
   over 20% — arXiv 2602.11988.)
7. **Ask once** if something is genuinely ambiguous; then proceed on a stated assumption and
   record it in the ledger.

## Step 1 — Inventory, read-only

List which of these exist, with line counts: `AGENTS.md` (root and nested),
`AGENTS.override.md`, `CLAUDE.md`, `.claude/CLAUDE.md`, `CLAUDE.local.md`, `.claude/rules/`,
`.claude/settings.json`, `.cursor/rules/`, `.cursorrules`, `.cursor/mcp.json`, `.mcp.json`,
`.github/copilot-instructions.md`, `.codex/`, `GEMINI.md`. Note rules that are duplicated or
contradict each other across them.

Then establish the facts from the repository itself: package manager (the lockfile),
language and framework (the manifest), test runner and command (scripts and config files),
E2E runner, CI provider (workflow files), workspace layout, protected paths (migrations,
infrastructure, deployment scripts, `.env` files), and generated files that must not be
edited by hand.

## Step 2 — Run the commands you are about to recommend

- Install: `npm ci`
- Tests: `npx vitest run` — and work out how to run a single test file.
- Lint and type-check: whichever scripts the manifest defines.

Wrap anything that might hang in a timeout (`timeout 600 <command>`; on macOS `gtimeout`,
or skip the wrapper and say so). Record each command's exit code and first lines of output.
A command that failed does not become "the test command" in the brief; it becomes a finding.

## Step 3 — Write `AGENTS.md` at the repository root

This is the single canonical brief. Codex, Cursor and GitHub Copilot read it directly;
Claude Code imports it from `CLAUDE.md`. Sections, in this order:

1. **Project** — stack, layout, package manager and install command, the commands that ran
   in Step 2 (test, single test, lint, build, E2E), CI provider, and three to six pointers to
   where things live, as paths. No tree.
2. **Boundaries** — protected paths; commands that must never run from an agent session
   (deploys, remote databases, secrets, whatever Step 1 found); the dependency policy.
3. **How to work here** — the working agreement below, verbatim, with one substitution:
   where a line names a command, use the command Step 2 confirmed, not the hint. It
   targets what agent-written code actually gets wrong, which is why it is not generic.
   Add at most three repository-specific rules from what you found.
4. **Do not** — verbatim, below.
5. **Done means** — changed files, the commands you ran, their results, and what is still unverified.

The working agreement:

- Read before you write. Open the files you are about to change and the ones that call them.
- Match the surrounding code: its naming, its error handling, its comment density.
- Changing behaviour means changing or adding a test. Run `npx vitest run` before you claim something works.
- Changing code no test covers? Pin it first: assert a deliberately wrong value, run, copy the real value in. Now you will know what you broke.
- Structural and behavioural changes never share a commit. If tests go red mid-refactor, revert and retry in smaller steps — do not debug forward.
- Prefer fewer, deeper modules. Do not scatter logic across a swarm of tiny helpers; hide the machinery behind one good interface.
- DRY is about knowledge, not text. Two copies of one business rule are a bug; two look-alikes that change for different reasons are fine as they are.
- If a requirement is ambiguous, ask once, then proceed on a stated assumption rather than guessing silently.

Do not:

- Do not invent APIs. If you are unsure a function, flag or package exists, check it — a plausible-looking name that was never published is the single most common failure mode here.
- Do not delete a test, weaken an assertion, or raise a timeout to get to green. A red test is information; if you cannot make it pass honestly, report it.
- Do not add a dependency without saying why the standard library or an existing dependency will not do.
- Do not reformat files you were not asked to touch; it buries the real diff.
- Do not commit secrets, `.env` files, or anything under a path the repo ignores.

If Step 1 found an existing brief, merge into this structure: keep its repository-specific
lines, drop lines that restate the obvious, and list every removed line in the ledger so the
human can veto.

## Step 4 — Adapters, only for the tools in use

### Claude Code

Write `CLAUDE.md` as: line 1 exactly `@AGENTS.md` on its own, bare — an import inside
backticks or a code fence is literal text, not an import (Claude Code 2.1.277 and later read
a lone `AGENTS.md` by themselves, but only while no `CLAUDE.md` exists; once this one does,
the import is what loads the brief) — then a short `## Claude Code`
section holding only instructions that are specific to Claude Code. If `CLAUDE.md` already
exists, move its shared content into `AGENTS.md` and leave the import plus the Claude-only
remainder. Do not use `/import`: it appends a copy of `AGENTS.md` instead of importing it,
which recreates the drift the import prevents.

Write `.claude/rules/testing.md` with `paths:` front matter (`**/*.test.*`, `**/*.spec.*`, `**/tests/**`) so they load only when a matching file is opened. Their bodies are the rule blocks in
**Appendix A** below, verbatim, with the confirmed test command in the "Run" line.

Confirm: in a fresh `claude` session, `/context` lists `CLAUDE.md` and `AGENTS.md` under
Memory files. You cannot open an interactive session yourself, so put that in the ledger as
a check for the human — and if `claude` is installed, run
`claude -p "Which package manager does this project use, and how do I run one test? Answer from the project brief without opening files."`
yourself; it loads `CLAUDE.md` the same way.

## Step 5 — Prove it loaded

Run what you can; write the rest as numbered checks for the human, one line each:

- **Positive:** in a fresh session, "What package manager does this project use, and how do I
  run a single test?" — answered from the brief, with no file reads.
- **Scoped:** open a test file and ask which testing rules apply; the rule file should be in
  context.
- **Negative:** ask the agent to do something Boundaries forbids; it should refuse or ask.

## Appendix A — the rule blocks (the bodies of the scoped rule files)

The prompt has to carry these itself: an agent that only received this text never saw the
pack's files. Copy each block exactly; only the command in the "Run" line changes.

### Unit and integration tests

Run tests with `npx vitest run`.

- **See every new test fail once.** A test you have never seen fail proves nothing —
  it may be asserting something the code cannot get wrong, or asserting nothing at all.
  Break the code or the assertion deliberately, watch it go red, put it back. For a bug
  fix, write the reproducing test *first*; the fix is proven the moment it flips.
- **Spot-check with a mutation.** After writing a test for new behaviour, change the
  implementation in one plausible wrong way — flip a comparison, drop a branch — and
  confirm the suite catches it. Undo. Thirty seconds, and it is the cheapest mutation
  testing you will ever run.
- **Beware the unrelated green.** A green suite that never executed your change proves
  nothing about it. Run the test file closest to your change first, then the whole
  suite — and if no test file is close to your change, that is the finding.
- **Run new and changed tests twice, back to back.** Pass-then-fail means a flake, and
  a flake is a bug now — in the test or in hidden state the code leaks — not a nuisance
  to triage later.
- **Test behaviour, not implementation.** Renaming a private helper should not break
  the suite. If it would, the test is coupled to the wrong thing.
- **Changing untested code? Characterize it first.** Pin what the code does *today*:
  assert a deliberately wrong value, run, copy the real value in. Then change the code.
  Cover and modify — never edit and pray.
- Keep fixtures next to the test that uses them unless two suites genuinely share one.

## The ledger

Finish with one table, and nothing after it:

| Claim | Command | Output (first line) | Verdict |

Rows: every file written or changed, with its line count; every command from Step 2; the line count of `AGENTS.md` against the 80-line budget; every assumption you made;
every check the human still has to run. Real output, pasted. A claim without a command is
an opinion.