CLAUDE.md & AGENTS.md Generator
Fill in the things an agent cannot infer from your code, and take away CLAUDE.md, AGENTS.md and a Cursor rule with the same body
CLAUDE.md vs AGENTS.md vs Cursor rules
Three names for the same idea: a Markdown file, committed to the repository, that an agent reads before it starts work. What differs is which tool looks for which name, and whether the file carries any metadata. This is the state of things at the time of writing — each tool’s own documentation is the authority, and these conventions move.
| File | Read by | Where it lives | Nested files | Notable |
|---|
| CLAUDE.md | Claude Code | The repository root, with a personal file at ~/.claude/CLAUDE.md | Yes — files in parent and child directories are picked up too | Can pull in other files with an @path reference |
| AGENTS.md | A cross-vendor convention adopted by several coding agents, among them Codex, Cursor, GitHub Copilot’s coding agent and Jules | The repository root, and any subdirectory | Yes — the file nearest the code being edited takes precedence | Plain Markdown, no front matter, no required sections |
| .cursor/rules/*.mdc | Cursor | A .cursor/rules directory; the older .cursorrules file at the root still works | Yes — a .cursor/rules directory can sit in a subdirectory | YAML front matter decides when a rule applies: description, globs, alwaysApply |
What belongs in the file
The rule that decides everything else: write down what an agent cannot work out by reading the code. Everything else is noise competing with the code for attention.
- Commands. The exact lines that install, run, build, test, lint and typecheck. A repository with three package managers’ lockfiles is a guessing game without them.
- Layout. Four or five lines saying what lives where, and which directories are generated.
- Conventions. The ones a linter does not already enforce — anything a linter catches does not need saying twice.
- Gotchas and prohibitions. The generated directory that must never be edited, the API whose shape is pinned by a consumer, the migration that cannot be re-run. This is the section that earns the file.
Leave out anything that duplicates package.json, the README or the linter config. Keep it to a page, and revise it when it turns out to be wrong rather than adding to it.
Example output
The “Next.js + TypeScript app” preset, exactly as the generator writes it:
# acme-web
Marketing site and dashboard built with the Next.js app router.
## Stack
- Next.js (app router)
- React
- TypeScript, strict
- Tailwind CSS
- Vitest + Testing Library
## Commands
```bash
npm install # install dependencies
npm run dev # start the dev server
npm run build # production build
npm test # run the test suite
npm run lint # lint
npx tsc --noEmit # type check
```
## Project layout
```
app/ routes, layouts and route handlers
components/ shared React components
lib/ framework-free logic, with its tests alongside
public/ static assets
```
## Conventions
- TypeScript strict mode. No `any` — reach for `unknown` and narrow it.
- Prefer named exports; use a default export only where a framework demands one.
- Tests live next to the source file they cover.
- Run lint and typecheck before committing.
- Server components by default; add "use client" only where the browser is needed.
- Style with Tailwind utility classes, not a separate stylesheet.
## Do not
- Do not add a dependency for something a dozen lines would do.
- Do not commit .next/, coverage/ or .env.local.
- Do not change a public route path without a redirect.
## Testing
Vitest with Testing Library. Every module in lib/ gets a test file beside it, and every page component gets a render test. Run the whole suite before opening a pull request.
## Git workflow
Branch from main, one topic per branch. Rebase rather than merge. Never force-push a branch someone else is on.
## Notes
Environment variables live in .env.local and every one of them is documented in .env.example.
Frequently Asked Questions
What is the difference between CLAUDE.md, AGENTS.md and Cursor rules?
Mostly the file name. All three are Markdown instructions an agent reads before it touches your code. CLAUDE.md is the file Claude Code looks for; AGENTS.md is a cross-vendor convention that several tools have adopted so one file serves them all; Cursor reads .mdc rule files from a .cursor/rules directory, and those carry YAML front matter that decides when the rule applies. The body is the same in every case, which is why this generator writes one and emits three.
Do I need all three files?
No. Write the one your team’s tools actually read, and add another only when someone uses a different tool. Many repositories keep AGENTS.md as the single source and let the other names point at it — some people symlink CLAUDE.md to AGENTS.md so the two can never drift apart. Three files with three slightly different sets of instructions is worse than one file that is right.
Where does the file go?
At the root of the repository, committed like any other file, so everyone working in it — human or agent — gets the same instructions. Claude Code also reads a personal file at ~/.claude/CLAUDE.md for preferences that are yours rather than the project’s; that one is not committed. Cursor rules live in .cursor/rules/ inside the repository.
How long should it be?
Short. It is read at the start of every session, so every line competes for attention with the code. Prefer facts an agent cannot infer — the command that runs the tests, the directory it must not touch, the convention that is not visible in the source — and leave out anything a glance at package.json would answer. A page is plenty; several pages usually means it has become documentation, which belongs in docs/.
Does it work in a monorepo?
Yes, and that is where nested files pay off. Keep the root file for what is true everywhere — the package manager, the release process, the conventions — and put a smaller file in each package for what is only true there. The agent reads the file nearest the code it is working on, so the two combine instead of competing. This generator writes one file at a time; run it once per package.
Can one file import another?
CLAUDE.md supports referencing another file with an @path line, which is useful when a long section already exists elsewhere in the repository and you would rather not copy it. Support for that is specific to Claude Code, so keep anything a different tool must understand inline in the file itself. Whether a given tool follows a reference is worth checking against its own documentation before relying on it.