Home › Agent workflows › Legacy codebase onboarding CLAUDE.md

Legacy codebase onboarding CLAUDE.md

CLAUDE.md workflow for an agent joining an unfamiliar or legacy codebase: map it, document it, then change it safely.

Claude Code (CLAUDE.md)Agent workflows

Copy CLAUDE.md

How to use

Save this as CLAUDE.md in your repository root, commit it, and your agent will pick it up automatically. Edit the commands to match your project.

Note: Review and test before use. Provided as is, without warranty. See Terms.

# 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)