Claude Code Usage

This page documents how Claude Code is configured for the PaperRun API codebase — what rules it follows, where docs live, and what commands are available.

Layout overview

File	Loaded when	What it carries
Root CLAUDE.md	every session	Layering invariant, hard rules, routing table, build/test/lint commands, PR workflow
app/<layer>/CLAUDE.md	working in that directory	Per-layer rules — see below
docs/business-context.md	on demand (linked from root)	What the product is, integrations, attribution methods at a glance
docs/gotchas.md	on demand (linked from root)	Append-only "things that look right but aren't" log
docs/models/<model>.md	on demand	Per-model deep context
docs/architecture/*.md, docs/data_flow/*.md, docs/guides/*.md, docs/code/*.md	on demand	System-level deep dives
.claude/agents/*.md	on invocation	Reviewer subagents
.claude/commands/*.md	on /command invocation	Slash commands
.claude/guides/*.md	read by the relevant skill at runtime	Reference material backing slash commands

The intent: the always-loaded prompt is small and immutable; everything else is loaded on demand, either by the Claude Code subdirectory-CLAUDE.md mechanism or via the routing tables.

What's in root CLAUDE.md

Section	What it controls
Layering	Routes → Methods → Models → Core. Pointer to subdirectory CLAUDE.md files for per-layer rules.
Hard rules	Tests (monkeypatch only), imports at top, layer boundaries, no ORM (raw SQL via psycopg), just lint after edits.
Routing	Read-on-demand table mapping task type → which doc to read.
Workflow	When to plan first, what to do after edits (lint, tests, optional reviewer agent).
Build/test/lint	just test, just lint, just check-all, docker compose up, etc.
PR workflow	gh pr create with --reviewer "Paper-Run/development-team"

When to update root CLAUDE.md

Update it when: - A new coding convention is adopted across the whole repo (not just one layer — that goes in the layer's CLAUDE.md). - A new always-loaded rule is needed because a recurring mistake can't be caught by ruff or by a reviewer agent. - Build/test commands change. - The directory layout changes.

Don't put: ephemeral information, soft preferences ruff handles, or rules that only apply to one layer.

Subdirectory CLAUDE.md files

Per-layer rules. These are auto-loaded by Claude Code when you work inside that directory.

File	Purpose
app/routes/CLAUDE.md	Blueprint conventions, response shapes, schema reuse, no integrations imports
app/methods/CLAUDE.md	Pure-function preference, side-effect placement, smells to watch for
app/core/models/CLAUDE.md	Raw SQL patterns, cursor lifecycle, JSONB updates, model class shape
app/core/integrations/CLAUDE.md	Integration directory structure, client naming patterns
app/celery/CLAUDE.md	Task decorator, beat schedule, routing config
app/scripts/CLAUDE.md	Script conventions, run commands
app/tests/CLAUDE.md	Factory patterns, fixture registration, monkeypatch idiom and why MagicMock is banned
migrations/CLAUDE.md	Filename convention, idempotency, backfill pattern, rollback comments

Read-on-demand docs

These are not auto-loaded. The root CLAUDE.md routing table tells Claude when to read each. Do not preemptively read them.

When the task touches…	Reference
Business context (product overview, integrations, attribution methods)	docs/business-context.md
Gotchas / non-obvious mistakes	docs/gotchas.md
Attribution methodology (matching hierarchy, holdouts, edge cases)	docs/attribution_methodology.md
Mailpiece printing & proofing pipeline	docs/proofing_and_mailing.md
Order syncing flow	docs/data_flow/order_syncing.md
Address enrichment pipeline	docs/data_flow/address_enrichment.md
Reporting / stats / experiments	docs/data_flow/reporting.md
Billing pipeline (preflight, meter emission, rate cards)	docs/data_flow/billing.md
Recipient pipeline (cross-cutting)	docs/data_flow/recipient_pipeline_flow.md
Request flow / API layering	docs/data_flow/request_flow.md
Architecture overview	docs/architecture/index.md
Worker schedule / Celery beat	docs/architecture/worker-schedule.md
External integrations overview	docs/architecture/integrations.md
Testing patterns (deep)	docs/code/testing.md
Deployment	docs/guides/deploying.md
Full system overview	docs/index.md

Rule of thumb: if you'd ship the change confidently without consulting one of these, you don't need to read it. If the change crosses model boundaries, mutates a shared pipeline, or alters externally-observable behavior, read the relevant doc first.

Reviewer subagents

On-demand reviewers. The main agent invokes them after edits to catch things ruff / black can't.

Agent	Trigger
test-quality-reviewer	Tests have been added or significantly changed
python-style-reviewer	Non-trivial Python source has been written or modified — checks layer boundaries, side-effect placement, SQL idioms, composition vs. inheritance

The pattern is "main agent writes → invokes reviewer → applies findings → reports done." Reviewers carry deeper rules than CLAUDE.md can afford because they only run on demand.

Slash Commands

All commands live in .claude/commands/ and run by typing /command-name.

Onboarding & Learning

Command	What it does
/onboard-setup	Interactive dev environment setup checklist (prerequisites, env file, DB seeding, tests)
/onboard-learn	Guided walkthrough of the full system — architecture, request flow, recipient pipeline, attribution
/onboard-dive	Area-specific code orientation: pick a domain, get walked through key files and patterns
/explain-domain	Quick domain explainer — pick any area and get state machines, key files, gotchas

Code Review

Command	What it does
/review	Reviews current branch against main — broken callers, schema changes, dependency updates
/final-review	Multi-agent PR review: 3 parallel reviewers (consistency, clean code, error handling), then reconcile and fix
/pr-comments	Fetches PR comments from GitHub, auto-applies straightforward fixes, flags complex ones

Documentation

Command	What it does
/update-docs	Scans codebase and proposes doc updates with Mermaid diagrams. Scopes: full, models, data flows, architecture, or changed files only

Guide: .claude/guides/update-docs-guide.md

Integration Workflows

Command	What it does
/register-klaviyo-events	Discover and register Klaviyo events across domains (loyalty, birthday). Inspect orgs, test segments, create Linear tickets
/register-klaviyo-order-events	Register Klaviyo order-related events
/register-ometria-shims	Register Ometria shim events

Guides: .claude/guides/register-klaviyo-events-guide.md, .claude/guides/register-klaviyo-order-events-guide.md, .claude/guides/register-ometria-shims-guide.md