Code organisation

One principle sits under everything here: what changes together lives together. Co-locate code that changes for the same reason; separate code that changes for different reasons. Apply it at three zoom levels — system → module → file — each the same rule at a different scale.

This skill is reference. Read the level you are working at.

Placing new code

A short procedure for the recurring question "where does this go?":

1. Name its reason to change in domain language — the feature or concept it serves. Done when you can finish "this changes when ___" without naming a technology.
2. Find the home that shares that reason — the module whose other code changes on the same trigger. Done when you have checked siblings at the right zoom level, not only the file you are already in.
3. Place it, or create a sibling. If a home fits, add it there; if none fits, create a new sibling at that zoom level, named for the concept. Done when the new code's neighbours are the things that change with it.
4. Confirm the feature did not scatter — one logical change should not force edits across many directories. Done when a typical change to this feature stays inside one module.

System level — the repository