This paper outlines best practices for creating CLAUDE.md, a critical document designed to effectively onboard AI coding agents like Claude to a codebase during each interaction session. Given the stateless nature of Large Language Models (LLMs)—where they do not retain memory or learned information between sessions and operate with fixed weights during inference—all necessary context must be provided as input tokens for every new task. CLAUDE.md serves as the sole file automatically included in every conversation with Claude Code, making it the primary mechanism for re-onboarding the model to the project.

The core methodology revolves around optimizing the CLAUDE.md file to counteract LLM limitations, particularly their sensitivity to excessive or irrelevant instructions. Claude Code's system prompt explicitly states that supplied context "may or may not be relevant," allowing the model to disregard instructions if they are deemed unassociated with the current task, a behavior observed to improve output quality by Anthropic.

Key principles and technical considerations for an effective CLAUDE.md are:

1. Statelessness and Onboarding: Acknowledge that Claude begins each session with no prior knowledge of the codebase. CLAUDE.md bridges this gap by providing an "onboarding" overview covering the project's WHAT (technical stack, project structure, monorepo configuration), WHY (purpose and function of components), and HOW (build, test, and type-checking procedures). Crucially, this must be concise, including only the minimum necessary information, to avoid overwhelming the model.

2. Instruction Optimization ("Less is More"): LLMs have a limited capacity for reliably following instructions, generally around 150-200. Since Claude Code's internal system prompts already consume approximately 50 instructions, CLAUDE.md should contain only universal and essential directives. Over-instruction leads to a uniform degradation in the quality of instruction adherence across all directives. The paper suggests an analogy where adding more instructions dilutes the model's overall compliance capability.

3. Context Density and File Scope: LLMs perform better with focused and highly relevant context. As CLAUDE.md is always present, it must contain only broadly applicable information. Recommended length is under 300 lines, ideally shorter (e.g., <60 lines as per HumanLayer's example).

4. Progressive Disclosure: For complex or large projects, detailed instructions should not reside directly within CLAUDE.md. Instead, a progressive disclosure model is recommended:
   • Detailed guidelines (e.g., building, testing, code conventions) are moved into separate Markdown files (e.g., agent_docs/building_the_project.md).
   • CLAUDE.md then contains a directory or list of these files with brief descriptions, along with a directive for Claude to consult them when needed. This is conceptually similar to Claude Skills but focuses on instruction management rather than tool usage.
   • Instead of embedding code snippets, use file:line references to ensure currency and avoid redundant code copying.

5. LLM as Non-Linter: Claude should not be used as a code style linter. LLMs are expensive, slow, and non-deterministic for enforcing style guidelines. Code style is often inferred from existing patterns, and formatting can be automated by dedicated tools (e.g., Biome). Claude should receive already formatted code, with formatting automation handled by Stop Hooks or Slash Commands external to the LLM's direct instruction set.

6. Manual Crafting over Automation: CLAUDE.md should be meticulously hand-crafted, not automatically generated (e.g., via /init commands). This file represents the highest leverage point for the AI agent harness, where a single incorrect instruction can cascade into detrimental effects on overall code quality. Each statement must be carefully considered.

In essence, CLAUDE.md is a highly leveraged, minimalist, and carefully constructed initial prompt that efficiently re-onboards Claude to a project's core WHAT, WHY, and HOW for every session, minimizing noise and maximizing the agent's ability to follow relevant instructions.