Writing a Good Claude.md (www.humanlayer.dev)

This post explains how to write an effective CLAUDE.md (and AGENTS.md) to onboard Claude-based coding agents to your repository, emphasizing that LLMs are essentially stateless functions: they don’t “remember” your codebase between sessions and only know what you include in the prompt. Because Claude Code injects a system reminder that may cause the model to ignore context it deems irrelevant, CLAUDE.md must be concise, universally applicable, and focused on WHAT (tech stack and repo map), WHY (project purpose), and HOW (how to build, test, and verify changes). Overly long or task-specific instructions will likely be ignored or degrade instruction-following performance; practical heuristics include keeping files under ~300 lines (many teams use far fewer), avoiding auto-generated CLAUDE.md, and not expecting the model to replace deterministic linters/formatters. Technically, the post highlights prompt-engineering and harness design trade-offs: Claude Code’s system prompt already contains ~50 instructions, frontier models reliably follow ~150–200 instructions before quality drops, and smaller models degrade much faster. Recommended practices are Progressive Disclosure (store task-specific docs separately and give Claude pointers or file:line references), use Stop hooks or Slash Commands to run linters/formatters (e.g., Biome) and present errors rather than having the LLM do linting, and let the agent request which supplementary files to read. These patterns reduce context bloat, improve reliability, and make agent behavior more predictable for production ML/engineering workflows.