Diagnostic guide
Context rot, context bloat, and instruction residue are not the same problem.
If a coding agent starts ignoring instructions, repeating rejected approaches, or referring to deleted architecture, “context rot” may describe the experience. It does not identify the cause.
Hygiene was created after repository residue caused friction, context bloat, and unintended governance in a real AI-assisted project. Cleaning it improved that workflow. When an agent loads governance comments or stale prose, the material consumes input tokens; contradictions create conflicting context; and prescriptive comments can become unintended governance.
The terms describe different layers
| Term | Useful meaning | Can Hygiene establish it? |
|---|---|---|
| Context bloat | Too much material competes for attention or consumes avoidable tokens. | Only repository prose volume. Hygiene cannot see the active model context. |
| Context drift | Current work diverges from earlier constraints or decisions. | No. It can surface stored material worth reviewing. |
| Context rot | Output quality appears to degrade as context becomes longer, noisier, or less relevant. | No. Multiple causes exist outside the repository. |
| Documentation drift | Documentation no longer matches the implementation. | Partly. Hygiene is not a semantic consistency checker. |
| Instruction residue | Rule-like or decision-like text remains after its original context changes or disappears. | Yes. This is Hygiene's primary inspection target. |
| Phantom authority | A source comment cites a document the scanner cannot find. | Yes, within the documented file and pattern coverage. |
Why context bloat costs more tokens
This relationship is established: model providers meter and price input tokens. Anthropic documents input-token pricing and premium long-context rates, while OpenAI also prices model input per token. More material included in a request means more input tokens processed, subject to provider-specific caching and pricing rules.
The 2026 ETH Zurich study Evaluating AGENTS.md: Are Repository-Level Context Files Helpful for Coding Agents? found over 20% higher inference cost from context files in its evaluated settings. That is direct evidence for those experiments, not a universal savings estimate for Hygiene.
Hygiene reports repository prose volume and residue candidates. It does not yet measure which material a particular agent loaded or calculate tokens saved after cleanup.
When should you scan a repository?
Run a read-only scan when Claude Code, Cursor, Codex, Copilot, or another coding agent:
- appears to follow an old project decision;
- repeats an approach that was previously rejected;
- cites a document or architecture that no longer exists;
- behaves as if a source comment were permanent policy;
- works in a repository whose instruction files and Markdown have only grown;
- seems to receive conflicting repository guidance.
The project that produced Hygiene experienced these symptoms alongside accumulated repository residue, and cleanup reduced the friction. The mechanism is direct: repository text loaded by an agent becomes input context. What varies is which material the tool loads and how strongly it affects the task.
git clone https://github.com/nouvic/hygiene.git
cd hygiene
./bin/hygiene scan /path/to/your-projectHow should you handle a finding?
- Read the finding in its current code context.
- Decide whether it explains a mechanism or preserves an expired decision.
- If it is a real invariant, prefer a test, type, check, or hook that can fail.
- If it is historical discussion, preserve useful rationale in an appropriate decision record or remove it.
- If it is an ordinary comment, report the false positive so the scanner can become more precise.
Do not delete useful documentation merely to reduce a count. Hygiene reports candidates for human review, not a target score.
What can a scan not tell you?
A scan cannot show which files an agent loaded, measure the context window, attribute a hallucination to one comment, guarantee instruction compliance, or calculate token savings. Session history, compaction, tool behavior, model changes, and conflicting prompts can produce similar symptoms.
The originating project shows that repository residue created friction and unintended governance. Hygiene shows whether the same stored conditions are present elsewhere. Broader trials measure prevalence and effect size; they are not needed to establish that loaded text consumes context or that contradictory instructions create conflicting context.