Stop using AGENTS.md and CLAUDE.md (do this instead)

Do “repo-level context files” like CLAUDE.md and AGENT.md files actually make a difference for agentic coding tasks?

Well yeah. But not necessarily in a helpful way.

I looked at some recent research on the topic and pulled out some tips to make these files more effective.

Here’s the video on YouTube

By the way—you can reach out to me directly at alex@zazencodes.com if you want to get in touch.

By the way, I’ve got my the full 12+ hour AI Engineering video course on sale for 30% off until Match 31st. Use code ZAZEN30 at checkout.

This week is the LAST chance to get this sale. I won’t run another one until the end of the year.

Topics from this week’s video

• Repository-level context files for coding agents

  • Files like CLAUDE.md and AGENTS.md that give instructions to coding agents

  • Separate from README files meant for human developers

  • Often contain project rules, structure notes, and workflow guidance

  • Many generated versions become overly long and repetitive

• Research on whether these files actually help

  • Study comparing three scenarios:

    • No context file

    • Developer-written context file

    • LLM-generated context file

  • Evaluated using coding-agent benchmarks on real repository tasks

• Key results

  • Developer-written files slightly improved performance

  • LLM-generated files slightly reduced performance

  • Context files increased token usage and inference cost

• Practical recommendations

  • Keep context files short and focused

  • Avoid repeating information already in the README

  • Include only agent-specific instructions or constraints

• Demo on a real project

  • Implementing a newsletter feature on a personal website

  • Comparing coding agent performance with and without a CLAUDE.md file

---

A scientist in his laboratory is not only a technician: He is also a child placed before natural phenomena which impress him like a fairy tale.

Marie Curie