Free · Hyrax
The AGENTS.md that stops AI slop at the source
A drop-in rules file for your AI coding agent (Claude Code, Cursor, Codex, Copilot). It makes the agent produce small, tested, convention-following, reviewable PRs, so the slop never reaches your review queue.
Save it as AGENTS.md at your repo root (or CLAUDE.md for Claude Code). Agents read it before they work. Tune the size cap and add your own "known mistakes" as you catch them.
# AGENTS.md — rules for any AI coding agent in this repo. Read first. If a change can't follow these, stop and ask.
Ownership
- Every change is submitted under a human's name, and that human owns the merge. Build something they can defend, not something that merely runs.
Scope: keep it small
- One logical change per PR. Over ~200 lines of real code, split it.
- Touch only the files the task requires. No unrelated renames or reformatting.
- If it genuinely needs a bigger change, propose the split first and wait.
Before you write
- Read the files you'll change and the ones beside them. Match their patterns, error handling, and naming.
- Restate the task as acceptance criteria in the PR. Build to those, nothing more.
Tests: prove it, don't fake it
- Write the test before the code. Show it fail, then make it pass.
- Break the code on purpose and confirm the test catches it. If it still passes, the test is worthless.
- Never mock, stub, or delete the thing under test to get green. Never weaken an assertion.
- Cover failure paths: null, empty, large input, and an error from every external call.
Dependencies: verify before you add
- No new package unless you've confirmed it exists on the real registry. Unsure means don't use it, and say so.
- Prefer the stdlib and dependencies already here. A new one needs a one-line justification.
- Pin versions. Never invent a package, import, API method, or config key.
Security: safe by default at every boundary
- Validate and type input at the boundary. Escape output. Parameterized queries, never string-concatenated SQL.
- No hardcoded secrets. Read them from the environment.
- Never disable a security control to make something work. If it blocks you, stop and ask.
Simplicity
- Solve the task in front of you. No abstraction or config for a use case that doesn't exist today.
- Any interface, factory, or wrapper must name its second concrete caller. If there isn't one, inline it.
What goes in the PR
- A small diff, the acceptance criteria, and two lines of intent.
- A list of new dependencies, each confirmed to exist.
- A note that the change was AI-assisted.
Never
- Skip an authorization or validation check to make a test pass.
- Call a service, endpoint, or method you haven't confirmed exists.
- Bundle unrelated changes. Submit code you can't explain.
Known mistakes (append your own)
- Add a bullet each time a review catches the agent, so it stops recurring. This is what makes the file get better.
e.g. Don't use db.query with string interpolation; use the sql tagged template in src/db.