Skip to main content

Claude Code Best Practices

Lessons learned from the March 2026 sprint. These apply to all developers using Claude Code on SecurityV0 repos.

Cross-File Reference Tracing​

After ANY type, interface, field, or function change -- trace ALL references before committing.

The checklist:

  1. grep -rn "old_name" src/ ui/src/ test/ -- find every reference
  2. npx tsc --noEmit -- backend typecheck
  3. cd ui && npx tsc --noEmit -- frontend typecheck
  4. npx vitest run test/<affected>.test.ts -- targeted tests
  5. git diff --stat -- review every changed file

Why: Removing a field from a type but leaving references in UI forms, API routes, and test fixtures causes multiple review rounds. A single grep catches them all.

Simplicity-First Design​

Start with the simplest model that works. Don't add optional fields, extra statuses, or secondary levels unless there's a current user need.

Example: The ownership assignment model went through 6 review rounds because it started with level (primary/secondary), effective_until, and expired status. The correct Phase 1 model was: one owner per target, active or revoked.

Rule: Before adding an optional field, ask: "Does any current user flow need this?" If no, omit it.

Full-Stack Verification​

Every change that touches types must verify both backend AND frontend:

  • Backend: npx tsc --noEmit from repo root
  • Frontend: cd ui && npx tsc --noEmit
  • Tests: npx vitest run (not just targeted files)

Running only one typecheck misses cross-boundary issues.

Environment URLs​

EnvironmentURL
Productionapp.securityv0.com
Dev (main branch)dev.securityv0.com
PR previewspr-N.dev.securityv0.com
Visual reviewspr-N.sv0-reviews.pages.dev
Sprint reviewssprint-<name>.sv0-reviews.pages.dev
Documentationsv0-docs.pages.dev

Never use localhost for sprint reviews, stakeholder reviews, or QA reports. Always compare deployed environments.

Sprint Review Workflow​

Always use the sprint review skill (sv0-skills/sprint-review/SKILL.md). Never generate a simple visual diff and call it a sprint review.

The skill orchestrates: action plan parsing, screenshot mapping, GitHub status collection, verdict derivation, HTML rendering, Cloudflare deployment.

Key files:

  • Action plan: sv0-documentation/docs/product/reviews/march-2026-platform-review/2026-03-21-consolidated-action-plan.md
  • Mapping: sv0-skills/sprint-review/screenshot-mapping.yaml
  • GitHub config: sv0-skills/sprint-review/github-query-march-2026.yaml
  • Snapshots: sv0-intelligence/store/snapshots/

Links in generated reports must use absolute URLs with the /docs/ prefix:

https://sv0-docs.pages.dev/docs/path/to/page

Not relative .md paths (those only work in Obsidian). No .md extension in URLs.

Sub-Agent Discipline​

From .claude/rules/workflow.md:

  • Max 4 parallel agents per wave
  • Agents MUST push their branches
  • Agents MUST verify their branch before committing
  • Cross-review BEFORE merge, not after
  • Clean up worktrees after each wave

Codex Review Integration​

When using Codex for code review:

  • Don't fix only the flagged line -- audit the ENTIRE feature for the same pattern
  • After each fix round, run the full verification checklist (grep + tsc + tests)
  • If a fix introduces a new field/type change, trace all consumers before pushing

Git Safety​

The platform .claude/settings.json denies:

  • Pushing to main or dev directly
  • Force pushing
  • git merge (rebase workflow only)
  • git reset --hard, rm -rf
  • gh pr merge (manual merge only)

Always create a feature branch and PR. Always verify your branch with git branch --show-current before committing.

Common Pitfalls​

  1. Forgetting UI typecheck -- Backend compiles but UI has type errors. Always run both.
  2. Stale worktrees -- Accumulate during review cycles. Clean with git worktree prune after each PR.
  3. Test mocks out of sync -- Adding StorageAdapter methods requires updating ALL Partial<StorageAdapter> mocks. Find them: grep -rn "Partial<StorageAdapter>" test/
  4. Generated files manually edited -- Sprint reviews, reports, evidence packs are generated. Put overrides in config (e.g., verdict_override in screenshot-mapping.yaml), not in the output.
  5. Relative links in HTML output -- Markdown relative links work in Obsidian but break in deployed HTML. Use absolute Docusaurus URLs.
  6. Branch confusion -- Too many local branches without verifying current branch. Always run git branch --show-current before making changes. Use worktrees instead of branch switching.
  7. CI failures discovered one at a time -- Run npm run ci && cd ui && npm run ci locally before any PR. Catches lint + typecheck + all tests + build in one shot.
  8. YAML parser format mismatch -- When building parsers for config files, always include an integration test that loads the actual file. Don't just test against synthetic inputs.