AGENTS.md Don’t Rules
Concept detailing the precise negative‑rule (“don’t” statements) found in AGENTS.md files across the top‑100 GitHub repositories. The field study enumerated 784 explicit bullets, most of which use strong modality (must, always, never) and cover topics such as commit messages, test handling, and AI disclosure.
Common Modalities
- must – obligatory actions
- always – perpetual enforcement
- never – forbidden practices
- cannot – disallowed state
Topic Categories
| Category | # Rules | % of Total | Representative Rules |
|---|---|---|---|
| Commit Messages | 37 | 4.7% | “Never use an emoji in a commit subject that is not a PR number.” |
| Testing | 117 | 14.9% | “Never skip a test when adding a feature.” |
| Build & CI | 78 | 9.9% | “Always run spotlessCheck before commit.” |
| Language conventions | 91 | 11.6% | “Must format code with Prettier before commit.” |
| Security | 18 | 2.3% | “Never commit secrets or credentials to source control.” |
| AI Disclosure | 11 | 1.4% | “If AI was used in any commit, add a AI-assisted: <tool> trailer.” |
| Build tools | 42 | 5.3% | “Never run go test without -race flag on CI.” |
| Documentation | 53 | 6.7% | “Must document all public APIs in Markdown” |
| Git Workflow | 89 | 11.3% | “Always run git diff --name-only before git commit to verify changes.” |
| Miscellaneous | 65 | 8.3% | “Never commit compiled artifacts.” |
Detailed Bullets (Excerpt)
- Never allow
bun testto run when you haven’t installed dependencies. - Always add a brief commit message summarizing changes.
- Must keep all tests under
src/test/or.../tests. - Never leave CI configuration files with hard‑coded secrets.
- must run
./gradlew spotlessApplybefore committing in Java projects. - Always push code to a feature branch and create a PR.
- Never merge a PR that fails the lint check.
- Must reference any new module in the top‑level
docs/folder. - Always tag release commits with
vX.Y.Z. - Never rely on unstaged changes to satisfy CI pre‑commit hooks.
Relationships
- See agents-md-field-study for quantitative context.
- See agents-md-patterns for structural sections where rules are applied.
- See temporalio-sdk-java-agents-md for a concrete example in an actual AGENTS.md file.
Implications
- Cognitive overhead: Contributors must remember strong modality verbs that carry action requirements.
- Automation potential: Rule sets can be fed into lint tools or Git hooks (e.g., pre‑commit, husky) to enforce compliance.
- Onboarding speed: Clear disallowed actions reduce accidental infractions.
- Cross‑project consistency: Uniform rule style aids teams that contribute to multiple repos.
Open Questions
- Are there domains (e.g., data‑science, embedded) where specific rule categories dominate?
- How effective are always vs. must in preventing regressions?
- Can a machine‑learning model predict which rule categories drive highest issue frequency?
Sources
raw/prompts/articles/coldtea-agents-md-field-study.md– Field study page containing the original negative‑rule enumeration.