# CLAUDE.md: Onboarding to an unfamiliar codebase

Use this when the project is new to you or has little documentation.

## 1. Map before changing (read-only)
- Identify languages, frameworks, and versions from manifests and lockfiles.
- Find how to run things: scripts, Makefile, CI config, Dockerfiles, README. Try the test command and record what happens.
- Locate entry points (main, routes, handlers, jobs, CLI commands) and the data layer (models, migrations, external APIs).
- Trace one real request or job end to end and write down the path.

## 2. Write it down
Create or update `docs/codebase-map.md` (and the short summary at the bottom of this file):
- How to set up, run, and test (exact commands that worked).
- Module map: folder -> responsibility.
- Key flows with file references.
- Conventions you observed (naming, error handling, patterns to copy).
- Risks: missing tests, dead code, surprising behavior, deprecated dependencies.

## 3. Change safely
- Follow existing patterns, even if you'd design it differently. Propose larger cleanups separately.
- Add characterization tests around code you must change when coverage is missing.
- Keep diffs small; don't reformat files you don't otherwise touch.
- Ask before changing build tooling, upgrading dependencies, or touching code paths you couldn't run locally.

## Summary (keep updated)
- Setup: `...` · Tests: `...` · Main entry: `...` (edit me)