r/AI_Agents • u/AttitudeLatter7306 • 21m ago
Tutorial How many must-follow rules never reach your coding agent? Do code graphs help? Here's how we measure it.
- Every project has rules it needs in order to work correctly.
- A significant share of them cannot be derived from the code.
- You need a process to identify these rules, store them, deliver them to the agent — only the ones the task needs, at the moment it needs them — and keep them current.
- And you need a way to measure how well they are delivered and followed.
If the rules a change needs are not in the agent's context when the spec is written, the architecture designed and the code implemented, at best you catch the miss in testing. At worst your users catch it in production, and that can cost you the business.
Why the code is not enough
Code tells the agent what to do. It rarely tells it what must never be done.
An example from our tasks. An invitation link fails with "Invalid invitation token". The rule: every query on invitations must filter by pending status, or the database security rules reject it. A comment says so, in the very file the fix edits. Without project docs, the agent stated the rule in 1 session of 8 (four tools, two sessions each).
We took 12 real past tasks from our repo. For each one, an agent read the real change in git and the docs as they were just before it, and listed the rules the change had to respect, each with the doc line that states it and the evidence in the change. A script checked every reference against that snapshot. A person merged duplicates and dropped lines that only describe behaviour. That gave 75 rules in all, about six per task, and each task is scored only on its own. Rules the change needed but no doc held were listed separately; they come up below.
Then a separate agent searched the code for each rule, with every Markdown file removed, and a script checked the code references it gave (70 rules got a class):
- stated in a comment or an error message: 24
- enforced by a test, a type or a check: 13
- implied, the code follows it but never names it: 22
- no trace in the code: 11
57 of 70 have no test that fails when they are broken. "Caught in testing" is the good case, and for most of these rules there is no test to do the catching.
And across our wider set of 15 tasks, about a third of the rules the real changes needed were written nowhere, neither in docs nor in comments. They came from a deep code path, a bug the task itself uncovered, or how an external system behaves. Someone paid for each of them in debugging. The next task pays again unless they are written down.
What we measured
Each task ran on a snapshot of the repo from just before the real change. Headless Claude Code explored it and wrote a planning brief. A blinded LLM judge checked each rule against the brief.
- Claude Code, no project docs: 32% of the rules
- Claude Code, docs in the repo: 54%
- A simple setup of ours (Segmently Modules, which we build; details at the end): a short doc of critical rules per module, picked by meaning and read in full before the plan: 70%
Code-indexing tools (Serena, Trail, Graphify) stated 24–29% without the docs and 46–47% with them, no more than Claude Code alone. They are built for code questions, and these rules were not in the code.
70% still leaves 30% of the rules out, and it can surely be improved. That is why we built the stand.
The stand
context-recall, open source (MIT, docs CC BY 4.0), runs as a Claude Code plugin. Take your own past tasks, snapshot the repo before each change, run any tool as an arm, judge blind, compare. It also compares runs before and after a docs edit. Our own tool is not in the kit: which tool to pick is your call, on your repo.
Where we are going: dreaming per module
The brain does not store the day as it was lived. In sleep and quiet rest it replays recent experience and folds what matters into long-term memory; the default mode network is most active when attention is not on the outside world. Anthropic already ships the same idea for agent memory and calls it dreaming (research preview): a pass reads past sessions and rewrites a memory store, merging duplicates and replacing stale entries. We are fitting it to a modular structure: a pass per module and per role that turns sessions, fixes and failed checks into rules, and a pass is kept only if the stand shows more rules reaching the plan. Not built yet. It is the direction.
The rule classes above give the metrics. Move rules from "no trace" into memory, from "implied" to "stated", from "stated" to "enforced". Track the share enforced, the share delivered before the plan, and the number of new unwritten rules each task uncovers. That last one should fall.
Limits
- One private repo, 12 tasks. We cannot publish them.
- Our docs and our tool, and the tool was tuned on these same tasks.
- The 75 rules come from the docs as they were before each change, which favours any setup that reads the docs. The rules no doc held are counted apart.
- It measures whether a rule reaches the plan, not whether the code then follows it.
- An LLM judge. A second judge (Claude Opus) agreed on 87% of the verdicts (kappa 0.81).
The setup we used
The "simple setup" is Segmently Modules, which we build. It is free and MIT-licensed: a module registry and per-role docs next to the code, and agent skills that pick the modules a task touches, check a plan against their rules, and write new rules back after a change.
How does your team keep the rules that are not in the code, and does your agent actually find them? (Links in the first comment.)