Vertical slices

Layered organisation (controllers/, services/, repositories/) makes every change a horizontal cut across the whole codebase. One feature edit touches five folders. Tests in one place, code in another, types in a third. Then six months in, every PR is a tour through the entire repo.

I organise by feature instead. A feature owns its handlers, its services, its types, its tests, its migrations, its fixtures. The seam between features is a package boundary, not a layer convention.

The canonical example is ait — see the package layout in personal/ait/references/core-architecture.md: @ait/core, @ait/connectors, @ait/postgres, @ait/qdrant, @ait/scheduler, @ait/gateway. Each one owns its slice end to end.

When this skill is active

You are about to:

• Create a new file or directory and have to decide where it goes
• Add a new feature or domain concept
• Propose monorepo package structure
• Refactor code that has accumulated into a shared utils/ or lib/ pile

The decision tree