mcclowes/ai-aware-code-structure
Use when deciding how to organise code in an AI-assisted codebase — whether to split or merge a file, where to draw module boundaries, how big a file should get, whether to separate logic from rendering/styles/data, whether to use barrel/index re-export files, or where types and test files should live. Triggers on "should I split this file", "this file is getting too big", "separate concerns", "where should this code live", "are barrel files worth it", "central types file or co-locate", "colocate tests or a tests folder", reviewing or refactoring file/module organisation, structuring a new component or feature, or any architecture decision where part of the audience is an AI coding agent. Apply this whenever someone is choosing how to lay code out across files and an LLM will be reading or editing it, even if they only say "refactor this" or "clean up the structure" without mentioning AI.
83
87%
Does it follow best practices?
Impact
82%
1.54xAverage score across 9 eval scenarios
Passed
No known issues
Evaluation results
79%
75%Structure a new data-export module
Advise file organisation for a new data-export module in a Next.js app
Start coarser, don't pre-split
0%
37%
Co-locate coupled job lifecycle
16%
100%
Abstraction over bare file split
0%
100%
~300-line split trigger
0%
100%
100%
58%Is a central 400-line types.ts a good idea?
Evaluate a central types.ts vs co-locating types in an AI-edited TS codebase
Co-locate type with owning module
37%
100%
Reframe single source of truth
16%
100%
Keep shared types shared, no scattering
83%
100%
Grounds in skipped cross-file lookup
33%
100%
86%
23%Review an over-split feature folder
Critique an over-split UserBadge feature folder for an AI-heavy codebase
Concludes over-split, consolidate coupled pieces
100%
87%
Identifies dumb-view-props smell
37%
100%
Keeps isolatable styles separate
50%
66%
100%
Are reflexive barrel files helping or hurting AI editing?
Evaluate reflexive barrel files in an AI-edited React/TS app
Drop reflexive barrels for direct imports
100%
100%
Grounds in agent indirection
100%
100%
Keeps deliberate public-API barrel
100%
100%
Names a concrete secondary cost
100%
100%
61%
61%Is a 420-line UserService god object the right call?
Critique a 420-line multi-responsibility UserService class
Recommends splitting by responsibility
0%
75%
Identifies independent seams
0%
33%
Ceiling and/or unrelated concerns
0%
83%
Pushes back on keep-together rationale
0%
50%
66%
-29%Organise a growing FastAPI route module
Lay out a growing FastAPI orders module for effective AI-assisted work
Applies to Python, not React-specific
100%
37%
Real abstraction over file split
100%
83%
Co-locate coupled, separate standalone
83%
66%
Isolation test / ~300-line guidance
100%
100%
73%
73%Should a clean, tested pricing function be inlined?
Decide whether a clean reused pricing abstraction should be inlined into a component
Recommends keeping the file
0%
75%
Abstraction-over-structure heuristic
0%
100%
Typed call site, no internals needed
0%
66%
Rejects inline-so-agent-sees-it argument
0%
50%
78%
-11%Should a 550-line grab-bag helpers.ts stay as one file?
Decide whether a 550-line grab-bag helpers.ts should be split
Recommends splitting
100%
87%
Justified by concerns and/or ceiling
100%
83%
Clean boundaries (isolation test)
100%
83%
Corrects misapplied defense
62%
62%
96%
12%Inline Avatar in 12 components, or extract a shared one?
Decide whether a repeated pure Avatar should be extracted or kept inline
Recommends extracting shared Avatar
100%
100%
Pure-presentation isolation test
50%
100%
Rejects keep-inline argument
100%
83%
Frames as real abstraction
83%
100%
- Evaluated
- Agent
- Claude Code
- Model
- Claude Sonnet 4.6
Table of Contents