iTechGuides is reader-supported. When you buy through links on our site, we may earn an affiliate commission. As an Amazon Associate I earn from qualifying purchases. Learn more
Written rules are useful, but they do not enforce themselves. In a review of 161 commits across six repositories I own, I found that three repositories had no CI and also had broken lint; in another, a check script existed but had never been run. That is evidence about my repositories—not a general measure of how well developers or coding agents follow instructions.
The practical distinction is whether a rule is guidance or a tested check that runs at the right point and can block a change. Markdown still matters for explaining standards and context. Rules that can be decided mechanically are stronger when automated, provided the check itself is trustworthy.
What I measured—and what the numbers do and do not show
In an article published September 20, 2026, I described reviewing 161 commits across six of my own repositories on August 25, 2026. The sample was small and personal; it does not establish how repositories generally behave or how often coding agents follow instructions.
Free tools Windows power users keep installed
One-click scans. No signup required.
| Observation | What it means in this case study |
|---|---|
| 3 of 6 repositories had no CI | Those same three had broken lint when I reviewed them. |
| 41 of 161 commits included an AI co-author trailer (25.5%) | This is the share in my repositories and commit sample, not an estimate of AI-authored commits generally. |
I started with familiar problems in agent-assisted coding: hardcoded values, missed stack conventions, or a component library being skipped. Rather than assume that adding stronger wording would fix these cases, I looked at the repositories’ instructions, checks, and commit history. Six repositories, all mine, is a small sample. I’m not claiming a general result.
#1 Best Overall
Why Markdown rules can be missed
A document can tell a person or coding agent what to do, but it cannot ensure the instruction was noticed, interpreted as intended, or applied to a particular change. In one repository, I had an AGENTS.md file with a “Hard rules” section, alongside SECURITY.md, GOVERNANCE.md, CONTRIBUTING.md, and a script chaining formatting, lint, type checking, tests, and a build. The script was never run.
That example illustrates two separate gaps: documentation is guidance, and an available script is only a potential check. Unless a person or automated workflow invokes it routinely—and the result matters to the merge—it can be bypassed accidentally or forgotten. More detailed prose may help an agent understand a convention, but it does not turn that convention into an enforcement mechanism.
Which rules belong in an automated check?
Automate rules whose outcome can be decided consistently from the changed files or project behavior. Keep Markdown for rationale, exceptions, and context that a tool cannot judge reliably. The two approaches complement each other: documentation can explain the standard, while CI checks a mechanical property of the change.
| Approach | Best suited to | Typical role | Main limitation |
|---|---|---|---|
| Markdown instructions | Context, rationale, conventions, and exceptions that require judgment | Tell contributors or agents which standards apply and why | Does not itself run or block a change |
| Static or prose lint | Patterns with clear, repeatable rules | Report or reject recognizable violations | Can miss meaning or flag valid cases |
| Local hooks or commit checks | Fast checks useful during development | Give feedback before changes are pushed | Local configuration is not a dependable server-side merge control |
| CI and required repository checks | Repeatable tests and policies suitable for merge gating | Run on submitted changes and block merging when configured as required | Coverage, permissions, configuration, and check quality still matter |
| Review bots or rule-aware review tools | Changes requiring richer, rule-based review | Surface findings for review; behavior depends on the tool and its configuration | Do not assume every finding is correct or that a review result is an effective gate |
These are categories, not a claim that one tool is best for every rule. For example, ESLint’s Markdown processor can lint JavaScript code blocks embedded in Markdown and can run in CI or git hooks. That makes it useful for code inside documentation; it does not make subjective prose conventions mechanically decidable. A separate project, tenet, documents a rule-based review approach for changes. Its project-authored descriptions and benchmarks are examples of an implementation category, not independent evidence that it improves compliance.
Automated checks need to earn trust
A green check is only meaningful if the check detects the failures it claims to prevent. While developing a checker, I applied 70 mutations and found that 30 survived with the test suite still green. I also discovered that exit codes could treat “passed” and “not applicable” as the same outcome, so I added assertions for expected states. These are development observations from my project, not independent validation.
Other failure modes showed why a gate can lose credibility:
Rank #4
- A literal-color heuristic produced seven hits and zero true positives in my example repository. A noisy rule like this should warn or be refined, not block changes.
- A test that treats “not applicable” as equivalent to “passed” can conceal missing coverage. Make the expected state explicit.
- A verification command stayed green while a project generator was broken. Test representative failures in the behavior the command claims to verify, not just whether the command exits successfully.
The principle I took from these cases is that “the enforcement has to be more reliable than the rule it replaces.” Before making a check blocking, test it against valid cases, representative violations, and cases where the rule does not apply. Decide whether uncertain findings should warn, fail, or require human review.
The Tool Desk
Outbyte PC Repair FREERepair Windows errors before they cause bigger problemsFix Now →Outbyte Driver Updater FREEScan for outdated or missing drivers - takes under a minuteDriver Scan →What makes a check enforceable at merge time?
A local hook or workflow file is not the same as a server-side policy. Someone with write access may be able to change repository files or bypass local checks. In my own test, I also found a bypass involving git update-index --skip-worktree. Those details are specific to my setup; they are a reminder to distinguish a check that runs from a control that prevents an unverified change from merging.
Best Value
I tested a GitHub ruleset configured with a required check and no bypass actors. In that test, the ruleset blocked a planted pull request and refused a direct push to the main branch. This reports the result of one repository’s configuration, not a guarantee for all GitHub repositories. The effective protection depends on the ruleset, required checks, permissions, and who can alter or bypass them.
Independent reader supportYour contribution helps us test, update, and keep practical guides available for everyone.A practical way to move from written rule to reliable gate
- State the rule in plain language. Keep the rationale and exceptions in the repository guidance so contributors and agents know which standard applies.
- Decide whether a tool can judge it consistently. If reasonable cases require interpretation, keep it as review guidance or use a warning rather than a blocking check.
- Implement the narrowest useful check. Prefer a check tied directly to the files or behavior covered by the rule over a broad command whose green result is ambiguous.
- Test the check’s expected states. Include valid examples, representative violations, and “not applicable” cases. Verify that a known broken behavior makes the check fail.
- Run it routinely. Use local feedback where it helps, then configure the appropriate CI or repository control if the rule must be a merge condition.
- Review false positives and misses. Track whether the check blocks valid changes or lets known failures through; adjust its scope or severity accordingly.
I built rebar, an open-source tool that applies rules to changes, and described one repository as gated for real by it. At the time of the September 20, 2026 article, rebar was in alpha and I was its only contributor. That disclosure matters when weighing the implementation example: a tool’s existence is not independent proof that its checks are broadly reliable.
The useful conclusion from this sample
My measurements do not show that Markdown rules are useless or that CI guarantees compliance. They show a narrower, practical distinction: instructions can communicate standards, but only checks that actually run can catch mechanical violations, and only properly configured required checks can make those results a merge condition. The check must itself be tested, scoped to what it can judge, and designed to handle exceptions and false positives.
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.
