Raw view: Legacy Codebase CLAUDE.md

No invisible, zero-width, or bidi-control characters detected.

# {{PROJECT_NAME}} (legacy)

{{LANGUAGE_AND_VERSION}} codebase, in production for years, with partial tests and little documentation. The code is the spec. Assume every odd-looking branch exists because a customer hit that case.

## Commands

| Task | Command |
|------|---------|
| Build | `{{BUILD_COMMAND}}` |
| Test | `{{TEST_COMMAND}}` |
| Run the characterization suite only | `{{TEST_COMMAND}} tests/characterization` |

Definition of done: `{{BUILD_COMMAND}}` and `{{TEST_COMMAND}}` exit 0 with the same number of passing tests as before plus the ones you added. Paste before/after test counts. Never mark a test skipped to get there.

## Ground rules

- No rewrites. Do not propose or start a from-scratch replacement of a module, no matter how bad it looks. Improve it in place, behind a test.
- Change the smallest thing that satisfies the task. One behavior change per PR. Refactoring and behavior changes go in separate commits so a reviewer can verify the refactor is behavior-neutral.
- Do not fix bugs you were not asked to fix. Log them in `{{DISCOVERIES_FILE}}` (see below) and mention them in the report.
- Do not "modernize" in passing: no reformatting whole files, renaming for taste, upgrading dependencies, or swapping libraries. Formatting a line you did not change is a diff reviewers must read.
- Preserve public interfaces, database schemas, file formats, CLI flags, and error messages byte for byte unless the task says otherwise. Something downstream parses them.
- Dead-looking code is not dead until a `grep` across the whole repo, the SQL, the config, and the templates proves nothing references it, and you have said so in the report.

## Characterization tests first

Before changing any function that lacks tests:

1. Write tests in `tests/characterization/test_<module>.py` (or the language equivalent) that call the existing code and assert whatever it currently returns, including the weird cases. The goal is to pin current behavior, not to judge it.
2. Cover: the happy path, each early return, each caught exception, and at least one input from real data if fixtures exist in `tests/fixtures/`.
3. Run them. They must pass against the unchanged code. Commit them separately with the message `test: characterize <module>`.
4. Now make the change. If a characterization test breaks, either the change is wrong or the old behavior was a bug; say which, and if it is a bug, get confirmation before changing the assertion.

Use golden-master/snapshot output for anything that produces a report, a file, or a large structure: capture the current output into `tests/golden/`, assert equality, and treat any diff as a question for a human.

## Strangler-fig pattern for larger changes

- New code lives in `{{NEW_DIR}}/`; legacy code stays in `{{LEGACY_DIR}}/`. New code may call legacy code; legacy code reaches new code only through a single adapter module per boundary.
- Replace one entry point at a time: route it to the new implementation behind a feature flag or config switch, run both and compare where feasible, then delete the legacy path only after the switch has been on in production and the task says to.
- Never copy a legacy function into `{{NEW_DIR}}/` and leave both. If you port it, the old one becomes a thin call into the new one.
- Shared state (globals, singletons, module-level caches) is the usual trap. Document each one you touch in `{{DISCOVERIES_FILE}}` with who reads and writes it.

## Documenting discoveries

Keep `{{DISCOVERIES_FILE}}` (checked in) as an append-only log. Add an entry whenever you learn something that is not obvious from the code or that cost you more than a few minutes:

```
## 2026-10-16 — Order totals are recomputed in two places
- `billing/calc.py:compute_total` and `reports/monthly.py:_total` disagree on rounding (half-up vs banker's).
- Found while: adding the discount field.
- Evidence: tests/characterization/test_calc.py::test_rounding_half_cent
- Status: not fixed (out of scope). Risk: monthly report off by cents.
```

Entries are facts with file paths and line references, not opinions. When an entry becomes a comment in the code or a ticket, link it and leave the entry in place. Read the file at the start of any task in an unfamiliar area; it is the closest thing to architecture docs this project has.

## Reading before writing

- Trace every caller of the function you are changing (`grep -rn "function_name" --include=*.{ext}`) and list them in the report. Check templates, SQL, config, and shell scripts too; legacy systems call code by string.
- Read the git history of the file (`git log --follow -p -- <path> | head -200`) for the lines you touch. Commit messages from ten years ago often explain the odd branch.
- If a comment and the code disagree, the code is right and the comment is a discovery entry.

## When to ask first

Stop and ask before: deleting any file or function, changing a database schema or a persisted format, changing anything under `{{LEGACY_DIR}}/` that has no characterization test and cannot be given one, touching build or deploy scripts, or when two characterization tests contradict each other.