docs: add example CLAUDE.md for automatic preflight integration

README.md

@@ -124,6 +124,19 @@ claude mcp add preflight -- preflight-dev-serve
 
 > **Note:** `preflight-dev` runs the interactive setup wizard. `preflight-dev-serve` starts the MCP server — that's what you want in your Claude Code config.
 
+### Make Claude use it automatically
+
+Add a `CLAUDE.md` to your project root telling Claude to run preflight on every prompt:
+
+```markdown
+## Preflight Integration
+
+Before starting any non-trivial task, run `preflight_check` with my prompt.
+Follow its recommendations — if it says clarify, ask me before proceeding.
+```
+
+See [`examples/CLAUDE.md`](examples/CLAUDE.md) for a full template you can copy and customize.
+
 ---
 
 ## How It Works

examples/CLAUDE.md

@@ -0,0 +1,46 @@
+# CLAUDE.md — Example Project Instructions with Preflight
+
+> Copy this to your project root and customize it. Claude Code reads this file
+> automatically at the start of every session.
+
+## Preflight Integration
+
+Before starting any non-trivial task, run `preflight_check` with my prompt.
+Follow its recommendations — if it says clarify, ask me before proceeding.
+
+When I give a vague prompt (e.g., "fix the tests"), don't guess. Use preflight
+to identify what's ambiguous, then ask me to be specific.
+
+## Project Overview
+
+- **Stack:** Next.js 14, TypeScript, Prisma, Supabase
+- **Monorepo:** `apps/web`, `packages/shared`, `services/auth`
+- **Node version:** 20+
+- **Package manager:** pnpm
+
+## Conventions
+
+- All new files in TypeScript (no `.js`)
+- Use `@/` path alias for imports from `src/`
+- Tests go next to source files: `foo.ts` → `foo.test.ts`
+- Commit messages: conventional commits (`feat:`, `fix:`, `docs:`, etc.)
+- Run `pnpm lint && pnpm test` before committing
+
+## Key Files
+
+- `prisma/schema.prisma` — database schema (source of truth for types)
+- `src/lib/auth.ts` — auth helpers, JWT validation
+- `src/middleware.ts` — route protection, redirects
+- `.env.local` — local env vars (never commit)
+
+## Things That Break Easily
+
+- Changing Prisma schema without running `pnpm prisma generate`
+- Modifying auth middleware without testing both logged-in and logged-out flows
+- Adding new API routes without updating the OpenAPI spec in `docs/api.yml`
+
+## What I Care About
+
+- Don't over-engineer. Simple > clever.
+- Explain *why* before showing code if the approach isn't obvious.
+- If a task touches multiple services, check contracts first (`search_contracts`).

examples/README.md

@@ -1,5 +1,18 @@
 # Examples
 
+## `CLAUDE.md` — Project Instructions with Preflight
+
+The [`CLAUDE.md`](CLAUDE.md) example shows how to set up your project instructions so Claude Code automatically uses preflight on every prompt. Copy it to your project root and customize:
+
+```bash
+cp /path/to/preflight/examples/CLAUDE.md ./CLAUDE.md
+```
+
+Key things it demonstrates:
+- Telling Claude to run `preflight_check` before starting work
+- Documenting your stack, conventions, and fragile areas
+- Keeping it under 5KB to avoid token bloat (preflight's `token_audit` will warn you if it gets too big)
+
 ## `.preflight/` Config Directory
 
 The `.preflight/` directory contains example configuration files you can copy into your project root: