CLAUDE.md for React

# CLAUDE.md

Project memory for Claude Code in this React repository. Read it before editing. Other agents can follow the same rules.

## Stack

This repository is a React app built from function components and hooks. Keep the bundler, router, and state library the repo already has.

## Layout

- Colocate a component with its styles and local helpers.
- Shared components live in one components directory. App state stays as low as it can.
- Do not invent a new folder taxonomy when the repo already has one.

## Commands

- Dev server: `npm run dev`
- Production build: `npm run build`
- Lint: `npm run lint`
- Tests: `npm test`

Use the script the repo already defines when it differs from the command above.

## Conventions

- Write function components and hooks. Do not add class components.
- Effects synchronize with an external system. They are not a data-loading layer if the app already has one.
- Give every control a label. Buttons do something; links go somewhere.
- Do not add a state library, router, or CSS framework that is not already a dependency.
- Lift state only when two siblings need it. Otherwise keep it local.
- Keys must be stable. Do not use the array index when the list can reorder.

## Testing

Add or update tests when behavior changes.

Prefer React Testing Library and test what the user can see and do. Mock network boundaries, not child components.

## Style

- Optimize for the next reader over the shortest diff.
- Comment only when the why is non-obvious.
- Name things the way neighboring files already do.
- Do not reformat code you did not change.

## Errors

- Fail at the boundary. Do not swallow errors.
- Show a recoverable error in the UI. An error boundary is appropriate for a subtree that can fail on its own.

## Scope

- Do the requested task. Do not refactor unrelated code.
- Match the rigor already in the repo. Fix what you touch.
- Ask one clarifying question only when the task cannot be finished without it. Otherwise state the assumption and continue.

## Avoid

- Do not disable a lint rule to hide a hooks dependency bug.
- Do not store derived data in state when a render can compute it.
- Do not fetch in an effect and forget a cancelled-request guard.
- Do not break keyboard access to make a click handler shorter.

## Done when

- The requested behavior works.
- The dev server still renders the screen you touched, and `npm test` passes if the repo has tests.
- The diff stays inside the task.
- You list anything you could not run.