# Claude Code

> Make Claude Code respect your kit's conventions via CLAUDE.md and AGENTS.md.

[Claude Code](https://claude.com/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](https://github.com/otf-kit/saas-dashboard/blob/main/CLAUDE.md)
as a template. The structure:

```md title="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

`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.