Claude.md Examples and Best Practices: A Complete Guide for Claude Code Users

June 10, 2026 · ☕ 6 min read

Claude.md Examples and Best Practices

If you use Claude Code without a Claude.md file, the AI starts every session cold. It does not know your project structure, your coding standards, or which files it should never touch. A Claude.md file fixes that. If you haven’t set up Claude Code yet, start with the installation guide.

Think of it as a permanent note pinned to your repository. Instead of telling Claude the same things over and over (how the project is structured, what technologies you use, which files are off limits), you write it once and let Claude read it.

This guide covers what Claude.md is, real examples for different projects, and common mistakes to avoid.

What is Claude.md?

Claude.md is a file Claude Code reads when it starts working in your repository. It works like a permanent system prompt for your project. Every time Claude starts a new session, it sees these instructions without you having to repeat them.

Why bother?

Without Claude.md:

Every session starts with limited context
The AI may generate inconsistent code
Architecture decisions drift between sessions
Refactoring becomes hit or miss

With Claude.md, you get faster development, more consistent output, and less repetition. For a project you work on regularly, the time spent writing the file pays for itself in a few sessions.

Where does it go?

Put it in the project root:

my-project/
  ├── src/
  ├── public/
  ├── package.json
  ├── astro.config.mjs
  └── Claude.md

The root is the easiest place for both humans and Claude to find it.

Example 1: Minimal Claude.md

For a small project, keep it short:

# Project Instructions

## Tech Stack
- Astro
- TypeScript
- Tailwind CSS

## Coding Standards
- Use TypeScript whenever possible
- Prefer functional components
- Avoid unnecessary dependencies

## SEO Requirements
- Include descriptive meta titles
- Include meta descriptions
- Use semantic HTML

## Restrictions
- Do not modify package.json without permission

Even this much helps. Claude knows the stack and the rules from the first prompt.

Example 2: Claude.md for an Astro Blog

If your site is SEO-focused, expand the file to cover content guidelines:

# Project Overview
Personal blog built with Astro.

## Content Guidelines
- All articles require frontmatter
- Include title and description
- Add tags
- Add canonical URLs

## SEO Requirements
- Optimize heading hierarchy
- Use only one H1
- Internal linking is encouraged
- Add image alt text

## Performance Rules
- Minimize JavaScript
- Prefer static rendering
- Avoid unnecessary client hydration

## Before Modifying Code
Explain:
1. What will be changed
2. Why it is needed
3. Potential side effects

This tells Claude to think about SEO and performance before generating output.

Example 3: Claude.md for Power Users

Advanced users add workflow rules:

# Workflow Rules
Before making any change:
1. Analyze the existing architecture
2. Identify affected files
3. Explain the implementation plan

After making changes:
1. Verify imports
2. Check build compatibility
3. Check for duplicate logic
4. Summarize modifications

## Code Quality
- Follow DRY principles
- Prefer reusable components
- Avoid code duplication

## Git Workflow
Never perform git push, git force-push, or branch deletion without explicit permission.

This reduces the chance of Claude making unexpected repository changes.

For content marketing workflows:

# Content Creation Rules
Every article must include:
- SEO title
- Meta description
- Canonical URL
- Target keyword
- Internal link opportunities

## Writing Style
- Clear and practical
- Use short paragraphs
- Use descriptive subheadings

## Formatting
- One H1 only
- H2 for major sections
- H3 for supporting topics

## SEO Goals
- Search intent alignment
- Topical authority
- Helpful content

This keeps AI-generated content consistent with your SEO strategy.

Best practices

Keep instructions specific. “Write good code” is useless. “Use TypeScript strict mode, avoid any types, prefer reusable utility functions” gives Claude something to act on.

Focus on long-term rules. Claude.md should document stable project requirements: coding standards, architecture decisions, SEO rules, workflow requirements. Temporary tasks like “fix navbar bug” belong in a prompt.

Protect critical files. If there are files Claude should never modify, say so explicitly. Deploy configs, package.json, and cloud platform settings are common candidates.

Define a workflow. Tell Claude how you want changes communicated. Many users ask Claude to explain the plan and list affected files before editing, then provide a summary afterward.

Document the project structure. A quick overview of what each directory contains helps Claude navigate the codebase faster.

Common mistakes

Making the file too large. A 5,000 word instruction file is counterproductive. Stick to architecture, standards, and constraints.

Repeating the same rule multiple times. One clear instruction beats three repetitions.

Storing temporary tasks. Claude.md is not a to-do list. Bug fixes and one-time changes go in your prompt. Claude.md holds project-wide rules that outlast a single session.

A production-ready template

# Project Overview
Project Type: [describe project]
Tech Stack:
- Astro
- TypeScript
- Tailwind CSS

# Coding Standards
- Use TypeScript
- Avoid duplicated logic
- Prefer reusable components

# SEO Rules
- One H1 per page
- Descriptive meta titles
- Meta descriptions required
- Internal linking encouraged

# Performance
- Minimize JavaScript
- Prefer static generation
- Optimize images

# Restrictions
Do not modify package.json or deployment configuration without permission.

# Communication
Before making changes:
1. Explain the plan
2. List affected files

After making changes:
1. Summarize modifications
2. Highlight risks

Final thoughts

A well-written Claude.md is one of those setup tasks that feels optional until you try it. Once Claude starts following your conventions without being reminded, the time you invested in the file comes back quickly.

If you use Claude Code regularly, take 15 minutes to write a Claude.md. It is infrastructure, not optional.

Related articles:

Install Claude Code — Get Claude Code running on your machine
Add vision capabilities — Enable image recognition in Claude Code

Newman

Writer and builder at BePhil. Passionate about design systems, frontend engineering, and clear thinking.