跪拜 Guibai
← All articles
AI Programming · Architecture · Python

Move the Files Before You Touch the Architecture

By ENCI ·
Read original on juejin.cn ↗ Google Translate ↗ Alt translation

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.

Summary

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.

Takeaways
— Most "messy project" complaints come from feature files spread across type-based directories (controllers/, services/, models/, utils/), not from wrong architecture.
— Architecture changes fail silently at release as subtle interface shifts; directory moves fail instantly as broken imports, so moving files carries near-zero regression risk.
— The audit script counts four metrics without reading code: directories a feature keyword spans, cross-directory imports, max source depth, and files per directory.
— --demo generates two 16-file samples with identical files and dependencies; the 'order' feature spans 3 directories in one layout and 1 in the other.
— Cross-directory imports drop from 12 to 4, a 67% cut, purely from reorganizing the same files; the sliced layout is one level deeper, but depth is position, not scatteredness.
— Migration is five steps: create features/ with a rule, move an entire feature on touch, use git mv without mixing moves and content changes, run tests right after each move, wait two weeks before the next feature.
— AI finds files by glob/grep on path names, so directory names are its only classification tag; scattered features mean more retrieval hops, more tokens, and missed edits.
Conclusions

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.

Concepts & terms
Package by Layer
Organizing source files by technical role (controllers, services, models, utils). Comfortable in small projects, but one feature's files end up scattered across several directories as the project grows.
Package by Feature
Organizing source files by business feature (features/order/, features/user/), keeping one feature's files together so a single directory holds the full context.
Cross-directory import
A source file importing a module outside its own directory. Counted as a coupling metric; each one is a directory hop paid every time a feature is read.
Move-on-touch migration
A team rule to move a file's entire feature whenever one of its files is edited, letting the new structure grow organically instead of through a big-bang rewrite.
AGENTS.md / CLAUDE.md
Local instruction files placed inside subdirectories that AI coding agents read as the authoritative context for that directory, letting rules follow the directory structure.
Source: juejin.cn ↗ Google Translate ↗ Backup ↗