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...

Guide Intermediate 1 min read Reviewed Mar 2026

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.

Related Skills & MCPs

Related Guides

Frequently Asked Questions

Do I need coding experience to get started with CLAUDE.md Best Practices: How to Write Effective Project Instructions?
Basic familiarity with command-line tools and project structure is helpful. This guide is rated intermediate-level and walks through the concepts step by step.
How long does it take to learn CLAUDE.md Best Practices: How to Write Effective Project Instructions?
This guide is a 5-minute read covering the key concepts. Hands-on practice with the tools and skills mentioned typically takes an additional 30-60 minutes to set up and try out.
What tools or skills are recommended for CLAUDE.md Best Practices: How to Write Effective Project Instructions?
This guide references 6 specific skills and MCP servers from the Marketing Skills Directory that you can install directly into Claude Code. Check the Related Skills section below for direct links.
Does this guide include hands-on examples?
Yes. This guide includes practical code examples, CLI commands, and step-by-step instructions you can follow along with in your own projects.
Last reviewed and updated: March 5, 2026