three_rules_paper.md

The Three-Rule Loop: turning a coding model into an improving repo agent

Abstract

Most coding assistants behave like sharp interns with no durable context. They can write code, but they don’t reliably accumulate repo-specific understanding, and they repeat the same mistakes. A three-rule scaffold fixes this by forcing a persistent loop: inspect → write down constraints → implement → record what was learned → tighten constraints. The result is less guesswork, fewer regressions, and faster follow-on work—without prescribing templates.

The problem (what keeps going wrong)

In real repos, failure modes are boring and repeatable:

• The assistant guesses commands, entrypoints, or project structure.
• It applies generic “best practices” that conflict with local conventions.
• It forgets prior decisions and re-litigates them every session.
• It makes broad refactors when a narrow change would do.
• Lessons learned during debugging vanish after the task ends.

The underlying issue isn’t capability. It’s missing feedback infrastructure.

The three rules

1. Create AGENTS.md and keep it current.
   This file is the repo’s “how to work here” contract for the agent, and it must be updated when the agent learns something that should change future behaviour.

2. Create a docs/ directory the agent maintains.
   The agent uses docs/ to write down things that will matter again: setup notes, wins, pitfalls, shortcuts, and plans for larger changes. It updates these as work progresses.

3. Analyse the existing repo for signals.
   Before substantial work, inspect the repo for conventions and reality checks (tooling, style, CI, entrypoints, tests, naming). Use that to seed AGENTS.md and initial docs.

Nothing here says what the files must look like. That’s deliberate. The rules are about behaviour.

The real mechanism: an implied iterative process

The files are not the point. The loop is.

1. Inspect
   Read the repo: how it builds, how it tests, how it’s laid out, what it treats as canonical.

2. Externalize constraints
   Write the operating assumptions down: “this repo uses X, we run Y, we avoid Z.” Put the rules of engagement in AGENTS.md. Put supporting detail in docs/.

3. Implement
   Do the work using those constraints. Keep changes scoped.

4. Capture what changed your mind
   If something surprised you—an edge case, a tool quirk, a test gotcha—write it down while it’s fresh.

5. Tighten the operating model
   Update AGENTS.md so the next task starts smarter. Update docs/ so the next human (or agent) doesn’t re-discover the same trap.

Repeat. The agent becomes more repo-aligned over time.

Why this works

• Durable memory in the right place. The repo holds the context, not the chat.
• Grounding beats guessing. “Inspect first” is a hard gate against hallucinated structure.
• Learning becomes a deliverable. If the agent learns something and doesn’t record it, it didn’t finish the job.
• No template lock-in. Different repos can converge on different shapes of AGENTS.md and docs/ while still following the same loop.

What you get in practice

When it’s working, you’ll notice:

• Fewer “we tried this already” moments.
• Faster setup and fewer dead-end commands.
• Smaller diffs and fewer drive-by refactors.
• Better consistency with local patterns.
• An audit trail of why the agent is behaving a certain way.

Common failure modes (and how the rules counter them)

• Docs rot: solved by making updates part of the job, not an optional extra.
• Over-documentation: keep docs terse; prefer bullets and “do X, avoid Y” notes.
• Agent policy creep: AGENTS.md should track repo reality. Treat it like code: review it, trim it, correct it.

Minimal adoption

Add the three rules to your repo instructions. On the first agent-assisted change, require AGENTS.md and docs/ to exist. After that, enforce the loop: repo-specific lessons must land in writing, and the agent’s operating assumptions must evolve with them.

Conclusion

This is a small constraint that creates compounding returns. You aren’t asking the agent to “be better” in the abstract. You’re giving it a place to store what it learns and a reason to update how it behaves. The files are artifacts; the value is the loop.

The Prompt In its rawest and most adaptable form

When you first set up a repo and have some code in it already and don't have an AGENTS.md or docs dir, this is what you use:

1. Make an AGENTS.md, you are to update this regularly, you are to self improve at this task by updating your own parameters here regularly.
2. Make a docs dir, you own the docs dir, this is your docs dir, you will use this to document anything including general wins, general pitfalls and shortcuts if an issue may reoccur, plans for complex changes and implementations as we discuss how said things should be done, should also be placed here and updated. you will also update this dir regularly in a general sense.
3. Please analyse the existing repo for hints as to what else should be in AGENTS.md and possible initial starter docs that need to be in docs.