CLAUDE.md Generator
Answer eight questions and get a well-structured CLAUDE.md or AGENTS.md for your repo.
Rules a linter can't enforce — naming, structure, patterns.
Things the agent must never do, with the reason if it helps.
Landmines the agent can't discover from the code alone.
# CLAUDE.md — project instructions ## Stack Next.js 14 (App Router), TypeScript, Tailwind v4, Postgres via Drizzle ## Commands - Package manager: `pnpm` — NEVER use any other package manager. - Test: `pnpm test` - Build: `pnpm build` Run the test command before claiming any task is complete. No exceptions. ## Conventions - Server components by default; "use client" only when needed - Named exports for components, default export for pages - Zod for all external input validation ## Forbidden patterns - NEVER: any types — use unknown and narrow - NEVER: Direct fetch in components — go through lib/api - NEVER: Editing generated files in src/gen/ ## Gotchas - Drizzle migrations must run before the dev server or queries 500 - The e2e suite needs Docker running locally ## Working style - Make surgical, minimal diffs. Do NOT refactor unrelated code. - Surface blockers immediately with the exact error text. - NEVER commit secrets, API keys or credentials.
37 lines · ≈ 244 tokens loaded every session
How it works
This generator turns eight short answers into a structured CLAUDE.md (or AGENTS.md — same content, different filename) for your repository. The preview builds live as you type, every section is optional, and nothing leaves your browser. Copy it or download it directly into your repo root.
The structure mirrors what works in practice across thousands of real agent sessions: a stack declaration so the agent stops guessing your framework, exact commands for install, test and build so it never invents npm run test:all, a conventions block for the rules a linter cannot enforce, an explicit forbidden-patterns list, and a gotchas section for the landmines only you know about. That last section is the highest value per token in the whole file — agents cannot discover from source code that your local D1 migration runner chokes on partial applies, or that a particular env var is wrangler-managed.
The tone selector changes how directives are phrased. Strict mode produces imperative MUST/NEVER language, which models follow more reliably for safety-critical rules but reads heavy-handed if applied to everything. Conversational mode reads like a senior engineer onboarding a new hire and works well for conventions and context. Most teams land somewhere between: strict for the forbidden list, relaxed everywhere else — so pick the tone that matches your most important rules and hand-edit the rest.
Treat the output as a living document rather than a one-shot artifact. The teams that get the most from coding agents follow a simple loop: when the agent makes the same mistake twice, that is a missing line in CLAUDE.md, not a model problem. Add the line, keep the file under roughly 150 lines, and split per-directory when a monorepo grows subsystems with conflicting rules. The instructions file is part of your codebase now — review changes to it like code, because it shapes every line the agent writes. A short, sharp, current file beats a long stale one every single time — the agent reads it on every session, so every sentence either earns its tokens or quietly degrades the rest.
Frequently asked questions
What is the difference between CLAUDE.md and AGENTS.md?
They serve the same purpose — project instructions an AI coding agent reads at session start — but different tools look for different filenames. Claude Code reads CLAUDE.md; OpenCode, Codex and a growing list of agents read AGENTS.md. The content is interchangeable, so this tool generates one document and lets you toggle the filename and header. Many teams keep both files, with one symlinked to the other.
What makes agent instructions actually effective?
Specificity and brevity. Agents follow concrete commands ('run npm test -- --runInBand') far better than vibes ('make sure tests pass'). The highest-value sections are exact build/test commands, forbidden patterns with the reason attached, and gotchas the agent cannot discover from the code alone — like a flaky migration step or a directory that must never be committed. Generic advice ('write clean code') wastes context tokens and changes nothing.
Is there a length limit for CLAUDE.md?
No hard limit, but every line is loaded into the model's context on every session, so you pay for it in tokens and attention. A good target is 60-150 lines. Past a few hundred lines, instructions start competing with each other and the agent reliably forgets the middle. If your file is growing, split per-directory: Claude Code reads nested CLAUDE.md files scoped to the folder being worked on.
Should I create per-directory CLAUDE.md files?
Yes, once a monorepo has subsystems with different rules. A root file carries universal commands and conventions; a per-package file carries the local test command, framework quirks and forbidden patterns for that package only. This keeps each file short and means the agent only loads rules relevant to the code it is touching, which improves both cost and instruction adherence.
Can I regenerate just one section later?
The generated document uses standard markdown headings, so each section is independently editable in your editor — treat the output as a starting scaffold, not a final artifact. The best CLAUDE.md files evolve: every time the agent makes the same mistake twice, add a one-line gotcha. Your inputs here are preserved in the share link, so you can come back and tweak.
Turn this analysis into a live rule with the FORG rule engine — route models and enforce limits automatically.
Explore the rule engine