.md files for coding agents
Too many .md files for your coding agent?
Decision logs, context notes, rules for each corner of the codebase, sometimes a roadmap so the agent does not lose its place. They start as a shortcut and become a second codebase: written by hand, growing every week, and drifting from the code they describe.
- Writing
- On top of the actual work
- Size
- Longer files, weaker adherence
- Drift
- The code moves; the notes don’t
- Conflicts
- Two files, two answers
Notes help. The problem is making them the only memory your agent has.
Why the folder keeps growing.
Every surprise adds a file or a paragraph. Almost nothing gets deleted, because nobody is sure a rule is safe to remove. After a few months, two files give different answers, the agent reads the wrong one, and the fix is another note.
What to keep in a file, and what to cut.
A small, current set of instructions still earns its place. Treat it like code and review it when the agent surprises you.
- Keep short, always-true rules: build commands, conventions, where things live
- Cut anything the code already says clearly
- Move area rules next to the code they govern
- Delete contradictions instead of archiving them
- Turn must-never rules into tests or checks
History does not belong in a hand-written file.
What changed, why it changed, what was removed on purpose, and what broke before is history, and history is better recorded from the work than rewritten from memory.
Kaplira records it from each governed run, links it to the files it affects, and hands the relevant part to the agent that touches those files. You delete what turns out to be wrong instead of writing everything down. Your notes can stay.
Continue exploring
CLAUDE.md ignored
Why rules get skipped, and how to put the ones that matter in front of the edit.
02Repeated mistakes
Why a fix doesn’t stick between sessions, and how to attach the lesson to the file.
03Agent governance
The boundaries, evidence, and review that keep autonomous changes accountable.
04Regression prevention
Carry known errors, guardrails, and required tests into the runs that follow.
Governance is easier to judge on a real run.
The desktop app is free, no signup is required, and the run record stays on your machine by default. Tell me which part of your review actually needs proof — that is what decides what gets built next.
Governance applies to integrated workflows that use the project contract. It does not replace your executor’s sandbox, access controls, tests, or human review, and it does not guarantee correct code. Read the run evidence and security boundaries to see what the record proves.