Delete your CLAUDE.md (and your AGENT.md too)

Too Long; Didn't Watch — Summary

Recent studies and real-world tests show that CLAUDE.md and agent.md files often degrade AI coding performance and increase costs by 20%, suggesting that developers should prioritize a clean codebase over bloated instruction files.

Main Takeaways

• Performance Degradation: LLM-generated context files can decrease task success rates by approximately 3% while increasing compute costs by over 20% due to unnecessary exploration.
• The Hierarchy of Priority: AI models follow a strict hierarchy: Provider Instructions > System Prompt > Developer Message (Agent MD) > User Prompt.
• Context Distraction: Providing redundant information already present in the codebase (like package scripts or basic architecture) distracts the model and leads to 'hallucinations' or incorrect steering.
• Codebase as Documentation: Models are highly proficient at using tools like grep or reading package.json; if an agent struggles to find something, the solution is usually to fix the code structure, not the MD file.
• Strategic Misdirection: Effective 'AI engineering' sometimes involves 'lying' to the agent (e.g., claiming a project is greenfield) to prevent it from over-complicating tasks with legacy constraints.

Detailed Summary

The Failure of Agent Context Files (0:00 - 03:46)

Recent research comparing models like Sonnet 3.5 and GPT-4o reveals that providing agent.md or CLAUDE.md files consistently leads to worse performance. Many developers feel their prompts fail because they lack these files, but the data suggests these files often steer models incorrectly. The video introduces the concept of context management as the core challenge in modern AI-assisted coding.

Understanding the Prompt Hierarchy (03:47 - 10:15)

Context files function as a 'Developer Message' layer between the system prompt and the user prompt.

• Provider Instructions: Top-level safety and operational rules (e.g., 'don't build weapons').
• System Prompt: Defines the agent's core persona and capabilities.
• Developer Message: Where agent.md lives, providing repo-specific rules.
• User Prompt: The specific task requested by the developer. Everything in this hierarchy consumes tokens and costs money, meaning every line of text must justify its existence.

The Cost of Distraction (10:16 - 14:13)

Models are 'autocomplete machines' that can be easily distracted by irrelevant details. Mentioning legacy technologies (like TRPC in a Convex-based repo) biases the model toward using them incorrectly. The 'Pink Elephant' effect applies: telling a model not to do something ensures it is thinking about that very thing. The study cited shows that developer-provided files only improve performance by 4%, while LLM-generated ones actively hurt it.

Live Experiment: With vs. Without CLAUDE.md (14:14 - 23:32)

A live test on a project called 'Lawn' compares an agent's performance with and without a generated CLAUDE.md.

• Without the file: The agent took 1 minute and 11 seconds to explore and answer.
• With the file: The agent took 1 minute and 29 seconds (a 25% time penalty). This demonstrates that agents are already skilled at exploring file structures and reading package.json without being told where things are in a separate document.

Best Practices for Context Management (23:33 - 27:26)

The best use for an agent.md is as a 'band-aid' for consistent mistakes the model makes.

• Audit regularly: Delete the file and see if the model still functions; if it does, keep it deleted.
• Steer away from errors: Only include patterns the model repeatedly gets wrong.
• Fix the source: If a model can't find a file, move the file to a more logical location rather than documenting its 'bad' location in an MD file.

Advanced Tactics and Conclusion (27:27 - 29:13)

Developers can use 'clever engineering hacks' like asking for 'Step 3' of a process to force the model to unblock itself on 'Step 2'. Reducing the sources of information (MCP servers, skills, and rules) makes it easier to diagnose why a model is failing. The ultimate goal is to build an intuition for model behavior rather than relying on static, often outdated, documentation files.

Notable Quotes

"If the info is in the codebase, it probably doesn't need to be in the agent MD file."

"The agent MD is almost like a band-aid solution... you're patching over this problem with it."

"Whatever you put in context is much more likely to happen. It's all an autocomplete machine."