Markdown and project instruction files (CLAUDE.md, AGENTS.md, and friends)

Open a healthy engineering repo and you will find more markdown than anyone admits in the all-hands. README for humans. CONTRIBUTING for process. Architecture Decision Records for the historians. Somewhere near the root, a file with a product name in capital letters that exists only so an agent stops inventing a second package manager.

This is Part 6 of the Claude Code tutorial: markdown and project instruction files. Part 5 covered what sticks and what resets (session chat, CLAUDE.md, auto memory, git as source of truth). Here we get concrete about CLAUDE.md, AGENTS.md, README, and the friends that show up in multi-tool workflows. You will leave with a pasteable skeleton, a division of labor table, and one rule that saves more pain than any template: short true beats long aspirational.

What you will learn

• What each common instruction file is for (and who is the primary reader)
• How Claude Code loads CLAUDE.md versus how other agents use AGENTS.md
• What belongs in a project brief, commands, style, and safety sections
• How to keep README human without starving the agent of facts
• A sample CLAUDE.md you can thin for your stack
• Failure modes: novels, contradictions, and “documentation theater”

Details track Anthropic’s public docs on memory and CLAUDE.md and related feature pages. Other tools evolve their own conventions for AGENTS.md and rule files. Confirm your client’s docs before you make a company standard. When in doubt, put shared truth in git where every tool can read a file.

Why instruction files exist at all

Agents do not magically inherit your team’s folklore. Session chat resets with /clear or a new session (Part 5). Auto memory can carry some learnings if enabled, but it is not a substitute for committed team rules. Instruction files are how you say, once, in a place the next session will load: here is the project, here are the commands, here is the style, here is what you must not do.

Humans need a different cut of the same truth. A new hire opens README to learn what the product is, how to install, and where the docs live. They do not need a bullet that says “use 2-space indentation” if the formatter already enforces it. Agents benefit from checkable constraints. Humans benefit from motivation, diagrams, and “why we did it this way.” Trying to make one file serve both audiences at full volume usually produces a 2,000-line swamp that neither party reads.

The cast of characters

README: for humans first

README is the front door. It answers: what is this, how do I run it, where is more detail, who owns it. Good READMEs are written for a tired person on day one. They can include architecture sketches and links. They should not become a dumping ground for every agent micro-preference, because humans stop scrolling and agents still need a denser brief elsewhere.

Practical split:

• README: purpose, prerequisites, install, common scripts, link to deeper docs
• CLAUDE.md: agent-facing constraints and the short command list Claude should not invent
• Both can mention the same test command. Duplication of a one-liner is fine. Duplication of a 40-line essay is how drift starts.

CLAUDE.md: project brief for Claude Code

Claude Code reads CLAUDE.md (and related paths such as .claude/CLAUDE.md, user-level ~/.claude/CLAUDE.md, local CLAUDE.local.md, managed org files). Official docs: you write these files; Claude loads them at session start; content is guidance in context, not a hard sandbox. Keep them specific and concise. Prefer facts that prevent repeated mistakes: build commands, conventions, layout, “always / never” rules that are true.

When the same mistake appears a second time, that is a CLAUDE.md candidate. When a procedure is multi-step and rare, that is often a skill (Part 4), not another always-loaded chapter.

AGENTS.md: multi-agent, multi-tool conventions

Many agent workflows and coding tools use AGENTS.md (or similarly named files) as a shared place for conventions that more than one agent or client should follow. Think of it as a house style for automation: how tools should behave in this repo, deploy notes for agents, safety rails, layout for humans who maintain agent configs.

Important Claude Code fact from the memory docs: Claude Code reads CLAUDE.md, not AGENTS.md by default. If your repo already has AGENTS.md for other tools, the documented pattern is to create a CLAUDE.md that imports it (for example with @AGENTS.md) so both ecosystems share one body of rules without copy-paste drift. A symlink can work when you do not need Claude-specific additions. On Windows, import syntax is often easier than symlinks.

So AGENTS.md is not “wrong” for Claude users. It is a multi-tool convention file. Wire Claude into it deliberately.

Friends you will meet

What a good CLAUDE.md contains

Docs and practice converge on a few sections. Names can vary. Content should stay checkable.

Project brief

Two to six sentences. What the product is, what the repo contains, what “done” roughly means for day-to-day work. No marketing. No roadmap for 2029. Enough that Claude does not invent a second product out of a folder name.

Commands

Install, test, lint, typecheck, run locally. Use the exact strings your team uses. If the truth is pnpm test, do not write “run the test suite.” If a suite is slow, say which subset is acceptable for a quick loop. Wrong commands waste context and confidence.

Style

Only what is not already obvious from formatters and linters. “Use 2-space indentation” is fine if the repo is not auto-formatted. “Prefer early returns in new TS files under src/api” is better than “write clean code.” Link to an existing style guide if one exists, but do not paste the whole guide.

Safety

Secrets, production data, force push, destructive migrate, customer exports. Write rules a junior could follow under pressure. Remember: CLAUDE.md is guidance. Pair high-cost rules with permissions, hooks, and human review (later parts of this series).

Architecture notes (optional, short)

Where new code should go, which modules are legacy, which package is the source of truth for a domain. These are the notes that prevent the agent from “helpfully” extending the wrong file. If the note is only true for one subdirectory, path-scoped rules under .claude/rules/ may be a better home so the main file stays small.

Sample CLAUDE.md (paste and thin)

Below is a realistic skeleton for a small TypeScript service. Delete every line that is not true for your repo. Add the three facts your last agent session got wrong. Resist the urge to write a novel.

# CLAUDE.md

## Project brief
Analytics dashboard API for internal ops. TypeScript on Node 20.
HTTP handlers live in `src/api`. Domain logic in `src/domain`.
Do not add new business rules to `src/legacy/`.

## Commands
- Install: `pnpm install`
- Dev server: `pnpm dev`
- Unit tests: `pnpm test`
- Typecheck: `pnpm typecheck`
- Lint: `pnpm lint`
- Prefer `pnpm`, not `npm` or `yarn`

## Style
- TypeScript strict already enabled; do not weaken `tsconfig`
- Prefer named exports for new modules under `src/`
- No default exports in new `src/api` handlers
- Match existing error shape: `{ error: { code, message } }`

## Safety
- Never commit `.env`, credentials, or production data dumps
- Do not run `pnpm migrate:prod` from agent sessions
- Do not force-push to `main`
- Redact customer emails in logs and fixtures

## Architecture notes
- Auth middleware: `src/api/middleware/auth.ts`
- Feature flags: `src/config/flags.ts` (not env sprawl)
- When adding an endpoint, add a test under `src/api/__tests__/`

## Imports for multi-tool teams (optional)
# If AGENTS.md already holds shared agent rules:
# @AGENTS.md

If you use the import line, keep Claude-specific extras below the import so both tools share the common core. Official docs show patterns like importing AGENTS.md then adding a short Claude-only section.

CLAUDE.md versus AGENTS.md versus README

Same facts, different cuts:

Git remains the source of truth for all of them. Instruction files that only exist on one laptop do not help the PR bot, the new hire, or the CI machine. Local-only preferences belong in CLAUDE.local.md or user-level files, ideally gitignored when they contain personal paths.

How files load (enough to debug “it ignored me”)

From Claude Code memory docs, a useful debugging sequence:

1. Run /context and check which memory files loaded.
2. Run /memory to open or create the files you expected.
3. Confirm you are in the directory tree you think you are (nested CLAUDE.md files load with documented rules; subdirectory files may load on demand when files there are read).
4. Make the instruction specific enough to verify. “Format nicely” loses to “use 2-space indentation.”
5. Search for contradictions across root CLAUDE.md, nested files, and rules. Conflicting rules produce arbitrary picks.

Remember Part 5: session chat is not where durable rules live. If you only said it once in conversation, a clear or a new session can wipe it. Promote the rule into CLAUDE.md when it should stick for everyone.

Short true beats long aspirational

This is the quality bar for every instruction file you maintain for agents.

Short true means a junior engineer could check compliance in a code review. Examples:

• “Run pnpm test before claiming done.”
• “API handlers live in src/api/handlers/.”
• “Never commit .env.”

Long aspirational means a paragraph of values that nobody can fail concretely. Examples:

• “We pursue excellence in craft and delight users.”
• “Write elegant, scalable, future-proof abstractions.”
• “Always think carefully about edge cases.”

Aspirational text is not evil in a company handbook. In CLAUDE.md it burns context and dilutes the lines that matter. Docs explicitly note that longer files consume more context and reduce adherence. Target roughly under 200 lines for a main CLAUDE.md; push depth into path-scoped rules or skills.

When you catch yourself writing “always prefer maintainable solutions,” stop and ask: what would a diff look like if this rule were followed or broken? If you cannot answer, delete the sentence.

Worked example: one repo, three files, no drama

Suppose you maintain a small internal metrics API. Human onboarding needs a story. Claude needs rails. Other agents need the same rails.

README.md (excerpt for humans):

# Metrics API

Internal service that serves weekly ops metrics for the dashboard team.

## Quick start
1. Node 20+
2. `pnpm install`
3. Copy `.env.example` to `.env`
4. `pnpm dev`

## Docs
- Architecture: docs/architecture.md
- Runbooks: docs/runbooks/

AGENTS.md (shared automation conventions):

# Agent conventions

## Tooling
- Package manager: pnpm only
- Tests: `pnpm test` (unit), `pnpm test:integration` only when asked
- Do not invent Docker workflows; we run on the host for local dev

## Safety
- No production database URLs in agent sessions
- No force-push
- Secrets stay in `.env` (gitignored)

## Layout
- Handlers: `src/api`
- Domain: `src/domain`
- Legacy: `src/legacy` (read-only unless ticket says otherwise)

CLAUDE.md (Claude entry + optional import):

@AGENTS.md

## Claude Code
- Prefer plan mode for changes under `src/billing/` if that folder exists
- After API changes, run `pnpm typecheck` before summarizing done

Humans get a friendly README. Multiple agents share AGENTS.md. Claude loads AGENTS.md through CLAUDE.md and adds one or two Claude-specific notes. You are not maintaining three contradictory novels.

Bootstrap without starting from a blank page

Claude Code documents /init to generate a starting CLAUDE.md from the codebase (build commands, tests, conventions it can discover). If a file already exists, it suggests improvements rather than blindly overwriting. Treat the draft as a first pass. Delete guesses. Add the tribal knowledge only humans know (“Billing is owned by team Coral; do not rename those tables without them”).

Also useful: run /doctor when available for config health, and use /memory when you are unsure what files are in play. The goal is not a perfect template. The goal is a short file the next session will actually follow.

Rules, skills, and when not to grow CLAUDE.md

As the project grows, the always-on brief should not grow at the same rate.

• Path-scoped rules in .claude/rules/ load when matching files are in play. Good for API-only or frontend-only constraints.
• Skills package multi-step workflows that load on demand (Part 4). Good for release checklists, Substack export recipes, deploy dances.
• Hooks and permissions enforce must-not behaviors that markdown alone cannot guarantee.

If CLAUDE.md is a table of contents for the entire engineering wiki, you have the wrong abstraction. Link out. Split. Keep the session-start payload lean so there is room for the files the task actually needs.

Common mistakes

• One mega-file for humans and agents. Neither audience finishes it. Split README from CLAUDE.md/AGENTS.md.
• Assuming Claude reads AGENTS.md alone. Wire it through CLAUDE.md import or symlink.
• Aspirational filler. If you cannot fail the rule in review, cut it.
• Contradictions across nested files. Pick one owner for each rule.
• Personal secrets in committed CLAUDE.md. Use local files and gitignore.
• Never updating after reality changes. Dead commands teach agents to improvise badly.
• Expecting markdown to replace git review. Instruction files guide. Diffs still need eyes (Part 9).

How to practice this week

1. Open a real repo. List which of README, CLAUDE.md, AGENTS.md already exist.
2. Write or trim a CLAUDE.md to under roughly 80 lines using the skeleton above. Only true lines.
3. If AGENTS.md exists for other tools, import it from CLAUDE.md instead of duplicating.
4. Start a new Claude Code session, run /context, confirm the file loaded.
5. Ask for a small change that would violate a safety or layout rule. See whether the agent hesitates or complies. Tighten wording if needed.
6. Commit the shared files. Keep personal paths local.

Part 7 moves to plugins, connectors, and tools: how external capabilities attach without turning every session into a permission maze. For the broader map of Claude products, see the Claude product map series and the paths on Learn.

Quick recap

• README is for humans; CLAUDE.md is Claude Code’s session brief; AGENTS.md is multi-agent convention glue.
• Claude Code loads CLAUDE.md; import AGENTS.md when you need one shared rule set.
• Put project brief, commands, style, and safety in short checkable form.
• Short true beats long aspirational. Context is finite. Adherence drops as novels grow.
• Git holds the durable truth. Chat still resets; instruction files are how the next session starts smart.

Sources

Research and further reading used for this article:

• Claude Code docs: How Claude remembers your project (CLAUDE.md locations, AGENTS.md import, rules, auto memory, writing effective instructions)
• Claude Code docs: Explore the context window (why instruction size matters next to file reads)
• Claude Code docs: Skills (on-demand workflows versus always-on markdown)
• Claude Code docs: Extend Claude Code (when to use CLAUDE.md vs skills vs rules vs hooks vs MCP)
• Claude Code docs: Best practices (context as a primary constraint)
• Claude Code docs: Hooks guide (enforcement when markdown guidance is not enough)
• Claude Code docs: Commands (/init, /memory, /context, and related)
• Claude Code docs: Overview (product entry and doc index)
• Analytics Made Simple: Learn (series map on this site)

Merch on Etsy

Open store →

You're On Mute White Ceramic Coffee Mug, Data Science Mug, Data Mug, Analytics Mug, Statistics Mug, Programming Mug, Gift Mug, Coffee Mug View on Etsy → Y Hat Mouse Pad, Data Science Mouse Pad, Analytics Mouse Pad, Y Pred Mouse Pad View on Etsy → You're On Mute White Ceramic Coffee Mug, Data Science Mug, Data Mug, Analytics Mug, Statistics Mug, Programming Mug, Gift Mug, Coffee Mug View on Etsy → Boxplot Mouse Pad, Data Science Mouse Pad, Analytics Mouse Pad, Box Plot, Whisker Plot View on Etsy →