AGENTS.md vs CLAUDE.md vs .cursorrules

Every AI coding agent now reads a per-project rules file. The bad news: each agent has its own filename. The good news: the contents are basically the same. This guide explains which file each tool reads, what to put in them, and how to keep one source of truth so you don't end up with five copies that drift.

The filenames at a glance

What goes inside

The content is nearly identical across all of them. A good rules file answers five questions:

1. What are we building? One paragraph about the project, the stack, and the audience.
2. What's the workflow? Planning → tests → implementation → commit. The Ralph-style loop. The 3-retry rule.
3. What are the style rules? Naming, formatting, error handling, no emojis in output, conventional commits.
4. What's banned? Stale library versions, defensive over-engineering, "fix" without root cause, mega-PRs, untested code, secrets in code.
5. What's the quality gate? Lint + types + tests + build all green, or it's not done.

A minimal AGENTS.md that works

# Project rules

## What we're building
Localhost-first {project type} with {stack}. {Audience}.

## Workflow
- Plan before code. Write PLAN.md when scope > one file.
- Failing test first. No green, no commit.
- One feature per commit. Conventional commits.
- 3 retries then ask. Don't grind forever.
- Quality gate: lint + types + tests + build all green = "done".

## Style
- Latest stable library versions. No deprecated APIs.
- Short modules, short functions, clear names.
- Docstrings on public functions. Comments only where the code can't speak for itself.
- No emojis in code or output.

## Banned
- Defensive over-engineering. No try/except wrappers without a reason.
- Workarounds. Find root cause, then fix.
- Secrets in code. Use .env and .env.example.

## Tooling
- Package manager: {npm | pnpm | uv | poetry}.
- Lint: {eslint | ruff}.
- Tests: {vitest | pytest}.
- One source of truth. Don't duplicate config.

The drift problem

The reason this is so annoying is that you need the same content in five different filenames if you use five different agents. People typically:

• Maintain only one (usually CLAUDE.md) and the others stay stale or empty.
• Symlink them all to one file — fragile on Windows, breaks on git clone for teammates.
• Write five copies and watch them drift over a month.

None of these are great. The right answer is to generate them all from one template.

pwsh -File ~/.agents/skills/myvibe/myvibe-init.ps1   # Windows
bash ~/.agents/skills/myvibe/myvibe-init.sh          # macOS / Linux

Should you push for AGENTS.md as the standard?

Yes. AGENTS.md is the closest thing to a vendor-neutral standard right now — it doesn't lead with a brand name, it's already adopted by OpenAI's Codex CLI and a growing list of agents, and it slots naturally next to README.md and CONTRIBUTING.md. The other filenames will continue to exist (vendors will keep their own conventions), but treating AGENTS.md as the master and generating the others from it is a clean path forward.

One-line install

# Windows
iwr https://raw.githubusercontent.com/Mohamed201389/myVibe/main/bootstrap.ps1 | iex

# macOS / Linux
curl -fsSL https://raw.githubusercontent.com/Mohamed201389/myVibe/main/bootstrap.sh | bash

Further reading

• What is vibe coding? A 2026 guide
• How to build a Claude Code skill
• Cursor rules that actually work