Nothing is obvious to an agent until it's in the file

Behavior your team considers self-evident does not exist for the agent until someone writes it down. In one factorial study of Claude Code sessions, the baseline cells with no instruction file never once produced a specific local convention on their own — zero times, across 1,669 function-level observations. That's one narrow, mechanically-checked convention, not a general claim that agents do nothing without files. What's local and unguessable stays undone until someone writes it down.

What does get written down is executed reliably — that same factorial study found instructions, once present, followed with high fidelity. That's the power of the mechanism, and also its risk: an agent executes a useless instruction exactly as faithfully as an essential one, and nothing about presence tells it which is which. Presence isn't free either: a separate controlled study — one benchmark family (SWE-bench-style Python issue resolution), a preprint, not peer-reviewed — found cost rose 20–23% in every condition where a file existed, generated or developer-written, regardless of whether it changed the outcome.

There's one condition where that cost reliably buys something back: a repository with no other documentation. Restricted to that subgroup — the only place the strongest study found a clean, verified win — a generated file improved outcomes by 2.7% on average and beat developer-written files at the same task. That's the new, empty project, which is where every project starts.

Put those three findings together and a specific, checkable design falls out of them:

Only the underivable. Local conventions, prohibitions, paths that aren't visible in the code and can't be inferred from it — never a retelling of what a repository already shows.
Concrete, checkable instructions, not survey prose. Instructions get followed; a generated repository overview demonstrably doesn't speed up finding the right file.
High-cost rules go in a git-tracked mechanical gate, not a paragraph. A hook-checked rule doesn't decay as a session runs long and exists automatically in every fresh clone — a prose rule has to be re-read and re-obeyed every time. Our own manually-installed version of this sat uninstalled, unnoticed, for 13 days.
A per-task operational journal — a Tasks/ folder with a running log. Cheap, matches how any competent project gets managed regardless of who's running it, and the closest adjacent agent-memory research finds written progress tracking moves outcomes, even though none of it measures this exact practice directly.
A place lessons graduate to. LESSONS.md and DECISIONS.md hold the small, deliberately promoted subset of what the journal accumulates — not the whole journal.
A review before calling anything done, capped at two revise cycles. Left unforced, this happens in a minority of a team's own work. The template makes it a requirement, not a habit to hope forms on its own.
The file has to lose weight as routinely as it gains it. Nothing in a repository prunes itself — left alone, real instruction files grow almost only by addition: a median of 57 words added against fewer than 15 deleted per commit, once no one is actively pruning.

What our own history added to the outside evidence

The outside studies describe the field in general. About 200 of our own task folders — 23 days of one research-lab PMO running its own work — show what held up under its own weight and what turned out to be ceremony.

The running log held up cleanly: present in 81% of every folder we looked at, and that number doesn't move no matter how you slice the population — the one figure in the whole review that's insensitive to which subset of the work you're measuring.

The installation mechanism told its own story. A manually-installed pre-commit hook needs someone to remember to run a copy command into .git/hooks/. Ours sat inert for 13 days after the repository was bootstrapped — nobody noticed, because nothing failed loudly, the hook simply wasn't there, silently. A git-tracked hook is live the moment anyone clones the repository or creates a worktree; there's no step to forget.

The sharpest lesson came from checking our own headline number. Our first pass at this research claimed 83% of task folders carried an independent-review artifact before merge — a strong, near-universal figure. It was wrong for the population we actually meant to describe. Of 198 folders, 146 belong to this same PMO's own cross-repo review queue for other teams' work — a different job entirely from one developer's own substantive output. Restricted to that narrower, honest population: 20 of 52 folders, about 38%. Real, and worth requiring — but not the number the first pass reported. An independent review caught the gap before publication, the same review discipline this template asks a project to require of itself.

A definition, before the template itself

We use "harness" more narrowly than common usage. Industry shorthand often folds instructions, tools, memory, and the control loop that drives the model turn-by-turn into one word — people say "Claude Code is a harness." We split that: the harness is the equipment layer wrapped around an engine — instructions, tools and skills, the memory and knowledge base it draws on, the gates that keep it honest. The engine — the loop that actually drives the model — is a separate thing we don't build. What follows is about the equipment layer: the instructions file and the minimal scaffolding around it.

The template: two variants, one shared core

The template's public home is agent-harness-registry: templates/base-project-template/ for both variants, the shared fragments, and the drift-checking render script, plus a longer research write-up at deep-dives/components/instructions-rules/base-project-template/ in the same repo (workain/agent-lab-manager PR #217 is the private working history behind it). It ships as with-git/ and without-git/. A project that already is, or will become, a git repository gets a mechanical branch-protection gate, live from the first clone. A plain folder or an undecided prototype gets no gate — a gate that can't see a repository would give false confidence just by existing — and an honest prose substitute instead: back up before risky changes, lean on the review policy. The two variants share everything except the one section where git-assumption content differs, composed from common fragments by a render script that fails loudly on drift — one short CLAUDE.md per project, not two files independently maintained and slowly diverging.

We tested the gate directly rather than trusting the config. A fresh Claude Code session, rooted at a scratch project with no commits yet (the exact edge case a naive branch check gets wrong), was told to commit straight to master. It was blocked, with the message BLOCKED: direct commit to main/master. Create a feature branch first. The same session then built a small CLI through the template's own discipline end to end: two Tasks/ folders with running logs, a passing test suite by the end, and entries written into LESSONS.md, including one about the gate itself after it got denied for chaining a branch switch and a commit in one command. A second, separately instructed session ran the without-git/ path and caught a real bug in the template's own instructions: the backup guidance arrived after the first destructive edit, not before it. We fixed the ordering because a live run found the problem, not because rereading the design document would have.

The gate only activates for a session launched with the templated directory as its actual project root. A session that's already running and just changes into the directory doesn't pick it up, confirmed the hard way: our own pre-existing session committed straight to an unborn master with no interference at all, before we tested a freshly launched one against the same repository. That's how the runtime resolves hooks, and it changes what "the gate protects you" means in practice.

A growth ladder, not a ceiling

Everything above argues for shipping thin. The other half of that argument is naming, concretely, when a project should deliberately outgrow the minimum — "keep it thin" is a starting point with stated exits, not a ceiling. Three axes, each with a trigger condition and what to add:

Axis	Trigger	What you add
Heavy / critical code	A change's blast radius becomes real — production paths, security-sensitive code, anything expensive to get wrong.	Extend the gate's hook array with a tests-before-merge check; the array is built to take more entries, not a new mechanism.
Complex processes	One process concern — a recurring cadence, an audit rhythm — generates enough separate, frequently-revised content that folding it into one etiquette paragraph would bloat that paragraph itself.	Split that one topic into its own process doc, keyed to which concern actually shows citation/revision traffic, not all of them speculatively at once.
Orchestration / multi-agent	A recurring task shape emerges that benefits from a distinct voice — an independent reviewer role, a research role, a scoped-tool specialist — not just "it would be nice to have an agent for this."	Populate the already-scaffolded `.claude/agents/` with real subagent roles.

A second Axis-3 trigger: the first time an agent reaches for a plausible-but-wrong tool, or hits a non-obvious quirk of your specific substrate. That's when .claude/environment/, the template's one deliberately novel slot, gets its first module. It ships empty by design — two teams in our own fleet independently built the identical fix for this exact failure shape, weeks apart, with no coordination between them. That's evidence the slot is worth having. It says nothing about whether pre-populating it with someone else's substrate facts would transfer to yours.

What this doesn't prove

Presence and outcome are not the same claim. The one controlled study that actually removed instruction files and compared against a baseline found that having a file — generated or developer-written — does not reliably move task-success rate on its own; only the no-other-documentation subgroup showed a clean win, which is exactly the third finding in this post's opening. A different study found instructions, once present, get executed with high compliance. Those are two different constructs — behavior versus outcome — and conflating them would be a mistake a careful reader could catch us on.

The operational-journal recommendation rests on adjacent evidence, not direct proof. The closest true with/without-memory ablations in the literature — Reflexion (arXiv:2303.11366), ReasoningBank (arXiv:2509.25140), SWE-MeM (arXiv:2606.28434) — measure an agent's own machine-authored notes across the same task retried, or across many short, repetitive episodes within one benchmark suite, not a human-readable project journal spanning unrelated work over days. Those ablations are real and the deltas are large, but they're evidence for a different mechanism than the one this template ships. We adopted the running log because it's cheap and matches how any competent project gets run regardless of who's doing the work, not because a benchmark measured this exact practice — and the one benchmark aimed at multi-session memory (arXiv:2602.16313) found flat, unstructured context beats a more elaborate memory system, which argues for keeping the log plain rather than building tooling around it. A candid counter-anecdote exists too: a real, closed GitHub issue (anthropics/claude-code#51735) where an agent acknowledged a documented rule and still repeated the violation 25 days later. A written record doesn't guarantee the behavior it describes.

What's proven live, not just designed: the with-git branch gate on a fresh session's actual first commit; the Tasks/ discipline followed unprompted across two independent sessions with running logs; the memory-promotion files populated with entries that came directly out of friction the dogfood runs produced. Verified during design but not re-run live: the with-git variant's warning when copied into a folder that isn't a git repository yet. Not tested at all: multi-contributor use, long-running project drift, any agent engine other than Claude Code (the AGENTS.md symlink exists; nothing has read through it yet), and whether without-git discipline holds up past one session.

This also isn't a new category. Assembled, fill-in-the-blanks harness templates already exist — gtm-starter-kit and shinpr/ai-coding-project-boilerplate are real, maintained, single-vertical instances, and one engine-agnostic scaffolding generator exists too. What we didn't find anywhere is a general-purpose, evidence-derived default with a named growth path and a two-variant git/no-git split, distributed as a copy-in-place template rather than a portfolio piece.

What's next

None of this is built yet. A per-vertical specialized variant, once real demand for one shows up. The distribution story is only partly solved: the registry import above gives a copy-from-a-public-repo path instead of a private branch, but there's still no installable entry point: no npx create-..., no package-registry entry, no command that scaffolds a variant directly. Integration with our own harness-assembler tooling, with .claude/environment/ as the likely slot for assembler-composed modules. Eval hooks wired into the same gate array, once a project's stakes justify an automated check suite. And the still-open question of how a promoted LESSONS.md entry eventually becomes a knowledge/ entry — a gap inherited from our own fleet's larger version of the same problem, unsolved there too.

References

McMillan, D. "Instruction Adherence in Coding Agent Configuration Files: A Factorial Study of Four File-Structure Variables." arXiv:2605.10039. arxiv.org/abs/2605.10039
Gloaguen, T., Mündler, N., Müller, M., Raychev, V., Vechev, M. "Evaluating AGENTS.md: Are Repository-Level Context Files Helpful for Coding Agents?" arXiv:2602.11988. arxiv.org/abs/2602.11988
Chatlatanagulchai, W. et al. "Agent READMEs: An Empirical Study of Context Files for Agentic Coding." arXiv:2511.12884. arxiv.org/abs/2511.12884
Shinn, N., Cassano, F., Berman, E., Gopinath, A., Narasimhan, K., Yao, S. "Reflexion: Language Agents with Verbal Reinforcement Learning." arXiv:2303.11366. arxiv.org/abs/2303.11366
Ouyang, S. et al. "ReasoningBank: Scaling Agent Self-Evolving with Reasoning Memory." arXiv:2509.25140. arxiv.org/abs/2509.25140
Gao, S., Zeng, W., Yu, Z., Wangni, J., Wang, C., Cai, K., He, S., Lyu, M. R. "SWE-MeM: Learning Adaptive Memory Management for Long-Horizon Coding Agents." arXiv:2606.28434. arxiv.org/abs/2606.28434
He, Z. et al. "MemoryArena: Benchmarking Agent Memory in Interdependent Multi-Session Agentic Tasks." arXiv:2602.16313. arxiv.org/abs/2602.16313
Anthropic. "Claude Code best practices." anthropic.com/engineering/claude-code-best-practices
Anthropic. Claude Code memory documentation. code.claude.com/docs/en/memory
Cursor. Rules documentation. cursor.com/docs/context/rules
GitHub. "Adding repository custom instructions for GitHub Copilot." docs.github.com/copilot/customizing-copilot/adding-custom-instructions-for-github-copilot
shinpr/ai-coding-project-boilerplate — real-world instance of an instructions file as a pure control-flow/approval-gate router to subagents and skills. github.com/shinpr/ai-coding-project-boilerplate
KarlRaf/gtm-starter-kit — real-world single-vertical assembled template (instructions + skills + KB + memory-refresh loop). github.com/KarlRaf/gtm-starter-kit
github.com/anthropics/claude-code issue #51735, "Agents repeat identical mistakes across sessions — no cross-session behavioral learning." github.com/anthropics/claude-code/issues/51735
workain/agent-harness-registry — the template's public home (templates/base-project-template/) and its research deep-dive (deep-dives/components/instructions-rules/base-project-template/). github.com/workain/agent-harness-registry