Practical Lesson 2 of 7

CLAUDE.md

CLAUDE.md functions as the primary configuration interface between a project and Claude Code. Its content is loaded automatically at the start of every session and influences all subsequent interactions within that project.

Effective CLAUDE.md content captures non-inferable project knowledge: conventions, constraints, and rationale that cannot be derived from the code alone.

Function and Scope

CLAUDE.md is a Markdown file placed at the project root. Claude Code reads it at session initialization, making its content available as persistent context across all conversations within the project. It serves as the project-level equivalent of a system prompt.

Design Principles

  • Conciseness: Approximately 150–200 lines is the recommended upper bound. Every line consumes context window capacity on every interaction.
  • Non-obvious information only: Omit facts that Claude can determine by reading the codebase (e.g., "components are in the components folder"). Include information that requires institutional knowledge.
  • Rationale over directive: "Use strict mode because production bugs resulted from type coercion" is more effective than "Use strict mode" alone. Rationale enables the model to generalize the principle.
  • Continuous evolution: Press # during a session to append instructions. A well-maintained CLAUDE.md reflects accumulated project learning.

Content Quality Comparison

Inferable (low value)

This project uses React for the frontend. Components are in the components folder. We use TypeScript. The API is in the api folder.

Non-inferable (high value)

Legacy API uses snake_case (do not change). New endpoints use camelCase. Auth tokens expire in 1hr — check expiry before API calls. Never use any in TypeScript.

The first example duplicates information available in the directory structure. The second captures conventions, edge cases, and prohibitions that would otherwise require a senior developer's guidance.

Recommended Content Categories

  • Project-specific conventions that diverge from framework defaults
  • Known pitfalls and their historical context
  • Canonical examples of common patterns within the project
  • Explicit prohibitions with rationale
  • Test execution commands and coverage requirements

Relationship to the Memory System

Claude Code also provides a persistent memory system that stores user preferences and cross-project knowledge. CLAUDE.md is project-scoped and version-controlled; memory is user-scoped and conversation-derived. The two mechanisms are complementary: CLAUDE.md captures team-shared project rules, while memory captures individual workflow preferences.

Key Takeaways

  • CLAUDE.md is loaded on every session — conciseness is a performance concern
  • Include only information not derivable from the codebase
  • Rationale enables the model to generalize directives
  • CLAUDE.md (project-scoped) and memory (user-scoped) are complementary persistence layers