Learn how to write effective CLAUDE.md files that help Claude understand your project context, conventions, and workflow.CLAUDE.md is a markdown file placed in the root of your project that Claude (in Claude Projects, Cursor, Cline, Roo Code, Google Antigravity, Windsurf, etc.) automatically reads. It acts as a persistent system prompt that defines your project’s standards, architecture, coding style, and preferences.
This article explores the most effective and future-ready best practices for structuring and maintaining a CLAUDE.md file—your central instruction layer for working with Claude models in 2026.
A well-crafted CLAUDE.md is often the difference between mediocre AI assistance and exceptional, consistent output that feels like working with a senior developer who deeply understands your codebase.
What is CLAUDE.md?
CLAUDE.md is a special markdown file that Claude reads automatically when you start a project session. It provides persistent context, instructions, and guidelines that shape how Claude assists you throughout the entire conversation.
Think of it as an onboarding document for Claude — a single source of truth that describes your project, coding standards, preferred tools, and any constraints Claude should respect.
A well-written CLAUDE.md reduces repetitive explanations, prevents common mistakes, and makes every Claude session more productive from the very first message.
Best Practices for Writing CLAUDE.md
Structure It Like a System Prompt
Use clear sections with hierarchical headings. The most effective structure is:
- Project Context & Goals
- Core Principles
- Architecture & Technical Decisions
- Coding Standards
- Do’s and Don’ts
- Examples (extremely important)
# CLAUDE.md - Project Standards
## 🛠 Critical Commands
- Build: `npm run build`
- Dev: `npm run dev`
- Test: `npm test`
- Lint: `npm run lint:fix`
## 🏗 Architecture
- All business logic lives in `src/lib/services`.
- UI components must be stateless; use `src/lib/store` for global state.
- Database access is restricted to Server Actions or API routes.
## 📝 Coding Standards
- Use **Functional Components** with TypeScript.
- Error Handling: All async calls must use `try/catch`.
- Naming: `kebab-case` for files, `PascalCase` for Components.
## 🔄 Workflow
- Prefix commits with: `feat:`, `fix:`, or `docs:`.
- All PRs must pass the `npm run verify` suite before merge.
Core Best Practices
Follow these principles when crafting your CLAUDE.md file.
1 Be Explicit About Project Context
Always describe what your project does, its main purpose, and who the target users are. Claude cannot infer business logic or product intent from code alone. A brief project summary at the top of CLAUDE.md sets the right mental model for all subsequent assistance.
2 Define Your Tech Stack Clearly
List the languages, frameworks, libraries, and tools your project uses — including version numbers where relevant. This prevents Claude from suggesting incompatible solutions, outdated APIs, or tools you have already decided against.
3 Document Coding Conventions
Specify naming conventions, file structure patterns, formatting rules, and architectural decisions. If you follow a specific style guide or use a linter with custom rules, mention it. Claude will produce code that is consistent with your existing codebase.
4 Specify Preferred Workflows
Describe how you prefer to work: do you want Claude to ask clarifying questions before writing code, or dive in immediately? Should Claude explain changes, or just produce the output? Document your preferences so interactions feel natural and efficient.
5 List What Claude Should Avoid
Explicitly state anti-patterns, deprecated libraries, or approaches that do not fit your project. For example: “Do not use class components — we use functional React components only.” Negative instructions are just as important as positive ones.
6 Keep It Concise and Well-Structured
Use clear headings, bullet points, and short paragraphs. A CLAUDE.md file should be scannable, not a novel. Focus on information that is genuinely unique to your project — avoid documenting things Claude already knows well from its training.
7 Update It Regularly
Treat CLAUDE.md as a living document. Update it when your tech stack changes, when you establish new conventions, or when you notice Claude repeatedly making the same mistake. A stale CLAUDE.md is worse than no CLAUDE.md at all.
Real-World Examples
See how CLAUDE.md looks across different project types and complexity levels.
Basic
# Personal Portfolio — CLAUDE.md ## Project Overview - Personal portfolio website with UI/UX designer - Showcases projects, a blog, and a contact form - Audience: potential clients and recruiters ## Tech Stack - Framework: Astro 4.x - Styling: Tailwind CSS 3.x (no custom CSS unless necessary) - Language: TypeScript (strict mode enabled) - Deployment: Vercel ## Conventions - Use kebab-case for file and folder names - Component files use PascalCase (e.g., ProjectCard.astro) - All images must use the Astro Image component for optimization - Keep components small and single-purpose ## Do Not - Do not use React or Vue — Astro components only - Do not add npm packages without asking first - Do not use inline styles ## Preferred Style - Explain changes briefly before writing code - Prefer simple, readable solutions over clever ones
Advanced
# TaskFlow SaaS — CLAUDE.md ## Project Overview TaskFlow is a multi-tenant project management SaaS application. It allows teams to manage tasks, track time, and generate reports. - Users: small-to-medium businesses (5–200 employees) - Billing: per-seat subscription via Stripe - Data isolation: each tenant has a separate database schema ## Tech Stack Frontend: - Next.js 14 (App Router only — no Pages Router) - React 18 with Server Components where possible - Tailwind CSS + shadcn/ui component library - Zustand for client-side state management Backend: - Next.js API Routes (Route Handlers) - Prisma ORM with PostgreSQL (Neon serverless) - NextAuth.js v5 for authentication - Resend for transactional emails ## Architecture Rules - All API routes must validate input with Zod schemas - Always check tenant ownership before DB operations - Use Server Actions for form mutations, not client-side fetch - Data fetching happens in Server Components, never in useEffect - Shared UI goes in /components, page-specific UI in the page folder ## Security Constraints - Never expose tenant IDs in client-side code or URLs - All user input must be sanitized before database insertion - Rate limiting is applied to all public API routes - Secrets must use environment variables — never hardcoded ## Coding Conventions - TypeScript strict mode — no "any" types allowed - File names: kebab-case. Component names: PascalCase - Custom hooks prefixed with "use" (e.g., useTaskList) - Database models prefixed with "db" in variable names - Error handling: always use try/catch in async functions ## Do Not - Do not use the Pages Router or getServerSideProps - Do not use Redux — we use Zustand - Do not write raw SQL — always use Prisma - Do not use moment.js — use date-fns instead - Do not create client components unnecessarily ## Testing - Unit tests: Vitest - Integration tests: Playwright - All utility functions must have tests before merging - Test files live next to the file they test (*.test.ts) ## Workflow Preferences - Ask clarifying questions before implementing complex features - Always explain architectural decisions in your response - Provide migration steps when changing database schema
Enterprise
# DataPulse ETL Platform — CLAUDE.md ## Project Overview DataPulse is an internal data pipeline platform that ingests, transforms, and loads data from 40+ sources into a central data warehouse. - Team: 8 data engineers, 2 data scientists - Volume: ~500 GB of data processed daily - SLA: 99.9% uptime, pipelines must complete within 4-hour windows - Compliance: SOC 2 Type II, GDPR applicable to EU user data ## Tech Stack Orchestration: Apache Airflow 2.8 (running on Kubernetes) Processing: PySpark 3.5 for batch, Kafka for streaming Storage: AWS S3 (raw), Snowflake (warehouse), Redis (cache) Language: Python 3.11 (type hints required on all functions) Infrastructure: Terraform, AWS (EKS, RDS, MSK, Glue) Monitoring: Datadog, PagerDuty for on-call alerts CI/CD: GitHub Actions → staging → production ## Data Architecture - Medallion architecture: Bronze (raw) → Silver (clean) → Gold (aggregated) - All Bronze data is immutable — never modify raw ingested files - Transformations are idempotent — running twice must produce same result - Partitioning strategy: by ingestion_date and source_system - Schema changes require a backwards-compatible migration plan ## Compliance Requirements - PII fields must be masked in Silver layer and above - EU user data must not leave eu-west-1 AWS region - Data retention: raw data 90 days, warehouse data 7 years - All access to production data must be logged and auditable - Encryption at rest (AES-256) and in transit (TLS 1.3) required ## Coding Standards - All Python functions must have type hints and docstrings - Linting: ruff (configuration in pyproject.toml) - Formatting: black with 88-character line length - No hardcoded credentials, connection strings, or bucket names - Configuration via environment variables or AWS Parameter Store - Use dataclasses or Pydantic for data models — no plain dicts ## Airflow DAG Conventions - DAG IDs: snake_case, prefixed by domain (e.g., finance_daily_close) - Each DAG must have owner, SLA, and on_failure_callback set - Use TaskFlow API (@task decorator) for Python operators - Maximum 3 levels of task dependency depth per DAG - All DAGs must have a README in the same folder ## Performance Rules - Avoid full table scans — always filter by partition columns - PySpark jobs must be profiled before merging if processing >10 GB - Use broadcast joins for tables smaller than 100 MB - Cache reused DataFrames explicitly with .cache() or .persist() ## Do Not - Do not use pandas for datasets larger than 1 GB — use PySpark - Do not use Airflow's BashOperator for business logic - Do not write to production S3 buckets from local environments - Do not merge PRs without passing all integration tests - Do not use mutable default arguments in Python functions ## Testing Requirements - Unit tests: pytest with minimum 80% coverage per module - Integration tests run against a local Spark + MinIO environment - Data quality checks: Great Expectations for schema validation - Backfill tests required for any DAG that modifies historical data ## Deployment Process 1. Feature branch → PR → code review (2 approvals required) 2. Merge to main → automated deploy to staging 3. QA sign-off → manual promotion to production 4. Monitor Datadog dashboard for 30 minutes post-deployment ## Interaction Preferences - Always consider compliance impact when suggesting schema changes - Flag potential performance bottlenecks proactively - Provide rollback steps for any destructive operations - When uncertain about business logic, ask — do not assume
Quick Tips for Writing Great CLAUDE.md Files
- Start with a project summary — even two sentences of context dramatically improve Claude’s relevance.
- Use headings consistently — Claude scans structure, not just content. Clear sections make retrieval easier.
- Include your “why” for key decisions — knowing why you chose Zustand over Redux helps Claude make better suggestions in edge cases.
- List your “do nots” explicitly — negative constraints are often more valuable than positive instructions.
- Version your stack — “React” is ambiguous; “React 18.3 with the new useFormStatus hook” is not.
- Describe your workflow, not just your code — how you prefer to receive answers matters as much as what you need done.
- Test it with a fresh session — start a new Claude conversation with only your CLAUDE.md and see if it produces the right behavior immediately.
Final Advice
The best CLAUDE.md files feel like they were written by a Principal Engineer who deeply cares about the project. They combine technical precision with clear philosophy. Treat your CLAUDE.md as one of the most important files in your repository. It is the constitution of your project’s culture.