From 5c2979da8e443cc857561a9aa56a0aa856722185 Mon Sep 17 00:00:00 2001
From: Jack Felke <jrinnfelke@gmail.com>
Date: Mon, 16 Mar 2026 08:31:20 -0700
Subject: [PATCH] docs: add example CLAUDE.md for automatic preflight
 integration

---
 README.md          | 13 +++++++++++++
 examples/CLAUDE.md | 46 ++++++++++++++++++++++++++++++++++++++++++++++
 examples/README.md | 13 +++++++++++++
 3 files changed, 72 insertions(+)
 create mode 100644 examples/CLAUDE.md

diff --git a/README.md b/README.md
index 6d03f5d..9418a50 100644
--- a/README.md
+++ b/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
diff --git a/examples/CLAUDE.md b/examples/CLAUDE.md
new file mode 100644
index 0000000..7fd9f7a
--- /dev/null
+++ b/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`).
diff --git a/examples/README.md b/examples/README.md
index 778f15d..de43487 100644
--- a/examples/README.md
+++ b/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: