Move the Files Before You Touch the Architecture
AI coding agents locate files by path semantics, not memory, so a feature scattered across directories costs extra retrieval hops and produces missed edits no matter how capable the model. Directory rearrangement changes no behavior, lowers the cost of every future edit and agent call, and is one of the cheapest high-leverage changes an AI-assisted workflow can make.
Most "this codebase is getting messier" complaints trace back to file placement, not architecture. Features get sliced across controllers/, services/, models/, and utils/ directories, so changing one feature means opening four folders. Architecture rewrites alter dependency direction and fail silently at release; directory moves break loudly, because a missed import errors instantly and tests go red. The ordering argument: do the work whose failure is visible first, and only touch architecture when dependency cycles or duplicated concepts are the real problem.
A bundled Python audit script counts four metrics without reading code: how many directories a feature keyword spans, how many imports cross directories, maximum source depth, and the file count of the most crowded directories. A --demo mode generates two 16-file samples with identical files and dependencies. Layered by type, the 'order' feature spans 3 directories with 12 cross-directory imports; sliced by feature, it sits in 1 directory with 4 imports: an 8-import, 67% reduction with not a single file added or removed. The sliced layout sits one level deeper, correctly read as position rather than scatteredness.
Migration follows five steps: create a features/ folder and rule first, move an entire feature whenever you touch one of its files, use git mv and never mix moves with content changes, run the tests after each move, and wait two weeks before the next feature. A mid-size project migrates naturally in two to three months, and stopping on any day still leaves a releasable codebase. AI agents locate files by path semantics via glob and grep, so directory names are the only classification tag they see; scattered features cost extra retrieval hops, extra tokens, and missed edits.
Preferring work whose failure is visible is the real engineering claim behind "move first": a broken import that fails instantly is safer than a silent semantic drift users only notice at release.
As AI coding agents do more of the editing, folder layout becomes the interface the model reads, not just a human convenience; scattered features produce missed edits because the layout never told the model those files belong together.
"Move on touch" converts a risky big-bang refactor into dozens of zero-risk small moves, which changes the review problem: a 3,000-line diff gets no review, but one feature moved per commit gets a real one.
The measured numbers come from synthetic samples generated by the script, not a production repo; the metric definitions and code generalize, while the specific 12-to-4 reduction is an illustration, not a benchmark of a real codebase.