Skip to main content

Takeaways from "Writing a good CLAUDE(AGENTS).md"

https://www.humanlayer.dev/blog/writing-a-good-claude-md

All understanding of what LLMs (i.e., Claude, Copilot, etc.) can do revolves around this tenant: LLMs are stateless functions. They read your code, do some pattern matching to find possible equivalencies, spit something out, and then forget everything about your code until you ask a LLM to do something else for your codebase. 

In short, know that every time you ask a coding agent to do something:

  1. The agent will know absolutely nothing about your codebase
  2. The agent must be told anything that's important to know about your codebase

We educate coding agents with AGENTS.md files; Claude leverages CLAUDE.md files which is just the Anthropic version of AGENTS.md files. A good AGENTS.md file should describe:

  • What (languages, frameworks, libraries, etc. that you're using, the structure of your project, purpose and function of different modules in your project, etc.)
  • How (what patterns, coding styles, tooling, build steps, etc., do developers on the project use)

Keep the AGENTS.md file succinct - if there's too much in the file, coding agents like Claude will skip over it. For example, tools like Claude Code and Cursor will inject "reminders" to the agent to skip over reading the AGENTS.md file if there's not enough info in the file that's directly relevant to what's being asked of it.

The Humanlayer team speculates that it's Anthropic doing a little CYA because if a customer has a giant AGENTS.md file and Claude starts spitting out poor results, it's on Anthropic and not the customer making a giant AGENTS.md file.

Humanlayer suggests the following for good AGENTS.md files:

  • Less is more
    • Large LLMs can follow ~150-200 instructions in a prompt with reasonable consistency; this gets lower as the LLM gets smaller, and small LLMs will destabilize quickly
    • LLMs bias towards instructions at the start and at the end of the prompt; sorta like reading the intro and conclusion of an essay to get the gist of what a paper might be about
    • If a LLM passes instruction capacity, it won't just ignore instructions provided past capacity, it'll ignore EVERYTHING
    • Coding agents may already be providing instructions of their own to the LLM, eating into your instruction bandwidth, make your instructions count
  • "Less is more" also applies to AGENTS.md linecount, aim for less than 300 lines
  • Markdown files as inline documentation is back: add nested instructions for tasks like running tests and point to them in prompts and in your AGENTS.md file
  • Don't include code examples, but point to files and lines in the codebase with "file:line" structure
  • Don't include code style guidelines in your AGENTS.md file; the LLMs are good enough to pick up on it as a given LLM reads your codebase
  • Do not auto-generate your AGENTS.md file; any design mistakes made in it because it wasn't created by a developer will have knock-on effects if mistakes and bad implementations start slipping into generated code

 

 

 

 

 

 

 

 

Back to top