CLAUDE.md Best Practices: How to Write Effective Project Instructions
Learn how to write effective CLAUDE.md files for Claude Code. Covers file placement, essential sections, marketing-specific patterns, templates, and com...
What is CLAUDE.md?
CLAUDE.md is a project instruction file that Claude Code reads at the start of every conversation. It acts as persistent memory — your project’s conventions, architecture, commands, and preferences survive across sessions without you re-explaining them. Think of it as an onboarding document for an AI teammate that never forgets.
Without a CLAUDE.md, Claude Code still works — it reads your codebase and infers patterns. But with one, it follows your exact conventions, knows your deployment process, and understands domain-specific rules from the first prompt.
Where to Put CLAUDE.md Files
Claude Code supports three CLAUDE.md locations, each with a different scope:
| Location | Scope | Shared with team? | Use case |
|---|---|---|---|
./CLAUDE.md (project root) |
This project | Yes (checked into git) | Project conventions, architecture, commands |
~/.claude/CLAUDE.md |
All projects | No (personal) | Your global preferences, style, tools |
~/.claude/projects/{path}/CLAUDE.md |
This project, only you | No (personal) | Personal notes for a specific project |
All three are merged at startup. Project-root instructions take precedence for project-specific rules. Your global file sets universal preferences (e.g., “always use TypeScript,” “never auto-commit”).
Essential Sections for Every CLAUDE.md
A well-structured CLAUDE.md covers these areas:
Project Overview
# Project
Marketing automation SaaS. Next.js 14 frontend, Express API, PostgreSQL.
Monorepo with packages/web, packages/api, packages/shared.
Tech Stack and Conventions
## Stack
- TypeScript strict mode everywhere
- Tailwind CSS for styling (no CSS modules)
- Prisma ORM for database access
- Zod for input validation at API boundaries
## Conventions
- Components: PascalCase, one per file, co-located tests
- API routes: kebab-case, RESTful, always return { data, error }
- Database: snake_case columns, plural table names
- No default exports except pages
Common Commands
## Commands
- `pnpm dev` — Start all services (web :3000, api :4000)
- `pnpm test` — Run Vitest test suite
- `pnpm db:migrate` — Run Prisma migrations
- `pnpm deploy:staging` — Deploy to staging via Vercel
- `pnpm lint` — ESLint + Prettier check
File Structure
## Key Paths
- /packages/web/src/app/ — Next.js app router pages
- /packages/api/src/routes/ — Express route handlers
- /packages/shared/src/types/ — Shared TypeScript types
- /.env.local — Local environment variables (never commit)
Writing Effective Instructions
The difference between a helpful CLAUDE.md and a useless one is specificity. Compare:
Bad: Vague
Write clean code.
Follow best practices.
Make sure tests pass.
Good: Specific and actionable
- Use early returns to reduce nesting. Max 3 levels of indentation.
- Every API endpoint must validate input with Zod before processing.
- Run `pnpm test` after modifying any file in /packages/api/src/.
- Error responses must use the ApiError class from /packages/shared.
Tips for effective instructions:
- Use imperative voice — “Use Zod for validation” not “It would be nice to use Zod”
- Include examples — Show the pattern you want, not just describe it
- Be concrete — File paths, function names, specific tools
- Omit the obvious — Don’t say “write working code.” Focus on what’s unique to your project
CLAUDE.md for Marketing Projects
Marketing teams benefit enormously from CLAUDE.md because marketing has domain-specific rules that generic AI tools don’t know. Here’s what to include:
## Brand Voice
- Tone: Professional but approachable. No jargon without explanation.
- Point of view: First person plural ("we" not "I")
- Avoid: "leverage," "synergy," "disrupt," "game-changing"
- CTA style: Action-oriented, benefit-first ("Get your free audit" not "Click here")
## Content Rules
- Blog posts: 1500-2500 words, H2 every 200-300 words
- Meta descriptions: 150-155 characters, include primary keyword
- Internal links: Minimum 3 per blog post
- Always include a relevant CTA above the fold
## SEO
- Primary keyword in H1, first paragraph, and meta description
- Use semantic variations, not exact-match stuffing
- Image alt text must be descriptive (not keyword-stuffed)
- Schema markup: Article for blogs, Product for tools
## Tools
- Analytics: Google Analytics 4 (property ID: G-XXXXXXX)
- Email: ConvertKit (API key in .env)
- CMS: WordPress REST API at https://example.com/wp-json/
Pair your CLAUDE.md with installed skills for maximum effectiveness. Skills like Content Strategy, SEO Plan, Marketing Strategy, and Brand Positioning complement your project instructions with proven frameworks.
Advanced Patterns
Conditional Instructions
## Environment-Specific
- When editing /src/api/: Always add input validation and error handling
- When editing /src/tests/: Use test factories from /src/tests/factories/
- When creating components: Include Storybook story file alongside
Referencing Skills
## Installed Skills
- SEO Content Pipeline at ~/.claude/skills/seo-content-pipeline/
- LinkedIn Post Generator at ~/.claude/skills/linkedin-post-generator/
Use these skills when the task matches their domain.
Memory Patterns
## Auto-Memory
Claude has a persistent memory at ~/.claude/projects/this-project/memory/.
Save debugging insights, architecture decisions, and recurring patterns there.
Common Mistakes to Avoid
- Too long — A 2000-line CLAUDE.md causes more confusion than clarity. Keep it under 200 lines. Move detailed docs to separate files and reference them.
- Conflicting instructions — “Use Tailwind CSS” in one section and “Use CSS modules” in another. Review for contradictions.
- Outdated information — Dead commands, renamed files, deprecated APIs. Review quarterly.
- Missing deployment context — Claude can help deploy, but only if it knows how. Include deploy commands and environment setup.
- No error handling patterns — Tell Claude how your project handles errors. Without this, generated code invents its own patterns.
- Kitchen-sink instructions — Don’t paste your entire README. CLAUDE.md is for actionable instructions, not documentation.
CLAUDE.md Starter Templates
Web Application
# Project
[App name] — [One-line description]
## Stack
- [Framework] + [Language]
- [Database] + [ORM]
- [CSS framework]
## Commands
- `npm run dev` — Development server
- `npm test` — Test suite
- `npm run build` — Production build
## Conventions
- [File naming pattern]
- [Component structure]
- [API response format]
## Key Files
- /src/config/ — Configuration
- /src/routes/ — API endpoints
- /src/components/ — UI components
Marketing Project
# Project
[Brand] marketing site and content pipeline
## Brand Voice
- Tone: [Professional/Casual/Technical]
- POV: [We/You/Third person]
- Avoid: [Words and phrases to skip]
## Content
- Blog format: [Word count, structure]
- SEO rules: [Keyword placement, meta descriptions]
- CTA patterns: [Style and placement]
## Tools & APIs
- CMS: [Platform and API details]
- Email: [Provider and config]
- Analytics: [Platform and property ID]
## Deployment
- `[deploy command]` — Push to production
WordPress Project
# Project
WordPress theme/plugin for [purpose]
## Local Dev
- Docker: `docker-compose up`
- URL: http://localhost:8080
- Admin: http://localhost:8080/wp-admin/
## Conventions
- PHP: WordPress coding standards
- Prefix all functions: `mkt_`
- Hooks: document priority in comments
- Database: use $wpdb->prepare() for all queries
## Deploy
- `bash deploy.sh [theme|plugin|mu|all]`
- Production: [URL]
- FTP/SFTP details in deploy.sh
Keeping CLAUDE.md Updated
- After debugging sessions — If you discovered a gotcha, add it. “The payment webhook requires signature verification — see /src/webhooks/verify.ts”
- After architecture changes — New service, renamed directory, changed build tool? Update immediately.
- Monthly review — Scan for dead references. Remove instructions for code that no longer exists.
- After onboarding — If you explained something to a new team member, it probably belongs in CLAUDE.md too.
- Version control — Commit CLAUDE.md changes with descriptive messages. Your project root CLAUDE.md is part of your codebase.
A well-maintained CLAUDE.md is the highest-leverage file in your project. Ten minutes of updates saves hours of re-explaining context. Start with the templates above, customize for your project, and iterate as you learn what instructions make the biggest difference.
Ready to put your CLAUDE.md to work? Learn how to vibe code with Claude Code or explore the fundamentals of vibe coding.