Claude Code
Understand how Claude Code loads CLAUDE.md and AGENTS.md project instructions.
Claude Code loads project instruction files according to its
Project instructions setting. By default, claude-md-or-agents-md loads CLAUDE.md files from
the working directory and its ancestors when any are present; it uses AGENTS.md instead only
when there is no CLAUDE.md, .claude/CLAUDE.md, or CLAUDE.local.md in that directory chain.
It does not automatically load both formats together in every repository. OTF kits can layer
guidance, but configure Claude Code to load both files if both are needed:
AGENTS.mdat the monorepo root — universally-applicable rules (Git workflow, worktree placement, deployment-documentation discipline, lessons-first rule)CLAUDE.mdat the kit root — kit-specific context (stack, file map, patterns)docs/at the kit root — deeper guides Claude can read on demand
To load both formats, set Project instructions to claude-md-and-agents-md in /config, or
import AGENTS.md from CLAUDE.md with an @path/to/AGENTS.md reference, relative to the
CLAUDE.md file. Direct AGENTS.md support requires Claude Code v2.1.277 or later, and some
older or restricted sessions read only CLAUDE.md. Check /config or /context to confirm
which instruction files loaded.
What goes in CLAUDE.md
Every kit ships a CLAUDE.md at its root. Use the SaaS Dashboard kit's file, outlined below, as a
template. The structure:
# CLAUDE.md — Your Kit
A one-paragraph description of what this kit is and what AI editors should
know on first contact.
## Stack
| Layer | Choice |
| -------- | --------------------------------- |
| Framework | Vite 6 + React 19 |
| Routing | TanStack Router |
| ... | ... |
## Project structure
your-kit/ ├── src/ │ ├── pages/ │ ├── components/ │ ├── hooks/ │ └── ... └── server/ ├── routes/ └── db/
## Patterns
How TanStack Query hooks are shaped. How Hono routes are shaped. How a new
screen gets added. How theming works. Whatever idioms repeat in this kit.
## Coding conventions
Strict TypeScript. No comments unless explaining a non-obvious why. Tailwind
tokens only — no inline styles. Functional components.
## Deploy
Exact command to ship. Required env vars.What goes in AGENTS.md
Use the monorepo-root AGENTS.md for rules shared across kits and apps. Whether Claude Code
loads it alongside a kit-root CLAUDE.md depends on the Project instructions setting and the
file hierarchy described above; its presence alone does not guarantee both files load.
The OTF master AGENTS.md covers:
- Maintenance rule — keep AGENTS.md under 200 lines; deep dives go in
docs/ - Lessons-first rule — grep
docs/lessons.mdbefore reaching for new infrastructure - Phase rule — work strictly from
.todo/phase-N-*/PRD.md+todo.md - Deploy guidance — follow the target kit's deployment documentation; do not assume it ships an automation wrapper.
How Claude Code reads these
When you open Claude Code in a kit directory, the default loader:
- Loads
CLAUDE.md,.claude/CLAUDE.md, andCLAUDE.local.mdfiles from the working directory and its ancestors. - By default, loads
AGENTS.mdinstead only when noCLAUDE.md,.claude/CLAUDE.md, orCLAUDE.local.mdexists in that directory chain. Useclaude-md-and-agents-mdor an@AGENTS.mdimport when you need both formats. - Loads a subdirectory's instruction file as Claude works with files there, subject to the same hierarchy rules.
Claude Code also reads files you mention in a turn with @file.tsx. A CLAUDE.md can import
another instruction file with @path/to/file; ordinary links to deeper guides do not make
those guides part of the startup instructions.
Tips
-
Keep it scannable. Long CLAUDE.md files cost tokens on every prompt. The OTF kits cap their CLAUDE.md at ~250 lines and push deeper material to
docs/. -
Show, don't tell. A 5-line "TanStack Query hook shape" code example beats 20 lines of prose explaining the convention.
-
Update it on convention drift. If you change how a hook is shaped or how a route is added, update CLAUDE.md the same commit. Stale docs train Claude on the wrong pattern.
-
Use the
Skilltool for slash commands. Claude Code's/<skill>syntax invokes a skill defined in.claude/skills/. The OTF master ships several (/marketing,/loop,/schedule) — kit-specific skills go inside the kit.
Sources
Vendor documentation checked 9 Oct 2026:
- Anthropic, How Claude remembers your project — instruction-file hierarchy,
AGENTS.mdsupport, and version/session conditions.