Home / Everyday moves

Getting to grips with, documenting and migrating a codebase

On an unfamiliar repository, asking for an overview before making any changes shapes the questions that follow, and the /init command actually reads the project's content to write a first CLAUDE.md rather than starting from a blank page.

On an unfamiliar repository, opening the first file that comes to hand teaches you almost nothing about how the pieces fit together. A broad question, along the lines of give me an overview of this repository, usefully shapes what follows: Claude Code identifies entry points, declared dependencies and folder organisation before going into the detail of one specific function.

Mapping the territory before touching the code

The answer to this first question serves as a map for choosing the next one. Asking straight away how an isolated module works, without going through this overview first, amounts to fixing a part without knowing what it does in the complete machine. On a large project, two or three successive questions, each narrower than the last, replace a file by file exploration that would take hours.

Writing a first memory file with /init

The /init command actually reads the repository's content to produce a first CLAUDE.md: detected build and test commands, conventions visible in the existing code, the structure of the main folders. If a CLAUDE.md already exists, /init does not overwrite it, it proposes improvements based on what is already written. The generated file remains a first draft: it gets reread and trimmed down to keep only what is short and verified, as detailed in CLAUDE.md, the project's memory.

mkdir -p demo-migration/src && cd demo-migration
git init -q
printf 'def total(a, b):\n    return a + b\n' > src/calcul.py
printf 'lodash==4.17.21\n' > requirements.txt
git add -A && git commit -q -m "première version"
claude
> give me an overview of this repository, then generate a CLAUDE.md with /init

Treating documentation as source code

Outdated documentation costs more than no documentation at all, because it misleads instead of simply saying nothing. Asking for it to be generated while specifying the expected style, JSDoc or docstrings depending on the project's language, avoids a format nobody on the team ends up using. The same principle applies to a dependency update: asking for the list of breaking changes before modifying the lock file gives a basis for a decision, even though no dedicated command produces this list automatically. It is a way of phrasing the request, not a separate tool.

The exercise always ends with a review of the final diff produced by the migration or by the documentation generation, never with trust placed solely in the success message shown at the end of the task.