Customize CLAUDE.project.md

CLAUDE.project.md is the project overlay — a file the kit creates once at install and never touches again. It's where you put rules specific to your project, your team, your stack. Rules in this file override kit defaults when there's a conflict.

This is the lowest-friction way to customize agent behavior. Don't reach for hooks or custom skills until the overlay isn't enough.

What the overlay is good for

• Stack quirks: "This is a Next.js 16 RSC project — never use 'use client' unless absolutely required."
• Architectural patterns: "All API responses follow the envelope pattern: { data, error, meta }."
• Naming conventions that differ from kit defaults
• Project-specific protected changes: "Stop and ask before changing the sync conflict resolution logic."
• Pointers to project-specific docs: "Offline sync patterns are in agent_docs/project/offline-first.md."

What the overlay is NOT good for

Anatomy

The kit creates this skeleton:

# CLAUDE.project.md — Project Overlay

> This file is never modified by kit upgrades. Add project-specific rules here.
> Rules in this file override kit defaults when there's a conflict.

---

## Project Context
<!-- Describe your project's unique constraints, patterns, and conventions here. -->

## Additional Agent Docs
<!-- Point to project-specific guides in agent_docs/project/ -->

## Project-Specific Protected Changes
<!-- Add to the kit's protected changes list -->

## Stack-Specific Rules
<!-- Add rules that are specific to your tech stack beyond what the kit covers -->

You fill in the four sections. Empty sections are fine.

Example: Next.js 16 with offline-first sync

# CLAUDE.project.md — Project Overlay

## Project Context

This is an offline-first PWA built on Next.js 16 (App Router) with Dexie.js for IndexedDB persistence.

- All data writes go through the sync layer (`src/sync/`) which queues them locally and replays to the server when online.
- The "source of truth" for any record is local IndexedDB; the server is eventually consistent.
- Real-time features use SignalR over WebSocket — never raw WebSockets.

## Additional Agent Docs

- Offline sync patterns → `agent_docs/project/offline-first.md`
- SignalR conventions → `agent_docs/project/signalr.md`
- Dexie schema migration playbook → `agent_docs/project/dexie-migrations.md`

## Project-Specific Protected Changes

Stop and request approval before:

- Modifying sync conflict resolution logic in `src/sync/conflict.ts`
- IndexedDB schema version bumps (touches all clients on next visit)
- Changing the tombstone propagation rules
- Adding any code that bypasses the sync queue (writing directly to network)

## Stack-Specific Rules

- **Server Components first** — only add `'use client'` when you actually need interactivity, browser APIs, or local state.
- **API responses use the envelope pattern**: `{ data: T, error: { code, message } | null, meta?: object }`. Never return raw data.
- **Dexie queries** must always include `.toArray()` or a similar terminal — chained promises silently swallow errors.
- **All user-facing strings** through `useTranslation()` from `next-intl`. Never hardcode English text.
- **Forms** use `react-hook-form` with Zod schemas. No uncontrolled forms.

How Claude reads it

CLAUDE.md (the kit's main rules file) tells Claude to load CLAUDE.project.md after itself in every session. So your overlay rules are always in context.

When kit defaults conflict with overlay rules, overlay wins. The kit's CLAUDE.md says "Rules in CLAUDE.project.md override kit defaults when there's a conflict."

Updating it

Just edit the file. No kit command needed. Claude picks up changes on the next session.

If you find yourself editing it constantly with the same kind of rule, that's a hint the rule should become a skill or hook instead.

Verifying

After editing, ask Claude something that should trigger your new rule:

"Add a new API endpoint for users."

If you wrote "All API responses use the envelope pattern," Claude should produce code that follows that pattern without you saying it again. If it doesn't, the rule is probably too vague — make it more concrete.

Project-specific docs (agent_docs/project/)

When CLAUDE.project.md starts getting long, split topical chunks into agent_docs/project/<topic>.md and reference them from the overlay:

## Additional Agent Docs

- Offline sync deep-dive → `agent_docs/project/offline-first.md`

The kit ships three optional templates in agent_docs/project/:

• mission.md — product mission and audience
• tech-stack.md — technology choices with rationale
• roadmap.md — current priorities and milestones

You can use them or delete them — they're project-owned.

Related

• CLAUDE.md guide — how the main rules file works
• Workflow & Planning — when project rules apply during the agent's planning phase
• Conventions — kit defaults you might want to override