Project Context Files
Encode your project's rules once in a context file (CLAUDE.md, AGENTS.md, .cursor/rules) so every prompt starts with them.
TL;DR
- A context file encodes your conventions once so the assistant applies them to every task.
- CLAUDE.md, AGENTS.md, and .cursor/rules hold stack, commands, conventions, and guardrails.
- Keep it short and high-signal; version it like code and scope rules to the right directories.
What It Is
Standing PromptThe part of every prompt you would otherwise retype, written once.
Conventions + commands + guardrails
-> loaded on every task.Tool FilesEach assistant reads its own file for persistent instructions.
CLAUDE.md / AGENTS.md /
.cursor/rules/*.mdcVersionedIt lives in the repo and changes through review like code.
git add CLAUDE.md # it's project
knowledgeWhat To Put In It
Stack & CommandsVersions and the exact build, test, and lint commands.
"TS 5.x, Node 20. Test: pnpm test.
Lint: pnpm lint."ConventionsNaming, structure, and patterns new code should follow.
"Named exports only. Zod for
validation. No default exports."GuardrailsHard rules the assistant must always respect.
"No new deps without approval.
Never edit generated files."Keep It Sharp
High SignalCrisp rules and commands beat long explanatory prose.
Bullets and commands, not essays.Scope By PathApply rules only where they belong using globs or nesting.
api/** -> backend rules
app/** -> frontend rulesPrune OftenRemove outdated rules so the file stays small and current.
Delete stale rules; they mislead
and cost context.Make It Work For You
Enable Self-CheckCommands in the file let an agent run tests and lint on its own.
"After changes, run pnpm test and
fix failures."Point To ExamplesReference canonical files the assistant should imitate.
"Follow the pattern in
src/features/orders."State What Not To DoCall out past mistakes so they are not repeated.
"Do not use the deprecated
`legacyFetch`."Tips
- Put the build/test/lint commands in the file so the agent can verify its own work.
- Scope rules to paths (e.g. .cursor/rules globs) so backend rules do not apply to frontend files.
Warnings
- A bloated context file wastes the window on every call and buries the rules that matter.
- Stale instructions are worse than none; update the file when conventions change.
In Practice
A compact CLAUDE.md (or AGENTS.md) that gives the assistant everything it needs to work in your repo: stack, commands, conventions, guardrails, and canonical examples, without bloating the context window.
- Stack and commands let the assistant build, test, and lint without asking.
- Conventions keep new code consistent with the rest of the repo.
- Guardrails encode the hard rules you never want violated.
- Pointers to canonical files and anti-patterns steer quality on every task.
# Project: Acme Web
## Stack
Next.js 15 (App Router), React 18, TypeScript 5.x,
Tailwind v4, Prisma + Postgres. Node 20, pnpm.
## Commands
- install: pnpm i
- dev: pnpm dev
- test: pnpm test (run after changes; fix failures)
- lint: pnpm lint
## Conventions
- Named exports only; no default exports
- Validate input with zod
- Server components by default; 'use client' only when needed
- Follow the pattern in src/features/orders for new features
## Guardrails
- No new dependencies without approval
- Never edit files under src/generated/
- Do not use the deprecated legacyFetch; use apiClientFAQ
The things you would otherwise repeat every prompt: the stack and versions, key commands (build, test, lint), code conventions, architectural notes, and hard guardrails like 'no new dependencies without approval'. It is the standing part of every prompt, written once.
Use the one your tool reads: CLAUDE.md for Claude Code, AGENTS.md as a cross-tool convention many agents honor, and .cursor/rules for Cursor. The content is similar; the filename and loading differ. Some teams keep one source and symlink or generate the others.
As short as possible while covering what matters, because it is loaded into context on every task. Favor crisp rules and commands over prose. If it grows large, split it: a small root file plus directory-scoped rules that load only when relevant.
Use path scoping. Cursor's rule files take glob patterns so a rule applies only to, say, *.tsx or the api/ directory. Nested CLAUDE.md files apply to their subtree. This keeps backend rules off frontend files and vice versa.