Claude Code

Claude Code auto-loads CLAUDE.md and AGENTS.md from the project root and from every parent directory up to your home folder. OTF kits exploit this to layer guidance:

• AGENTS.md at the monorepo root — universally-applicable rules (Git workflow, worktree placement, deploy script 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

Together, opening a kit in Claude Code gives the agent enough context to add a screen, wire a Hono route, or refactor a component without diverging from the rest of the codebase.

What goes in CLAUDE.md

Use the SaaS Dashboard kit's CLAUDE.md 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

AGENTS.md lives at the monorepo root and applies to every kit / every app in the workspace. It captures rules that are universal across this codebase — not kit-specific.

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 rule — use the per-app scripts/deploy-railway.sh wrapper, never raw CLI

How Claude Code reads these

When you open Claude Code in a kit directory, the auto-loader:

1. Walks up from the cwd to your home folder, gathering every CLAUDE.md and AGENTS.md
2. Concatenates them into the system prompt for every turn
3. Keeps file paths so [file](path/to/file) links remain navigable

Claude Code also reads any file you mention in a turn via @file.tsx. So if your CLAUDE.md points to deeper guides (docs/CUSTOMISATION.md), Claude will load them on demand.

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.