Documentation and legacy code

What you’ll be able to do

Produce documentation people actually read, and safely start improving code that has no tests and no docs.

Documentation that earns its place

Always tell Claude who the docs are for and what they need to do:

Write a README section "Local development" for a new engineer on Windows
or macOS. Cover prerequisites, setup, running tests and common errors.
Check every command against package.json and the scripts folder, and don't
include any command you couldn't verify.

Other high-value docs:

• Architecture overview: “One page, with a Mermaid diagram, for engineers joining the team.”
• ADR (Architecture Decision Record): “Write an ADR for why we chose Postgres over DynamoDB, based on @docs/notes/db-discussion.md.”
• API reference: “Generate reference docs for the public functions in @src/sdk/ from their types and JSDoc.”
• Changelog: “Summarise the commits since v1.4.0 into a user-facing changelog.”

Working with legacy code

1. Map it

Map @src/billing/invoice.js: its responsibilities, inputs and outputs, side
effects (DB, network, files), and the three riskiest areas to change. Mark
anything you're unsure about as UNCERTAIN.

2. Pin it with tests

Write characterization tests for calculateInvoice() that capture its current
behaviour, including the odd cases. If behaviour looks like a bug, keep the
test asserting the current behaviour but add a comment "suspected bug".

3. Document intent

Add a short header comment to each major function explaining what it does
and why, based on the code and git history. Keep the UNCERTAIN notes.

4. Improve in small steps, using the refactoring workflow from the last lesson.

Exercise

Pick the oldest, scariest file in a project you know, or a file in any older open-source project:

1. Ask for a map with UNCERTAIN markers
2. Add characterization tests for its main function
3. Write a “How this works” doc for the next person who opens it

Verify it worked

• You have a map of the file that marks uncertainties
• Characterization tests pass against the unchanged code
• You wrote a doc for a named reader, with every command checked

You’ve finished the free Foundations level. You can now use Claude Code confidently every day. The full course takes you through Control, Extend and Automate: hooks and permissions, MCP servers, Obsidian, skills, plugins and subagents, CI, the Agent SDK, and a capstone project.