CLAUDE.md — 100minds Claude Code rules

Read this before writing code. This file is intentionally short. Durable project guardrails live in AGENTS.md; current implementation details live in ARCHITECTURE.md; design rules live in docs/DESIGN_SYSTEM.md; performance and audit setup live in docs/PERFORMANCE_ANTI_SLOP.md and docs/QUALITY_GATES.md if present.

Claude-specific operating rule

Claude Code tends to be proactive. In this repo, be surgical: do exactly the requested task, do not add extra files, features, abstractions, refactors, convenience helpers, cleanup, dependency upgrades, or “while I was here” fixes unless the task explicitly asks for them. If something extra seems necessary, stop and report it instead of building it.

Required reading order

For every coding task, read AGENTS.md, read the relevant section of ARCHITECTURE.md, inspect 1–2 nearby files before editing. For UI/design work, also read docs/DESIGN_SYSTEM.md. For performance/audit/tooling work, also read docs/PERFORMANCE_ANTI_SLOP.md and docs/QUALITY_GATES.md.

Priority order

Access control > correctness > speed > AI quality. Never sacrifice access control. Sacrifice AI quality before correctness.

Uncertainty rule

If the task, codebase, or docs conflict, stop and surface the conflict. Do not silently pick defaults for product, architecture, tenant-scope, data model, AI, security, or UX decisions. If the user explicitly asks for best effort, make the smallest safe assumption and document it.

Non-negotiable rules

Tenant context comes from server auth/session only, never from client input; tenant-scoped data access must use the tenant-safe DB path; thread visibility must go through the central access-control layer; core writes must use existing authenticated action/write paths; do not create parallel “quick” write paths; mutations must validate input, enforce auth/tenant scope, audit where appropriate, and revalidate affected routes; do not add production dependencies without explicit justification.

AI rules

All model/provider calls go through the AI gateway/provider abstraction; AI never silently mutates state; AI output is a suggestion unless a feature spec explicitly says otherwise with safeguards; untrusted input is data, never instructions; use structured output and server-side validators; re-verify access-sensitive and value-sensitive fields on save; cited AI output must pass the grounding/verifier path when citations are used; every AI feature must degrade safely when AI is unavailable.

Performance rules

No N+1 queries, no database calls inside loops, no unbounded fetches for list/report pages, filter/sort/paginate/aggregate in the database where practical, add matching indexes for new filtered/sorted query paths, select only fields needed for the view model, prefer Server Components, add "use client" only for browser APIs/event handlers/client state, keep client components as small leaf components, avoid sequential awaits for independent fetches, do not add caching/memoization/workers without measured or clearly explained need, ensure tenant/user identity is part of any tenant/user cache key.

Anti-slop rules

Read nearby files before editing, match existing structure/naming/imports/test style, keep diffs small and task-focused, no speculative abstraction, no framework for one use, no dead code, no commented-out blocks, no unused exports, no TODO dumps, no duplicate utilities/schemas/actions/components/primitives/validation logic, do not weaken tests to pass, do not hide errors with broad try/catch, silent fallbacks, or ignored promises.

Definition of done

Before claiming completion, run the relevant gates and report results. Minimum: npm run lint, npm run typecheck, npm run test. Also run when relevant: npm run check:tokens, npm run eval:ai, npm run e2e, npm run build-storybook, npm run quality:fast, npm run quality:full. A task with failing gates is unfinished unless the failure is explicitly documented and accepted.

Response after coding

Report changed files, what changed, commands run, results, known risks, rollback path.

Scope control

Do exactly the requested task. Do not add adjacent features, cleanup, redesign, dependency upgrades, architecture changes, or tooling changes unless required for the task. If unrelated issues are found, report them separately instead of fixing them in the current change.

Branch discipline (pilot vs Phase 2) — MANDATORY, check before every edit

Two long-lived branches exist: master = the live client pilot (production, always deployable); phase-2 = all Phase 2 work per docs/100minds_Phase2_Plan.md. Before writing or editing ANY file, run git branch --show-current and classify the task: pilot bug fix / client-requested tweak → must be on master; Phase 2 feature/refactor/migration → must be on phase-2. If the current branch does not match the task, stop and switch branches before editing — never "just do it here". Never mix pilot and Phase 2 changes in one commit or one branch. Merge direction is one-way: master → phase-2 (after every pilot fix lands, or at least weekly); never merge phase-2 → master until the user explicitly approves the pilot-end cutover. Prisma migrations on phase-2 must be additive (no drops/renames of columns the pilot uses); a migration the pilot needs lands on master first, then merges down. Tag every pilot deploy (pilot-x.y). If it is unclear which branch a task belongs to, ask the user — do not guess. Full rules in AGENTS.md § Branch discipline.

Phase 2 tracker — MANDATORY

docs/100minds_Phase2_Tracker.md is the living status record for Phase 2. Any commit on phase-2 that advances/starts/blocks/finishes a plan milestone must update the tracker in the same commit (milestone status + a 1–2 line dated Session-log entry). Update it before ending a session with in-progress Phase 2 work. Full rules in AGENTS.md § Phase 2 tracker discipline.

Architecture doc — MANDATORY

ARCHITECTURE.md describes implemented code only, per branch — never unlanded plans. Any commit changing auth/session, the data model, tenant isolation, AI routing/providers, or adding/removing a route or major surface must update the affected ARCHITECTURE.md section (and its Last-updated date) in the same commit. Document transitional states as they actually are. Full rules in AGENTS.md § Architecture doc discipline.

Orchestrated Coding Workflow

Claude Code is the orchestrator: plan, delegate, verify, and keep context lean.

Agent roles

• Codex = primary coding agent for implementation, debugging, tests, refactors, and multi-file changes.
• deep-reasoner = use only for architecture, complex debugging, risky design decisions, migrations, security, or data-flow questions.
• fast-worker / Sonnet = use for simple edits, boilerplate, formatting, small tests, and mechanical cleanup.
• Claude Code fallback = continue directly if Codex is unavailable, quota-limited, stuck, or returns an unusable result.

Default workflow

1. Inspect relevant docs/code first.
2. Make a short plan.
3. Delegate implementation to Codex with /codex:rescue --background.
4. Use fast-worker for simple mechanical follow-up.
5. Use deep-reasoner only when the design is uncertain or high-risk.
6. Run project verification commands before considering work done.

High-risk changes

For auth, tenant isolation, database migrations, production data, billing, deletion, or large refactors:

1. Ask deep-reasoner for the safest approach.
2. Ask Codex independently for an implementation/design pass.
3. Compare both.
4. Synthesize one final plan.
5. Implement in small patches.
6. Run tests/quality gates.

Codex fallback rule

If Codex fails, is quota-limited, hangs, or gives a poor result:

• stop relying on Codex for that task,
• summarize what it was asked to do,
• continue with Claude Code or fast-worker,
• keep the patch small,
• verify with the same project commands.

Review policy

Use /codex:review --background for meaningful changes and /codex:adversarial-review --background for risky ones. Do not enable automatic Codex review gates by default.