Rethink CLAUDE.md: It's Not a README

The common instinct is to treat a CLAUDE.md file as a comprehensive project bible, akin to a README.md. This is a fundamental misunderstanding of how large language models like Claude process information. While a human might skim a README for specific sections, Claude reads the entire CLAUDE.md file on every interaction. This means every line of text competes for the model's limited attention within its context window. Adding extraneous information, like verbose explanations of standard SwiftLint rules or lengthy architectural debates, dilutes the impact of the critical directives you want Claude to follow.

Consider a 400-line CLAUDE.md file. By the time Claude reaches rules buried near the bottom, they're competing with hundreds of other lines for processing priority. This often leads to the model overlooking or misinterpreting crucial, yet late-stage, instructions. The key takeaway is that a CLAUDE.md file is not a documentation repository; it's a highly optimized instruction set for an AI. Reducing a file from 400 lines to a focused 60 lines, while retaining only the essential, non-obvious conventions, can dramatically improve Claude's adherence to the rules that truly matter for a specific team and codebase.

Conceptual diagram illustrating Claude's attention dilution with longer context files.

What Earns a Line in Your CLAUDE.md

The principle guiding what to include is simple: non-obvious conventions. If a rule or convention is easily inferable from standard iOS development practices, SwiftLint configurations, or widely accepted architectural patterns (like MVVM or TCA when used in their typical implementations), it likely doesn't belong in your CLAUDE.md. These standard practices are often already part of Claude's training data or can be easily inferred if the context is clear.

Focus on the idiosyncratic rules that make your project unique and are not immediately apparent. These are the details that separate your project's specific requirements from general best practices. For instance:

  • Specific Naming Conventions Beyond Standard Practices: If your team uses a unique prefix for certain types of view models, or a particular suffix for observable properties that deviates from common Swift patterns, document it.
  • Domain-Specific Terminology: If your application deals with a niche industry and uses specific terms for concepts that might be ambiguous (e.g., 'session' could mean different things in different contexts), clarify your project's definition.
  • Unconventional Architecture Choices: While full architectural debates belong elsewhere, if you've made a specific, non-standard choice within a common architecture (e.g., a particular way of handling data flow in MVVM that differs from the textbook example), a concise note is warranted.
  • Edge Case Handling Specific to Your App: Detail how your app handles unique edge cases that are critical for its functionality but wouldn't be obvious from general programming knowledge.
  • Custom Tooling or Workflow Specifics: If your team uses custom scripts or specific command-line tools for development tasks that influence code generation or validation, briefly mention their purpose and expected output.

Each line included should justify its existence by addressing something that Claude, without explicit instruction, would be unlikely to infer or might misinterpret based on its general training. Think of it as providing guardrails for the AI that are specific to your team's established norms and the subtle nuances of your project.

What to Leave Out: The Documentation Trap

The trap is to dump all your project documentation into CLAUDE.md. This is counterproductive. Here's what to exclude:

  • General Architectural Explanations: Detailed breakdowns of MVVM, TCA, or any other architectural pattern should reside in your project's main documentation or wiki. Claude's understanding of these patterns is likely sufficient; it needs to know how *your team* applies them, not the theory behind them.
  • Redundant Style Guides: If you are using SwiftLint or any other linter, its configuration file is the source of truth for coding style. Simply stating "follow SwiftLint rules" is adequate. Replicating SwiftLint rules in prose within CLAUDE.md is redundant and wastes valuable context space.
  • Obvious Conventions: Standard Swift naming conventions (e.g., `camelCase` for variables, `PascalCase` for types), standard library usage, or common API patterns do not need to be reiterated.
  • Project History or Philosophy: While important for human onboarding, the historical context of why certain decisions were made or the overarching philosophy of the project are generally not critical for Claude's day-to-day code generation or review tasks.
  • External Library Documentation: Unless your project uses a library in a highly unconventional way that requires specific instruction, Claude can typically access or infer information about standard libraries.

The goal is to be concise and impactful. Imagine you have only 60 seconds to tell Claude the absolute most critical rules it must follow to write code for your project. What would you say?

Structuring for Maximum Impact

Organize your CLAUDE.md logically to ensure clarity and immediate comprehension by the AI. Start with a brief, high-level summary of the project's primary goal or domain, if it aids context. Then, move directly into the core conventions.

A good structure might look like this:

  1. Core Objective/Domain: A single sentence defining the app's main purpose.
  2. Critical Non-Obvious Conventions: Bulleted list of specific, unique rules.
  3. Key Architectural Nuances: Very brief notes on how your team deviates or emphasizes specific aspects of your chosen architecture.
  4. Data Handling Specifics: Any unique requirements for data persistence, network responses, or data transformation.
  5. API Usage Guidelines: Specific instructions for interacting with critical internal or external APIs.

Avoid deep dives. Keep descriptions brief and to the point. Each point should be actionable and directly inform Claude's code generation or review process. If a point requires more than a sentence or two to explain, it might be too complex for CLAUDE.md and should be documented elsewhere, with a concise pointer in CLAUDE.md.

The Iterative Refinement Process

Creating an effective CLAUDE.md is an iterative process. Start lean, observe Claude's performance, and refine. The initial 400-line file was an attempt to document everything. The subsequent reduction to 60 lines, driven by observed performance issues, highlights the necessity of trimming the fat. Over time, as you identify specific areas where Claude struggles or deviates from team standards, you can add precisely targeted instructions. This iterative refinement ensures the CLAUDE.md remains a potent, focused tool rather than a bloated, ineffective document.

If you run an iOS team using AI coding assistants, actively monitor their output against your project's unique standards. When deviations occur, analyze whether the instruction was missing, unclear, or buried in too much other text. This feedback loop is crucial for optimizing your CLAUDE.md file. Treat it as a living document, but one that thrives on conciseness and specificity, not verbosity.