What is the difference between AGENTS.md and CLAUDE.md?

AGENTS.md is a shared convention read by many coding agents (Codex, Copilot, Windsurf, Gemini CLI and others). CLAUDE.md is the file Claude Code reads; it can import AGENTS.md so both tools share one rulebook.

Why does my AI agent ignore AGENTS.md or Cursor rules?

Rules files are context, not constraints. Long or stale files get diluted, task instructions win over general rules, and nothing checks the result. Keep the file short and current, and verify the outcome with checks such as stet guard and stet check.

How do I enforce AGENTS.md rules?

Turn each important rule into something checkable: allowed files per task, protected paths, and commands that prove behaviours still work. Run them after every AI change and in a pre-commit hook. Stet keeps AGENTS.md in sync with these checks.

Guide · Rules files

AGENTS.md, CLAUDE.md and Cursor rules: why rules files are not enforcement

Updated 15 Nov 2026 · 5 min read

Every serious AI-assisted codebase now has a rules file: AGENTS.md for most agents, CLAUDE.md for Claude Code, rules for Cursor. They help. But a rules file is a request. Nothing checks the agent actually followed it.

Which file does what

File	Read by
`AGENTS.md`	A shared convention read by Codex, GitHub Copilot, Windsurf, Gemini CLI and many other agents.
`CLAUDE.md`	Claude Code. It can import AGENTS.md (`@AGENTS.md`) so both share one rulebook.
Cursor rules	Cursor's project rules.

Why agents drift from the rules

Rules are context, not constraints. The model weighs them against the task; the task usually wins.
Files go stale. A rules file written in March doesn't know about the decision you made last week.
Long files get diluted. Fifty rules read like none.
No feedback loop. If a rule is broken, nobody finds out until review, or production.

What a good rules file contains

What the project is, in one paragraph.
The current task and which files it may touch.
The behaviours that must keep working, and the command that proves each.
A short "never do" list: protected paths, no new dependencies without asking, never weaken a test.
Recent decisions, so they aren't reopened.

Turn rules into checks

The fix is to keep the file generated from things that can be verified. Stet does this: it writes the Stet block of AGENTS.md (imported by CLAUDE.md) from the project charter, the current scope, the locked behaviours and the decision log, then verifies the outcome.

npx stet-cli init                     # creates the charter, AGENTS.md and CLAUDE.md
stet scope set "Add CSV export" --allow "src/export/**"
stet decide "Prices are integer cents" --why "float rounding bugs"
stet guard && stet check              # did the agent actually follow it?

Text you write outside the Stet block is kept. See the AGENTS.md guide for the full template.

Make your rules checkable

npx stet-cli init · AGENTS.md guide · Guardrails compared →