CLAUDE.md Generator
Generate CLAUDE.md project instruction files for Claude Code — pick a project type, customize sections, download
Project Type
Select a type to prefill all sections with sensible defaults.
# CLAUDE.md > This file provides project context to Claude Code. It is read automatically at the start of every session. ## Project Description A Next.js application using the App Router. [Add your project summary here — what it does, who uses it, and what problem it solves.] ## Tech Stack - Next.js 14+ with App Router - TypeScript - Tailwind CSS - Prisma + PostgreSQL - NextAuth.js for authentication - Vercel / Cloudflare Pages for deployment ## Build & Run Commands ```bash npm install # Install dependencies npm run dev # Start dev server at http://localhost:3000 npm run build # Production build npm run start # Serve production build npm run lint # ESLint ``` ## Testing Commands ```bash npm test # Jest / Vitest unit tests npm run test:e2e # Playwright end-to-end tests ``` ## Code Conventions - Use Server Components by default; add `'use client'` only when needed - Page files: `page.tsx`, layout files: `layout.tsx` - API routes: `app/api/<route>/route.ts` - Fetch data in Server Components, not in Client Components - Validate all form inputs server-side with Zod - Keep `'use client'` components as leaf nodes (no children that need server data) ## File Structure Overview ``` app/ (auth)/ # Route group for auth pages (dashboard)/ # Route group for app pages api/ # API route handlers components/ ui/ # Primitive UI components layout/ # Layout components (Header, Footer, Sidebar) lib/ db.ts # Prisma client singleton auth.ts # NextAuth config utils.ts # Shared utilities types/ index.ts # Shared TypeScript types ``` ## Common Tasks & Workflows **Adding a new page:** 1. Create `app/<path>/page.tsx` 2. Add metadata export (`export const metadata`) 3. If the page needs client interactivity, create a separate `*Client.tsx` component **Database changes:** 1. Edit `prisma/schema.prisma` 2. Run `npx prisma migrate dev --name <migration-name>` 3. Update seed data if needed ## Things to Avoid / Constraints - Do not use `getServerSideProps` or `getStaticProps` — use App Router patterns - Do not run Prisma queries in Client Components - Do not store secrets in client-accessible files - Do not bypass authentication middleware for protected routes - Do not skip input validation on API routes
Place the file in your project root. Claude Code reads it automatically.
If you use Claude Code, the CLAUDE.md file is the most direct lever you have over how the AI behaves in your specific project. This tool generates one for you — prefilled with sensible defaults for your project type, and editable section by section.
What Is CLAUDE.md?
CLAUDE.md is a special Markdown file that Claude Code reads automatically whenever it starts a session in your project directory. Think of it as a project-level system prompt: it tells Claude about your codebase, your conventions, your build commands, and anything else it needs to know to work effectively without repeated explanations.
When you open a terminal in your project and run claude, Claude Code checks for a CLAUDE.md in the current directory (and parent directories) and loads its contents as persistent context. Every question you ask, every file you ask it to edit, every task you assign — Claude has already read your CLAUDE.md before it responds.
This is categorically different from pasting context into every conversation. CLAUDE.md is persistent, version-controlled alongside your code, and automatically shared with every team member who uses Claude Code on the project.
What Should Go in CLAUDE.md?
A well-structured CLAUDE.md typically covers six to eight topics. Not all are required — the right set depends on your project’s complexity.
Project Description
A short paragraph explaining what the project does, who uses it, and what problem it solves. Claude uses this to understand the purpose behind requests: “refactor this function” means something different in a payments system than in a CLI toy.
Tech Stack
The languages, frameworks, libraries, and tools in use. This primes Claude to suggest solutions idiomatic to your stack — React patterns instead of Angular patterns, FastAPI conventions instead of Flask ones — without you needing to specify it on every request.
Build and Run Commands
The exact commands to install dependencies, start the dev server, and build for production. Claude Code can run these commands directly. If it doesn’t know them, it will either guess (risky) or ask you (friction). Write them down once.
Testing Commands and Conventions
How to run your test suite, where test files live, and how they’re named. Claude is much more useful when it knows to write *.test.ts files next to source files vs. putting everything in a __tests__/ directory.
Code Conventions
Your naming conventions, style rules, and architectural patterns. This is especially valuable for teams where inconsistency is costly: “PascalCase for components, camelCase for utilities, no default exports from non-component files.” Claude will follow these rules without being reminded.
File Structure Overview
A brief annotated directory tree. Claude Code can read your files, but a high-level map helps it navigate efficiently. Knowing that business logic lives in services/, not routes/, prevents it from putting code in the wrong place.
Common Tasks and Workflows
Step-by-step procedures for tasks that happen often but require specific sequencing. “Adding a new API endpoint: create the Zod schema, create the route handler, create the service, register the route, write the integration test.” If there’s a pattern you’ve codified, teach it to Claude here.
Constraints and Anti-Patterns
A short list of things Claude should never do in your codebase. “Do not use class components.” “Do not commit .env files.” “Do not add dependencies without checking bundle size impact.” Hard rules stated explicitly are reliably followed; hard rules left implicit are reliably violated.
CLAUDE.md Structure Best Practices
Be specific, not aspirational. “Write clean code” gives Claude nothing actionable. “Keep functions under 40 lines; extract helpers rather than nesting logic deeper than 2 levels” does.
Use headings to segment topics. Claude respects Markdown structure. Separate sections are easier to update and easier for Claude to reference when relevant.
Keep it current. A CLAUDE.md that describes a stack you migrated away from last quarter is worse than no CLAUDE.md at all — it creates confident wrong answers. Treat it like code documentation: update it when you change the system.
Commit it to source control. CLAUDE.md should live in your repository root alongside README.md. That way it’s versioned, reviewable, and shared automatically with collaborators.
Don’t duplicate what’s already obvious from the code. CLAUDE.md is for things Claude can’t infer from reading files — your architecture decisions, your team conventions, your non-standard toolchain choices.
Frequently Asked Questions
Where does CLAUDE.md go in my project?
Place it in your project root — the same directory where your package.json, pyproject.toml, or main config file lives. Claude Code searches the current working directory and its parents, so a root-level file covers the entire project. You can also add CLAUDE.md files in subdirectories for monorepos where different packages have different conventions.
Do I need to restart Claude Code after editing CLAUDE.md?
No. Claude Code reads CLAUDE.md at the start of each new session (each time you run claude in a terminal). If you edit the file mid-session, the changes take effect in the next session.
Can I put sensitive information like API keys in CLAUDE.md?
No. CLAUDE.md is a plain text file committed to your repository. Never put secrets, credentials, or private keys in it. For secrets, use environment variables and reference them by name in CLAUDE.md: “API keys are in .env — never commit that file.”
How is CLAUDE.md different from a project README?
READMEs are written for human developers unfamiliar with the project. CLAUDE.md is written for an AI assistant that is already capable of reading code — it needs context about your specific decisions, not background on what React is. READMEs explain the what and why; CLAUDE.md explains the how and the constraints. They serve different audiences and can comfortably coexist.