CLAUDE CODE

How I Write CLAUDE.md Files That Actually Work

A practical guide to writing CLAUDE.md files that Claude Code actually follows, with real production examples from my Next.js portfolio site and the mistakes I learned the hard way.

What Is a CLAUDE.md File?

CLAUDE.md is a Markdown file that provides project-specific instructions to Claude Code. When you start a session, Claude reads every CLAUDE.md file it finds - from your global config to your project root to nested subdirectories - and uses those instructions as context for the entire conversation. Think of it as a README, but written specifically for your AI coding partner.

According to JetBrains' 2026 developer survey, 40.8% of developers using AI agents use Claude Code - the most popular AI coding agent. Yet many users never create a CLAUDE.md file, leaving significant productivity gains untapped.

The Hierarchical Loading System

Claude Code loads CLAUDE.md files from multiple locations, with more specific files taking precedence over general ones:

~/.claude/CLAUDE.md              # Global - your personal preferences across all projects
/project-root/CLAUDE.md          # Project - shared team standards (commit to repo)
/project-root/.claude/CLAUDE.md  # Project - alternative location
/project-root/src/CLAUDE.md      # Subdirectory - scoped rules for a specific area

I use the global file for personal preferences (editor style, commit message format) and the project-level file for architecture rules specific to each codebase.

My Production CLAUDE.md: A Line-by-Line Breakdown

This is the actual CLAUDE.md from avinashsangle.com, a Next.js 16 static site with shadcn/ui deployed to GitHub Pages. Every rule exists because Claude made a specific mistake without it.

The Project Overview and Commands

# CLAUDE.md
This file provides guidance to Claude Code when working with this repository.

## Project Overview
Personal portfolio website - Next.js 16 static site with shadcn/ui,
deployed to GitHub Pages via GitHub Actions.

## Tech Stack
- Framework: Next.js 16 (App Router) with static export
- Styling: Tailwind CSS 4 with shadcn/ui components
- Icons: Lucide React (replaced emojis throughout)
- Deployment: GitHub Pages via GitHub Actions

## Development Commands
```bash
npm run dev    # Dev server on localhost:3000
npm run build  # Static export to ./out folder
npm run lint   # ESLint
```

The tech stack section prevents Claude from suggesting incompatible patterns - like server-side rendering or API routes that would break the GitHub Pages deployment.

The Hard Constraints That Prevent Real Mistakes

## Critical Architecture Rules

### 1. Static Export - NO Server Features
**CRITICAL:** All pages must be statically exportable.
No server-side rendering, API routes, or getServerSideProps.

next.config.ts must stay as:
  output: 'export'
  trailingSlash: true
  images: { unoptimized: true }

### 2. shadcn/ui Components - DO NOT MODIFY
**CRITICAL:** NEVER modify files in src/components/ui/
These are installed via CLI and must stay pristine.

Style changes go in:
- src/app/globals.css       (global styles)
- src/app/**/page.tsx       (Tailwind classes on elements)
- src/components/navbar.tsx (layout components)

### 3. Icons - Lucide Only, No Emojis
Use CategoryIcon from @/components/icons/category-icon
NEVER add emoji characters to any file

Showing Patterns - More Effective Than Rules

The most effective section in my CLAUDE.md is the page structure template. Rather than listing abstract rules, I show Claude exactly what a well-formed page looks like. According to Anthropic's 2026 Agentic Coding Trends Report, AI is projected to generate 60% of code by end of 2026. Templates ensure that generated code matches your established patterns from day one.

## Common Patterns

### New Blog Article Checklist
1. Create: src/app/blog/[slug]/page.tsx
2. Add metadata export (title 55-65 chars, description 130-160 chars)
3. Add TechArticle + BreadcrumbList + FAQPage JSON-LD schemas
4. Update src/app/blog/page.tsx with new article card
5. Update src/app/sitemap.ts with new slug

### Required JSON-LD Author Object (all articles)
{
  "@type": "Person",
  "name": "Avinash Sangle",
  "url": "https://avinashsangle.com",
  "sameAs": ["https://www.linkedin.com/in/avinashsangle", ...]
}

7 CLAUDE.md Mistakes That Waste Your Tokens

After iterating through dozens of CLAUDE.md versions and reading hundreds shared on r/ClaudeAI, these are the patterns that consistently cause problems. Files over 200 lines can consume 30-40K tokens at session start - real cost when paying per token on the API plan.

Do NOT use semicolons.
Do NOT add console.log statements.
Do NOT import from relative paths.

Style: no-semicolon (Prettier enforces this).
Logging: use logger from "@/lib/logger".
Imports: use path aliases (@/components/...).

- Use async/await instead of callbacks
- Use const for immutable variables
- Add error handling to async functions
- Use TypeScript for type safety

- Validation: use Zod (not io-ts or yup)
- Error boundaries: src/components/error-boundary.tsx
- API calls: always via src/lib/api-client.ts
- Dates: use date-fns (not moment.js)

# Instead of pasting 300 lines of API documentation:
See @docs/api-reference.md for all endpoint specifications.
See @README.md for project setup and background.

**CRITICAL:** NEVER modify files in src/components/ui/
**Important:** All pages must be statically exportable.
**Note:** Prefer named exports for components.

How I Keep My CLAUDE.md Fresh

CLAUDE.md files rot. Rules that were essential 3 months ago may now be irrelevant, and gaps accumulate as the project evolves. Research shows that AI-cited content is 25.7% fresher on average than traditional organic results - the same freshness principle applies to the instructions your AI reads.