notes on agents.md files

, , ,

Notes on AGENTS.md / CLAUDE.md

LLMs are stateless functions with frozen weights. They do not “learn” from your codebase over time.

The model only knows what is in its current “browsing history” the token stream. Context is Everything.

CLAUDE.md (or AGENTS.md) is usually the only file injected into every single session by default. It’s like a cast that helps you mold everything.

Since Claude starts every session with zero knowledge, CLAUDE.md must provide the What, Why, and How:

  • WHAT: The tech stack and project structure. Give Claude a “map” (especially for monorepos) so it knows where apps and shared packages live.

  • WHY: The purpose of the project. What is the goal of the different components?

  • HOW: Operational instructions. Specify tools (e.g., bun vs node), how to run tests, and how to verify builds.

Keep it minimal

Some coding agents like Claude Code include a system reminder telling the model to ignore context if it isn’t “highly relevant.” If you bloat the file with niche instructions, Claude may ignore it entirely.

Frontier models follow ~150–200 instructions reliably. Claude Code’s system prompt already uses ~50. Instruction Decay. Adding too many instructions causes the model to ignore all of them more frequently, not just the new ones.

It is therefore very important to keep the file under 300 lines (ideally <60).

Other thoughts that will help you craft great .md

Progressive Disclosure

Instead of stuffing every detail into one file, use pointers.

Keep task-specific docs in a directory like agent_docs/ (e.g., testing.md, schema.md).

List these files in CLAUDE.md with brief descriptions.

Instruct Claude to read these specific files only when relevant to the task.

CLIs / Scripts >> LLMs

Never use LLMs for tasks that deterministic tools can handle.

Do not put code style or formatting rules in CLAUDE.md.

Use linters/formatters (like Biome or ESLint).

Tip: Use a Stop hook to run a linter and feed the errors back to Claude to fix.

Manual curation

Do not auto-generate your CLAUDE.md. This file is the highest-leverage point in your workflow. Every line affects the agent’s research, planning, and coding phases. Spend the time to craft it manually.

Final thoughts

Treat CLAUDE.md as a high-level architectural map and a guide to finding information, rather than a dumping ground for every possible command.