Home › Coding & Cursor Rules

One Rules File for Claude Code, Codex, Cursor & Gemini

Stop CLAUDE.md, AGENTS.md, GEMINI.md, and Cursor rules drifting apart: one AGENTS.md source of truth plus tiny pointer files for every agent.

Copy template

# Goal: every coding agent reads the SAME rules. Edit one file, never four.

## 1. AGENTS.md (the only file you edit), at the repo root
# [PROJECT NAME]
[One sentence: what this repo is and who uses it.]

## Stack (decisions already made, do not change without asking)
- Language/framework: [e.g. TypeScript, Next.js 15 App Router]
- Data: [e.g. Postgres via Drizzle]; Styling: [e.g. Tailwind]; Tests: [e.g. Vitest + Playwright]
- Package manager: [pnpm]. Don't switch tools or add a dependency without asking.

## Commands
- Install: [pnpm install] / Dev: [pnpm dev] / Check: [pnpm typecheck && pnpm lint && pnpm test]

## Rules
1. Plan before editing: list the files you will touch, then make the smallest change.
2. Run the check command before saying "done". Report what you ran and the result.
3. Never commit secrets, delete tests to make them pass, or run destructive commands without asking.
4. Match existing patterns in the nearest similar file.

## Per-agent overrides (keep tiny)
- Claude Code: [e.g. use plan mode for changes touching more than 3 files]
- Codex: [e.g. run tests in the sandbox before proposing a diff]
- Cursor: [e.g. prefer inline edits over full-file rewrites]
- Gemini CLI: [e.g. ask before running shell commands]

## 2. CLAUDE.md (one line, imports AGENTS.md)
@AGENTS.md

## 3. GEMINI.md (one line)
Read and follow AGENTS.md in the repo root. It is the single source of truth for this project.

## 4. .cursor/rules/project.mdc (shim so Cursor always loads it)
---
description: Project rules (source of truth is AGENTS.md)
alwaysApply: true
---
Follow every rule in @AGENTS.md. If anything here conflicts with AGENTS.md, AGENTS.md wins.

## 5. Keep them in sync
- Option A (symlinks): ln -s AGENTS.md CLAUDE.md  and  ln -s AGENTS.md GEMINI.md
- Option B (pointers): keep the one-line files above and add a CI check that fails if anyone puts rules in them:
  test "$(wc -l < CLAUDE.md)" -le 2 || (echo "Put rules in AGENTS.md, not CLAUDE.md" && exit 1)
- Delete old .cursorrules and copilot-instructions files after moving their rules into AGENTS.md.

How to use it

1. Click Copy template.
2. Paste into ChatGPT, Claude, Grok, Cursor, or your agent framework.
3. Replace the [BRACKETED] parts with your details.

FAQ

Does Claude Code read AGENTS.md?

Claude Code reads CLAUDE.md. A CLAUDE.md that contains just @AGENTS.md imports the file, or you can symlink CLAUDE.md to AGENTS.md. Either way you edit one file.

Symlink or pointer file?

Symlinks are simplest on macOS and Linux. Pointer files are safer on Windows and in tools that don't follow symlinks, and they leave room for a short per-agent note.

What about .cursorrules?

The old .cursorrules file still works in many setups, but .cursor/rules/*.mdc with alwaysApply: true is the current format. Use it as a one-line shim that points at AGENTS.md.

Related templates

Browse all Coding & Cursor Rules templates

New on PromptLoot