Skip to content

why-claude-md.md

Latest commit

 

History

History
65 lines (46 loc) · 2.59 KB

why-claude-md.md

File metadata and controls

65 lines (46 loc) · 2.59 KB

Why CLAUDE.md Matters

The Problem

Without project-level instructions, Claude Code:

  • Generates code that doesn't match your style conventions
  • Uses packages or APIs you don't want in your project
  • Makes architectural decisions that conflict with your design
  • Loses context between sessions — you repeat the same instructions

The Solution

CLAUDE.md is a configuration file that Claude Code reads at the start of every session. It acts as persistent project memory.

What to Include

Essential (start here)

  • Project overview — what this project does, in 1-2 sentences
  • Tech stack — framework, language, package manager
  • Commands — how to build, test, lint, and run
  • Prohibited actions — things Claude should never do

Recommended (add as needed)

  • File structure — where components, utils, and configs live
  • Coding standards — naming conventions, patterns to follow
  • Session workflow — what to read first, what to check before committing

Advanced

  • Model assignment — which AI models handle which tasks
  • Pipeline phases — multi-step workflows with approval gates
  • Rules files — .claude/rules/*.md for topic-specific guidelines

Key Principles

  1. Be specific. "Write clean code" is useless. "Use named exports, no default exports" is actionable.
  2. Include the why. Rules without reasons get ignored when they seem inconvenient.
  3. Keep it current. Outdated instructions are worse than no instructions.
  4. Layer your config. Use CLAUDE.md for essentials, .claude/rules/ for detailed topic rules.

File Hierarchy

Claude Code reads instructions from multiple levels:

~/.claude/CLAUDE.md              # User-level (your personal preferences)
project/CLAUDE.md                # Project-level (shared with team)
project/.claude/rules/*.md       # Topic-specific rules (auto-loaded)
project/.claude/settings.json    # Permissions and tool access
project/.claude/commands/*.md    # Custom slash commands

Project-level files override user-level. Rules files are always loaded alongside CLAUDE.md.

Real-World Example

A tech blog (32blog.com) uses this structure to manage 120+ articles across 3 languages:

  • CLAUDE.md — project overview, tech stack, session workflow
  • .claude/rules/article-pipeline.md — 7-phase content pipeline with model assignments
  • .claude/rules/token-saving.md — context window optimization
  • .claude/commands/review.md — code review slash command
  • .claude/settings.json — safe permission defaults

The result: consistent quality across sessions, even when context is lost.