Skip to content

CLAUDE.md

Latest commit

 

History

History
73 lines (50 loc) · 3.31 KB

CLAUDE.md

File metadata and controls

73 lines (50 loc) · 3.31 KB
Raw

Project

React SPA built with Vite using feature slice architecture with clean architecture principles.

Stack

TypeScript SPA. React 19, Vite 7, React Router 7, TanStack Query, Zustand, XState, Chakra UI, i18next. Testing: Vitest, Storybook, Playwright, MSW.

Commands

  • pnpm dev — start dev server (port 5173)
  • pnpm dev:all — start both frontend (port 5173) and local API server (port 3001)
  • pnpm typecheck — type-check all sources (src, e2e, stories, tests)
  • pnpm lint --fix — lint and auto-fix
  • pnpm test — all tests (unit + storybook)
  • pnpm test:e2e — Playwright E2E (headless)
  • pnpm storybook — component dev (port 6006)

Package manager: PNPM only. Path alias: @/* → src/.

Core Principles

  • Simplicity first — make every change as simple as possible, minimize code impact, choose the boring solution
  • Surgical changes — touch only what the task requires; don't refactor, reformat, or "improve" adjacent code. Remove only the orphans your own changes create
  • When unsure about requirements or business logic, ask the developer — never assume
  • When multiple interpretations exist, present them — don't pick silently
  • For changes >300 LOC or >3 files, ask for confirmation before proceeding
  • Stay within current task context; inform dev if fresh start needed
  • Modify API contracts only with explicit approval
  • Use git commands only when explicitly requested
  • Keep reports, options, and summaries extremely concise — prioritize information density

Workflow

1. Plan Mode Default

  • Enter plan mode for any non-trivial task (3+ steps or architectural decisions)
  • If something goes wrong, STOP and re-plan immediately — do not keep pushing
  • For complex features, write or request a spec before implementation
  • Use plan mode for verification steps, not just building

2. Self-Improvement Loop

  • After any correction, capture the pattern in specs/lessons.md and write a rule to prevent recurrence
  • Review specs/lessons.md at the start of each session
  • Ruthlessly iterate on lessons until the mistake rate drops

3. Verification Before Done

  • Never mark a task complete without proving it works
  • Run tests, check logs, and demonstrate correctness

4. Demand Elegance (Balanced)

  • For non-trivial changes, ask: "Is there a more elegant solution?"
  • If a fix feels hacky: "Knowing everything I know now, implement the elegant solution"
  • Skip this for simple fixes — do not over-engineer

5. Autonomous Bug Fixing

  • When given a bug report: just fix it
  • Use logs, errors, and failing tests to diagnose — require zero context switching from the developer

6. Spec-Driven Development

  • For features spanning 5+ files or 5+ unconstrained decisions, write a spec first using writing-spec skill
  • When implementing a spec, read the building-blocks skill rule file for each block in the Building Blocks Diff before writing code. That is the canonical pattern — do not explore existing files to reverse-engineer patterns. Only read existing files for integration points (imports, symbols, types)
  • If a rule file is missing or ambiguous, raise the gap — do not substitute with codebase exploration
  • Skip when the developer opts out

Conventions

  • Use AIDEV-NOTE:, AIDEV-TODO:, AIDEV-QUESTION: anchors near non-trivial code (exception to no-comments rule)