How to write a CLAUDE.md / AGENTS.md that actually improves AI output

AI coding assistants perform wildly differently on the same codebase depending on one thing most developers ignore: whether the project has a context file telling the agent how the codebase actually works. A CLAUDE.md or AGENTS.md file is the closest thing to onboarding documentation for an AI teammate, and in 2026 it’s becoming the standard way to make agent output predictable instead of a guessing game.

What these files actually do

Before an agent touches your code, it reads this file if one exists at the project root. It’s plain Markdown, loaded automatically by tools like Claude Code, and increasingly by other agents that support the emerging AGENTS.md convention. Think of it as a briefing document: build commands, code conventions, things not to touch, and context that would take a new hire a week to learn by osmosis.

Why most first attempts fail

• They’re too vague (“write clean code”) instead of specific (“use named exports, never default exports”).
• They list aspirational rules nobody follows instead of describing the codebase as it actually is.
• They never mention what not to do, which is often more useful than style preferences.
• They go stale — nobody updates them after a major refactor, so the agent gets fed outdated instructions.

A template that works

Keep it short, concrete, and organized around the questions an agent actually needs answered before making a change.

# AGENTS.md

## Project overview
Node.js/Express API + React frontend. Monorepo with /server and /client.
Package manager: pnpm. Node version: 20.x.

## Build and test commands
- Install: pnpm install
- Dev server: pnpm dev
- Run tests: pnpm test (Vitest, must pass before any commit)
- Lint: pnpm lint --fix

## Code conventions
- TypeScript strict mode, no `any` unless justified with a comment.
- React: functional components only, hooks over classes.
- API routes live in /server/routes, one file per resource.
- Use named exports everywhere. No default exports.

## Testing rules
- Every new API route needs at least one integration test in /server/tests.
- Do not delete or skip existing tests to make a build pass.

## Things not to touch
- /server/legacy — frozen code, do not refactor even if it looks bad.
- Do not modify migration files after they've been merged to main.

## Git and PR conventions
- Commit messages: conventional commits (feat:, fix:, chore:).
- Keep PRs focused on one change; don't mix refactors with features.

## Environment
- Secrets live in .env, never commit them.
- Local DB: Postgres via docker-compose up.

Making it actually improve output

1. Write it from the codebase, not from a wishlist — describe real patterns, not ideal ones.
2. Update it whenever an agent makes the same mistake twice; that’s a signal the file is missing a rule.
3. Keep it under one page. Agents deprioritize instructions buried in long documents.
4. Put the highest-stakes rules (don’t touch this, don’t skip tests) near the top.

If you’re building a broader habit of working with AI agents rather than prompting them ad hoc, this file is one piece of a larger setup — see how to build a serious dev workflow around Claude for the rest.

Quick FAQ

Do I need both CLAUDE.md and AGENTS.md?

Not necessarily. Many teams symlink one to the other so every tool reads the same instructions without duplicating content.

Where should the file live?

At the project root by default. Larger monorepos can add nested versions in subdirectories for package-specific rules.

Will this work with any AI coding tool?

Support varies by tool, but the trend is converging on Markdown context files at the project root, so it’s worth maintaining one regardless.