In a 48-day, one-machine case study, a developer’s always-on agent instruction files grew from 90KB to 147KB without a decline in the violations they tracked. The author then moved eight of 24 tracked rules into code gates and reported no further counted recurrences for those eight. That is a useful workflow experiment—not proof that long instruction files fail, or that code checks will work for every team.
What happened in the 48-day case study
The author, writing as untactit, tracked one machine and one operator. Their account says the always-on instruction files increased from 90KB to 147KB, while the count of flagged violations did not decline. The author’s English-rendered article says, “Even after increasing instruction files from 90KB to 147KB, violations did not decrease.” The Zenn page identifies that English text as an AI-generated translation, so the quotation should be read in that context. Read the translated account.
As an Amazon Associate I earn from qualifying purchases.
This was not a controlled measurement of agent compliance. The author counted clauses that were broken and noticed by a human; violations that went unobserved or unflagged were not included. The author acknowledges that “The actual violation rate should be higher than this.” The reported figures therefore describe that person’s tracking method, not a population-wide failure rate.
What’s actually slowing this PC down?
Pick the symptom - the matching free tool is one click away.
How the author decided when to move a rule into code
The proposed process treats documentation as a first response, then escalates repeated, observable failures:
#1 Best Overall
- First violation: record what happened so the issue can be recognized if it recurs.
- Second violation: write a documentation clause, but surface only the three most recent frequent violations at the start of each turn rather than continually expanding the opening reminders.
- Third violation: if documentation alone has not solved the problem, consider building a code gate that checks the relevant output or repository state.
- Validate the gate: deliberately provide broken input and confirm that the check catches it. Also test valid cases to identify false positives.
In the author’s tracking, 24 rules were followed: eight were moved into code gates and 16 remained documentation-only. The author reported zero counted recurrences among the eight gated rules, while the 16 document-only rules recurred. The account does not establish that these groups were comparable, randomly assigned, or affected by the gates alone. “Zero recurrence” means none was recorded under this particular tracking method—not that violations became impossible.
When a code gate can help—and when it cannot
A gate is most promising when a rule maps to an observable artifact: a file, diff, command result, schema, test outcome, or other state a check can inspect. For example, a deterministic check may be able to reject a forbidden file change or detect a missing required field. A vague instruction about judgment, intent, or quality may not have a reliable machine-verifiable signal.
Rank #2
Before implementing a gate, ask:
- Is the expected behavior observable? If the check cannot inspect evidence of compliance, it cannot enforce the rule reliably.
- Can it detect the violation? Test deliberately broken examples, including boundary cases.
- What are the error costs? A false negative lets a violation through; a false positive blocks acceptable work and can erode trust in the check.
- Will the check stay correct as the repository changes? A gate adds maintenance work and may need updates when conventions or architecture change.
- Does the rule need explanation rather than enforcement? Preserve context, rationale, and policies that cannot be expressed as reliable checks in documentation.
The practitioner’s account notes that gate accuracy had not been measured and describes one regression judge with a 66% false-positive rate on a sample. That is a warning about validating checks, not a general estimate of code-gate accuracy.
What other 2026 studies add—and do not establish
Persistent rule files can help in a particular benchmark
A 2026 controlled study by Zhang, Wang, Cui, Qiu, Li, Zhu, and He evaluated persistent rule files with Claude Code and Claude Opus 4.6 on SWE-bench Verified. Its corpus included 679 instruction files and 25,532 rules, and the evaluation involved more than 5,000 agent runs. The authors report that rule-file conditions improved performance in that setup; in their ablation, negative constraints were the only individually beneficial rule type, while positive directives could hurt. They also report no degradation up to 50 rules under the tested conditions. These findings are specific to the paper’s model, vendor, benchmark, and methods; they do not directly test the practitioner’s escalation workflow or show that rule files always help. Read the study.
Rank #3
File structure alone is not an established explanation
A separate 2026 study by Damon McMillan examined file size, instruction position, architecture, and conflicts with adjacent files across 1,650 Claude Code CLI sessions and 16,050 function-level observations. After correcting for multiple testing, it reports no detectable contrasts for the structural variables it tested. It did report an association between session progression and declining odds of compliance in its tested conditions, but described the relationship as non-monotonic. The study did not evaluate code gates or reproduce the 48-day case study, so it cannot establish why that author’s tracked violations persisted. Read the study.
Together, these papers caution against a simple rule such as “shorter files work better” or “more rules always help.” Results depend on the tasks, models, and measurements used, and neither study validates the specific code-gate workflow.
Independent reader supportYour contribution helps us test, update, and keep practical guides available for everyone.A practical decision for your repository
Use documentation for context and for rules that require interpretation. For a repeatedly observed failure with a checkable artifact, try a narrow gate rather than adding another broad instruction. Keep a record of the triggering examples, test the gate against both broken and valid cases, and monitor whether it catches real violations without blocking acceptable work. If a rule has no dependable observable signal, a code check may create false confidence; clearer instructions or a different workflow may be more appropriate.
The Tool Desk
Outbyte PC Repair FREEClear out junk files and repair common Windows errorsFree Scan →Outbyte Driver Updater FREEScan for outdated or missing drivers - takes under a minuteDriver Scan →Quick Recap
Product prices and availability are accurate as of the date/time indicated and are subject to change. Any price and availability information displayed on Amazon at the time of purchase will apply.
