Skip to content

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.md at the monorepo root — universally-applicable rules (Git workflow, worktree placement, deployment-documentation discipline, lessons-first rule)
  • CLAUDE.md at 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:

kits/<your-kit>/CLAUDE.md
# 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.md before 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:

  1. Loads CLAUDE.md, .claude/CLAUDE.md, and CLAUDE.local.md files from the working directory and its ancestors.
  2. By default, loads AGENTS.md instead only when no CLAUDE.md, .claude/CLAUDE.md, or CLAUDE.local.md exists in that directory chain. Use claude-md-and-agents-md or an @AGENTS.md import when you need both formats.
  3. 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 Skill tool 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:

Free with your email

Get the free AI configs pack

The AI files every kit ships with. Drop them in and your AI tool knows your project.

  • CLAUDE.mdProject context
  • .cursorrulesRules for Cursor
  • prompts/Task prompts

No spam. Unsubscribe any time.