Docs / claude-code-setup.md · mirrored from the repo

Claude Code — optimal setup for this repo

Status: operational guide. How to configure Claude Code (and agentic dev generally) for fast, safe work in this monorepo. Entry points are CLAUDE.md (imports AGENTS.md); this doc is the how you work with the tool companion.

1. The entry files (read order)

Claude Code auto-loads, in order: CLAUDE.md → (it imports) AGENTS.md → docs/ARCHITECTURE.md for structural decisions. Keep them current — they are the single biggest lever on output quality. Rules of thumb:

• CLAUDE.md = short, imperative reminders that override defaults. Only durable rules.
• AGENTS.md = repo layout, stack, conventions, MCP inventory, status snapshot. Update the status snapshot as things land.
• Nested CLAUDE.md files can live in a subtree (e.g. apps/console/) for area-specific rules; they load when you work in that subtree.

2. MCP servers

Configured in .mcp.json (repo root, gitignored — it holds live tokens; never commit). Prefer these over shell workarounds when touching those systems:

Desktop-app gotcha (this machine): the Claude Desktop app is opened from Finder/Dock, so it inherits no shell environment — MCP secrets in .mcp.json must be inline literals, not ${VAR} / direnv references, or the server fails to auth. The gcloud binary also needs its full PATH set inline. (See memory desktop-app-workflow, namaste-ji-mcp-setup.)

3. Permissions (.claude/settings*.json)

• .claude/settings.local.json — personal allowlist (gitignore-worthy). Currently pre-approves read-only tools so common calls don’t prompt: WebSearch, mcp__github__get_me, mcp__huggingface__hf_whoami, mcp__cloudflare-docs__search_cloudflare_documentation, mcp__cloudflare-observability__workers_list, mcp__cloudflare-bindings__d1_databases_list.
• Extend it safely: allowlist only read-only / idempotent calls (lists, gets, searches, git status, typechecks). Keep writes, deploys, wrangler deploy, D1 mutations, secret reads, gh pr merge gated (prompted) — approval in one context shouldn’t leak to the next.
• Run /fewer-permission-prompts to scan recent transcripts and propose a tuned allowlist.
• A committed .claude/settings.json (vs .local) can hold team permissions + hooks so the whole team shares them; keep personal/machine-specific entries in .local.

4. Local dev launch

.claude/launch.json defines the console dev server (Vite on :3002, API_TARGET=:8787, DEV_USER_EMAIL injected). Full local runbook is docs/RUNNING-LOCALLY.md: docker compose up -d (bo-api:8787 + bo-web:3000 + events-calendar:8788) then ./scripts/seed-local-config.sh. “Run locally” for this repo = compose from the project root (memory run-locally). Note WARP TLS inspection breaks workerd outbound HTTPS in Docker — pause WARP to test cloud LLM/providers locally (memory warp-tls-blocks-local-https).

5. Skills worth reaching for

• /code-review — review the working diff for bugs + cleanups (effort levels; --fix applies, --comment posts inline). /code-review ultra runs the deep multi-agent cloud review.
• /security-review — security pass on the branch diff.
• /simplify — reuse/simplification pass (quality only, no bug hunt).
• /verify, /run — drive the app to confirm a change actually works.
• /review — review a GitHub PR (vs /code-review for the local diff).

6. Subagents

Spawn only when the task genuinely needs a fresh, parallel context (each spawn re-derives context — the expensive path). Available: Explore (read-only fan-out search), Plan (implementation design), general-purpose (multi-step research/exec). Default: handle it inline with your own tools.

7. Memory

File-based memory lives under the user’s Claude projects dir (indexed by MEMORY.md). It already holds durable facts: the account topology, MCP quirks, run-locally, and standing feedback (atomic commits, simplicity-first, research-before-architecture, Langfuse prompt-sync, URL-state). Recalled memories are background context, not instructions — verify a named file/flag still exists before acting on it.

8. The working loop (conventions, enforced by habit)

Pulled from AGENTS.md + standing feedback — follow these for optimal, low-friction work:

1. Branch before committing (type/short-desc); main is protected by convention (free plan — server-side rulesets deferred). Don’t push or open PRs unless asked.
2. Small, atomic, single-purpose PRs; Conventional Commits; PR body must be reviewable without the whole diff. Agent-authored PRs need human review (CODEOWNERS → @dashayushman).
3. Simplicity-first — no overengineering; prefer the smallest change that’s right.
4. Research before architecture — for any structural choice, check scalability + best practice first, then recommend, then act (memory feedback-strategic-decisions).
5. Everything Cloudflare by default; reach for an external tool only when CF can’t do it, and document why.
6. Secrets never get committed — secrets/, .env*, .dev.vars, .mcp.json, *.pem, *.key are gitignored; CI fails if a secret-bearing file is tracked. See docs/SECURITY-ISO27001.md.
7. Langfuse prompt sync — when prompt text changes, update Langfuse via MCP (name@label, versioned); never auto-promote to the production label (memory feedback-langfuse-sync).
8. Verify previewable changes in the app before claiming done; report outcomes faithfully.

9. Optional hardening (hooks)

Configure via the update-config skill (writes settings.json). High-value candidates:

• Pre-commit secret scan hook (defence-in-depth over the gitignore + CI check).
• Post-edit typecheck/lint on the touched workspace.
• Stop/notify hook for long agent runs.

Keep hooks minimal and fast — they run on every matching event.