Theo argues that repository-specific agent instruction files like CLAUDE.md and AGENT.md are often overused, frequently outdated, and can actively hurt coding-agent performance by adding irrelevant context and biasing the model toward wrong tools or patterns. He uses a recent study plus his own live tests in a real codebase to argue for minimal, high-signal instructions, better codebase architecture, and stronger tests instead of bloated prompt files.
Watch on YouTube ›Get the market thesis, key claims, assets, contradictions, and follow-up questions from any financial video — then unlock a version personalized to your portfolio, watchlist, and favorite speakers.
Theo frames the video around a simple provocation: if you are treating CLAUDE.md / AGENT.md files as essential, you may be making your coding agents worse. His core thesis is that these files often add noisy, misleading context that degrades performance, increases cost, and becomes stale quickly. He says the right default is not to stuff the file with every repo detail, but to keep it minimal and only use it when the agent repeatedly makes a specific, persistent mistake that cannot be fixed more cleanly elsewhere. He first explains how these files fit into the prompting hierarchy: provider instructions at the top, then system prompt, then developer message / agent-specific instructions, then the user prompt and conversation history. …
Near term, the actionable setup is to strip noisy repo instructions and compare agent performance against a minimal baseline, because stale guidance can immediately slow tasks and bias tool choice. The main risk is overfitting the file to today’s repo state instead of fixing the underlying workflow.
Over the next few weeks or months, the likely winning workflow is smaller agent docs, better tests, and clearer code structure that let the model infer the right path with less prompting. Validation comes from faster tasks, fewer wrong-tool choices, and fewer repeated mistakes; if those do not improve, the repo design still needs work.
The structural thesis is that coding agents will work best in environments designed for machine readability and strong feedback, not in repos maintained by large natural-language manuals. Over time, prompt files should become narrow exception lists rather than central operating documents.
Agent MD files will go out of date and become actively harmful rather than helpful.
Speaker argues that just like all other docs, agent MD files become outdated and then hurt rather than help.
Reducing the number of sources (context files, rules, MCP servers) makes it much more likely that the agent behaves correctly.
Speaker argues that eliminating unnecessary context sources helps diagnose why models do things wrong and improves agent behavior.
Using agent MD files leads to over 20% increase in cost, context, and time spent.
Speaker claims their one-off test and a published study both show cost increases of over 20% from steering agents via these files.
Is a video about skills something people would be excited about?
The speaker indicates he will do a long rant about skills in the near future and asks viewers to let him know if that's exciting and if the video is helpful.
Unlock the full claims, asset map, scores, related transcripts, follow-up questions, and AI chat — shaped around your portfolio, watchlist, favorite speakers, and risks.
