# Writing a good CLAUDE.md Source: https://www.youtube.com/watch?v=HhrZ3X7cu2Q Recap page: https://rapidrecap.app/video/HhrZ3X7cu2Q Generated: 2025-12-06T16:03:01.71+00:00 --- ## Quick Overview The key to writing a good Claude.md file for AI agents is to ensure the main context file is concise, universally applicable, and acts as an index, explicitly guiding the agent to reference specific, up-to-date source code files (like schema.md or protocol.md) rather than relying on potentially outdated information embedded within the context itself. **Key Points:** - The core problem is that LLMs inherently favor context provided early and late in the prompt (recency bias), causing them to ignore vital rules if they appear in the middle of extensive context. - For complex enterprise projects, context files (like Claude.md) should be concise, ideally under 150 to 200 instructions, acting as an index rather than containing all necessary operational knowledge. - A key solution is to use a 'stop hook' in the agent's code (like `CLAUDE.md`) that runs after code generation but before execution, allowing the agent to check if the generated code adheres to the rules. - The best practice is to reference external, current source files (like schema.md or protocol.md) directly, ensuring the agent uses the most up-to-date information, rather than pasting large chunks of code into the main context. - The speaker argues that the simple, rule-based linter approach is insufficient; agents need deterministic tools like Bison or ESLint to automatically fix formatting or syntax issues. - The ideal structure separates high-level project understanding (the main context file) from low-level, frequently updated implementation details (referenced files). ![Screenshot at 00:16: The speaker explicitly discusses the necessity of guiding the agent to use the correct context management system, referencing the need to optimize the central nervous system for tools like Claude code.](https://ss.rapidrecap.app/screens/HhrZ3X7cu2Q/00-00-16.png) **Context:** This podcast segment discusses best practices for structuring context files, specifically 'Claude.md', when developing AI agents using large language models (LLMs) like Claude. The speakers highlight the common frustration where agents, despite having clear instructions, often ignore critical rules if those rules are buried within a massive context window, leading to errors in code generation or adherence to project standards. ## Detailed Analysis The discussion centers on effective context management for AI agents, specifically using a file like 'Claude.md'. The primary takeaway is that context files should function as concise indexes rather than comprehensive manuals. The speaker notes that LLMs exhibit a strong bias towards information at the beginning and end of the context window, causing them to forget or ignore critical rules embedded in the middle, especially when the context is large (e.g., over 150-200 instructions). This leads to agents ignoring critical rules like not exposing API keys or following specific formatting guidelines, resulting in poor performance or security risks. The suggested solution involves using a 'stop hook' in the agent's code that runs post-generation but pre-execution to check rules, and structuring the project so the main context file only points to the latest source code files (like schema.md or protocol.md) for specific details, thereby keeping the main context lean and focused. The ideal is to use deterministic tools for fixing issues rather than relying on the LLM's inherent biases or simple rule-checking. ### Context Management Failures - Developers often dump hundreds of lines of text into the context window, causing the agent to ignore crucial instructions buried in the middle due to context window bias. ### The Core Problem - LLMs favor information at the start and end of the context, leading to agents forgetting the most important rules, like never exposing API keys. ### The Solution - Keep the main context file (Claude.md) concise (aiming for under 150-200 instructions), making it an index that points to the actual, up-to-date source code files (e.g., schema.md, protocol.md). ### Implementation Details - Use a 'stop hook' that runs after code generation but before execution to enforce critical rules (like never pasting code snippets into markdown files). ### Tooling - Rely on deterministic tools like Bison or ESLint for formatting and syntax fixing, rather than relying on the agent to self-correct, which often fails. ![Screenshot at 00:05: The initial discussion focuses on deep-diving into context management for AI coding agents.](https://ss.rapidrecap.app/screens/HhrZ3X7cu2Q/00-00-05.png) ![Screenshot at 00:18: The speaker mentions specific source files like cloudcode.io.ud, which should be referenced rather than included fully in the context.](https://ss.rapidrecap.app/screens/HhrZ3X7cu2Q/00-00-18.png) ![Screenshot at 00:53: The speaker contrasts treating LLMs like junior developers who need constant hand-holding versus treating them like contractors who need clear, concise direction.](https://ss.rapidrecap.app/screens/HhrZ3X7cu2Q/00-00-53.png) ![Screenshot at 03:37: Visual reinforcement of the problem: the agent's own code \(Claude code CLI\) is adding its own notes, showing a failure to adhere strictly to the original instructions.](https://ss.rapidrecap.app/screens/HhrZ3X7cu2Q/00-03-37.png) ![Screenshot at 05:24: The speaker explains that larger models show a linear decay in performance degradation, while smaller models show an exponential decay when context rules are ignored.](https://ss.rapidrecap.app/screens/HhrZ3X7cu2Q/00-05-24.png)