George Nurijanian: Best practices for writing CLAUDE.md and AGENTS.md files

As AI coding agents and product management automation tools become part of everyday work, product teams are learning that how you write instructions for those agents matters as much as what tools you choose. This article from George Nurijanian, published in April 2026 as part of his PM OS newsletter, makes the case that the instinct to write exhaustive context files for AI agents backfires — and explains what works instead.

The core claim is supported by research from ETH Zurich: auto-generated CLAUDE.md files that were long and detailed reduced task success rates by 3% and increased token costs by 20% compared to shorter, hand-crafted files. The reason is structural. AI agents operate with approximately 100 usable instruction slots after accounting for system prompts. A longer context file dilutes instruction fidelity uniformly — every additional line makes all other lines slightly less reliable.

What to include

Nurijanian identifies a small set of elements that genuinely improve agent performance. A clear project description and target users. The exact technology stack with specific version numbers. CLI commands for common tasks, written precisely rather than described generally. Conventions that a linter would not catch — things like naming patterns or API call ordering. And hard constraints written as explicit prohibitions (“NEVER” statements), which agents treat as higher-priority signals than softer guidance.

What to leave out

Directory trees, auto-generated content, and full API documentation should not appear in a CLAUDE.md file. If documentation exists elsewhere, link to it. Vague persona instructions (“you are an expert PM assistant”) add noise without improving results. Rules that a linter already enforces are redundant — the agent doesn’t need to be told what the toolchain already handles.

Structural guidance

The recommended root CLAUDE.md file stays under 80 lines. For larger codebases or multi-domain projects, scope-specific guidance belongs in .claude/rules/ subdirectories rather than bloating the root file. The article also recommends writing AGENTS.md as the source of truth and importing it into CLAUDE.md, so agent-specific instructions remain separate from project documentation that humans read.

One practical habit: update context files after each correction. If an agent makes a repeatable mistake and you correct it manually, adding a “NEVER” statement prevents the same error in subsequent runs. Treating the context file as a living document that reflects real failure modes is more effective than writing it from scratch based on anticipated needs.

Who this is for

Product managers who use Claude Code, Cursor, or similar agent tools for their own work — documentation, research synthesis, PRD drafting, or workflow automation — will get immediate value from this. Engineering leads who are standardizing how their product team interacts with AI agents will also find the structural guidance useful. The principles apply across tools, not just Anthropic’s ecosystem.