Español

Keep a Rules File for Your Agent

Stop repeating yourself to your AI assistant every session. Every new session starts with a fresh context window: your coding agent forgets the build command, the test runner, the "we use 2-space indentation" rule — all of it. The fix is a rules file: a markdown file in your repo that documents your conventions once, and that the agent reads automatically at the start of every session.

Why a rules file beats retyping

1. Zero repetition. Build commands, coding standards, and project layout load automatically. You never re-explain them.
2. Consistency. The same rules apply in every session, for every teammate — the file is version-controlled, so a convention change is a pull request, not a Slack thread.
3. Instant onboarding. A new agent (or a new teammate) is productive from the first prompt, because the "how we work here" knowledge lives next to the code.

One idea, many file names

Every major coding agent supports the pattern; only the file name changes:

If your repo already has an AGENTS.md, Claude Code can reuse it: put @AGENTS.md on its own line inside CLAUDE.md and the file is imported at session start — one source of truth, every tool reads it.

What to put in it

Write down what you'd otherwise re-explain. The best trigger: the agent makes the same mistake twice — that's a rules-file entry. Good content:

• Build, test, and run commands (npm test, make lint) — exact commands, not "run the tests"
• Coding standards that differ from tool defaults ("2-space indentation", "no default exports")
• Project layout ("API handlers live in src/api/handlers/")
• Gotchas and "always/never" rules ("never push directly to main")

Keep it specific and short. Anthropic's guidance for CLAUDE.md is to target under 200 lines: longer files consume more context and instructions get followed less reliably. Concrete beats vague — "Run npm test before committing" works; "test your changes" doesn't.

Power-user moves

• Split by topic. Claude Code reads every .md in .claude/rules/ (e.g. testing.md, security.md); Cursor does the same with .cursor/rules/. Small focused files are easier to maintain than one monolith.
• Scope rules to paths. Both Claude Code and Cursor support glob-scoped rules (paths: / globs: frontmatter) that load only when the agent touches matching files — TypeScript rules only for **/*.ts. Context stays lean.
• Import, don't duplicate. Claude Code's @path/to/file syntax pulls other files into context at launch (up to four hops deep). One @AGENTS.md line keeps multi-tool repos DRY.
• Personal vs. team rules. Keep team conventions in the checked-in file; keep your private preferences in a gitignored sibling (CLAUDE.local.md) or your home directory.
• Rules are context, not enforcement. The agent treats the file as strong guidance, not hard config. For rules that must never be broken (blocked commands, protected paths), use your tool's enforcement layer — hooks or permission settings — and keep the rules file for behavior.

Keep it current

A stale rules file is worse than none: the agent will confidently follow last quarter's conventions. Review it whenever conventions change, delete contradictory entries (an agent facing two conflicting rules may pick either one), and treat rules-file edits as part of the code review that changed the convention.

Resources

• Claude Code memory — CLAUDE.md files, rules, and imports
• AGENTS.md — the open cross-tool rules-file standard
• Cursor project rules (.cursor/rules)
• GitHub Copilot repository custom instructions