SERIES: AI-POWERED DEV WORKFLOW · POST 8 OF 10
Every time you start a Claude Code session without a CLAUDE.md file, you are starting from zero. Claude does not know your stack, your naming conventions, your auth approach, or the business rules that took your team weeks to nail down. You end up spending the first few exchanges re-explaining context that should not need explaining.
CLAUDE.md changes that. It is a plain text file you put in your project root. Claude Code reads it automatically at the start of every session. After that, Claude knows your project the way a developer who has been on the team for a month knows it — without you having to repeat yourself.
What the Difference Actually Looks Like
Same task. Same developer. Different starting state:
| Without CLAUDE.md | With CLAUDE.md |
|---|---|
| You: “Write an API route to get all projects for the current user.” Claude: “Sure! Here’s a Next.js API route using getServerSideProps…” You: “We’re using App Router. Not pages router.” Claude: “Got it! Here’s a version using pages/api/…” You: “No. We use app/api/ route handlers.” [3 more corrections before usable code] | You: “Write an API route to get all projects for the current user.” Claude reads CLAUDE.md. Knows: App Router, Prisma, NextAuth.js sessions, role-based access, named exports, Zod validation required. Claude: [writes correct route handler on first attempt, calls getServerSession(), checks role, queries via Prisma, validates with Zod, uses named export] You: “Ship it.” |
The before scenario is not an exaggeration. I ran into exactly this on ClientHub before adding CLAUDE.md. The App Router vs pages router confusion alone cost me ten minutes every session. After CLAUDE.md, it never came up again.
What CLAUDE.md Actually Is
It is a Markdown file. Nothing special about the format. Claude Code detects it at the root of your project and loads it into the context of every session automatically. You can also put CLAUDE.md files in subdirectories — Claude loads the closest one relevant to what it is working on.
Think of it as onboarding documentation for your AI assistant. The same things you would tell a new developer on day one — the stack, the conventions, the business rules, the “do not do this” list — go in CLAUDE.md. The difference is that Claude reads it every session, never forgets it, and never needs you to repeat it.
The 10 Sections Every CLAUDE.md Should Have
You do not need all ten sections on day one. Start with stack, structure, and business rules. Add the rest as you discover what Claude gets wrong. Here is the full set, and why each one earns its place:
| # | Section | What to put in it |
|---|---|---|
| 1 | Project Overview | One paragraph. What the app does, who uses it, why it exists. Gives Claude the “why” behind every decision. |
| 2 | Tech Stack | Frontend, backend, database, hosting, auth. Be specific: Next.js 14 App Router, not just “Next.js”. |
| 3 | Directory Structure | Top-level layout with a one-liner per directory. Claude uses this to put new files in the right place without asking. |
| 4 | Naming Conventions | File names, component names, variable names, API route patterns. Define the pattern and Claude follows it consistently. |
| 5 | Code Style Rules | Linting config, formatter, preferred patterns. e.g. “Always use named exports. No default exports except pages.” |
| 6 | Auth Approach | Who is authenticated, how sessions work, what the session object contains. Prevents Claude from re-inventing auth middleware on every feature. |
| 7 | Testing Setup | Test runner, test file location, what to test and what not to. e.g. “Unit tests in __tests__/. Integration tests in tests/integration/.” |
| 8 | Key Business Rules | The non-obvious constraints. e.g. “Soft deletes only — never hard delete.” “Only Admins can reassign project ownership.” |
| 9 | What NOT to Do | Common mistakes Claude makes in this codebase. This is the most underrated section. |
| 10 | Key Commands | Dev server, test runner, lint, build, deploy. Claude uses these when asked to run or verify something. |
Section 9 — What NOT to Do — is the one most developers skip and the one that pays off fastest. Every time Claude uses the wrong router, skips validation, or puts a file in the wrong directory, that is a one-line addition to this section. After a week of coding with Claude, this section alone eliminates most of the friction.
Generating CLAUDE.md with Claude
Option A — Starting a Fresh Project
If the codebase does not exist yet, give Claude the BRD, the FRD, and your tech decisions and ask it to draft CLAUDE.md. You will fill in the gaps, but the skeleton comes back solid:
PROMPT 1 - Generate CLAUDE.md for a Fresh Project
Read docs/ClientHub-BRD-v1.md and docs/ClientHub-FRD-v1.md.
We are building with:
- Next.js 14 (App Router)
- Prisma ORM + PostgreSQL (Supabase)
- Tailwind CSS v3
- NextAuth.js v5
- Deployed on Vercel
- Email via Resend
Generate a complete CLAUDE.md file for this project.
Include all 10 standard sections: project overview, tech stack,
directory structure, naming conventions, code style, auth,
key business rules, what not to do, testing setup, key commands.
Base the business rules on the BRD and FRD.
Keep it under 200 lines.Option B — Existing Codebase
If the project already exists, Claude reads the code and extracts the patterns that are already in use. This works even on large codebases:
PROMPT 2 - Generate CLAUDE.md from Existing Codebase
Read the project structure and key files:
- package.json
- app/ directory (first level)
- lib/ directory
- prisma/schema.prisma
- Any existing README.md or docs/
Based on what you find, generate a CLAUDE.md file for this codebase.
Infer: tech stack, directory conventions, naming patterns,
auth approach, and any business rules visible in the schema or code.
Where you are unsure, add a placeholder comment:
# [TO CONFIRM]: ...
I will review and fill in the gaps.Tip: Review before you commit. Claude will get most of it right but will sometimes infer a pattern that is not intentional. Read the generated file before adding it to the repo — especially the business rules and “What NOT to Do” sections. Those need to be accurate.
The Full ClientHub CLAUDE.md
Here is the complete CLAUDE.md for ClientHub:
# CLAUDE.md — ClientHub
# Auto-loaded by Claude Code at session start.
# Keep under 200 lines. Update when architecture changes.
## Project Overview
ClientHub is a client portal for agencies and freelancers.
Agencies manage projects and deliverables; clients log in to
approve or reject work; developers track assigned tasks.
Phase 1 covers auth, projects, and deliverable approval.
## Tech Stack
- Frontend: Next.js 14 (App Router), Tailwind CSS v3
- Backend: Next.js API routes (route handlers in app/api/)
- ORM: Prisma 5 with PostgreSQL (Supabase)
- Auth: NextAuth.js v5 with credentials + email magic link
- Hosting: Vercel (preview + production)
- Email: Resend (transactional only)
## Directory Structure
app/ # Next.js App Router pages and layouts
api/ # API route handlers
(auth)/ # Auth pages (login, register, reset)
dashboard/ # Protected app pages
components/ # Shared UI components
ui/ # Primitive components (Button, Input, etc.)
features/ # Feature-level components
lib/ # Utilities, db client, auth config
prisma/ # schema.prisma + migrations
__tests__/ # Unit tests (Jest + Testing Library)
tests/integration/ # Integration tests (real DB)
## Naming Conventions
- Pages: PascalCase, e.g. DeliverableDetail.tsx
- API routes: kebab-case, e.g. /api/deliverables/[id]/approve
- DB models: PascalCase singular, e.g. Deliverable, Project
- Env vars: SCREAMING_SNAKE_CASE
- Named exports everywhere. No default exports except page files.
## Code Style
- TypeScript strict mode. No implicit any.
- Prettier + ESLint (config in .eslintrc.js). Run before committing.
- Server components by default. Add "use client" only when needed.
- Zod for all input validation on API routes.
- No inline styles. Tailwind classes only.
## Auth
- Session via NextAuth.js. Session object: { user: { id, email, role } }
- Roles: ADMIN, PM, DEVELOPER, CLIENT
- Role check helper: lib/auth.ts > checkRole(session, role)
- All API routes must call getServerSession() and check role.
- Never trust client-side role claims.
## Key Business Rules
- Soft deletes only. All models have deletedAt: DateTime?
- A user cannot approve a deliverable they uploaded.
- All user actions must be written to the AuditLog table.
- Invoices are read-only once sent. No edits after status = SENT.
- Only ADMIN can delete projects or reassign ownership.
## What NOT to Do
- Do NOT use pages/ router. App Router only (app/ directory).
- Do NOT use getServerSideProps or getStaticProps.
- Do NOT hard-delete records. Always set deletedAt.
- Do NOT use console.log in production code. Use lib/logger.ts.
- Do NOT skip Zod validation on API routes.
- Do NOT put business logic in components. Use service functions in lib/.
## Testing
- Unit tests: Jest + React Testing Library. Run: npm test
- Integration tests hit a real test DB. Run: npm run test:integration
- Do not mock Prisma in unit tests — use factories in tests/factories/
- Every API route must have at least one integration test.
## Key Commands
npm run dev # Start dev server (localhost:3000)
npm test # Run unit tests
npm run test:integration # Run integration tests
npm run lint # ESLint check
npx prisma migrate dev # Apply new migrations
npx prisma studio # Open DB GUIKeeping CLAUDE.md Current
A stale CLAUDE.md is worse than no CLAUDE.md. If it describes an old tech decision or a directory structure that was refactored three months ago, Claude will confidently follow the wrong guidance. Update it when any of these things happen:
| Trigger | What to update |
|---|---|
| New tech added | Added Resend for email? Switched from REST to tRPC? Update the Tech Stack section immediately. |
| New business rule | If a PM or client adds a constraint (“invoices can’t be edited after sending”), add it to Key Business Rules before anyone codes around it. |
| Directory restructure | Moved components to a monorepo? Refactored lib/? Update Directory Structure so Claude stops putting files in the old locations. |
| Claude keeps making the same mistake | Add it to “What NOT to Do” with a specific rule. One line prevents hours of correction across the whole project. |
| Major refactor | After a significant change, ask Claude: “Read the current codebase and suggest updates to CLAUDE.md.” |
The most practical rule: if you find yourself correcting Claude for the same mistake twice, add a line to CLAUDE.md. It takes thirty seconds. It saves thirty minutes next session.
What Is Next
With CLAUDE.md in place, every coding prompt you write gets the full project context automatically. The next two posts close out the series: Post 9 is a structured test case review pass — finding gaps before QA does — and Post 10 is AI-powered code review with Claude.
Next in this series: Post 9 — Test Case Review with Claude: Find the Gaps Before QA Does
Save this one — you will want the CLAUDE.md template when you start your next project.