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
criteria.jsonevals/scenario-2/
{
"context": "A 400-line central src/types.ts is imported everywhere, defended as 'single source of truth'. The criteria check whether the answer co-locates types by default, reframes the SoT idea, keeps genuinely shared types central without scattering, and grounds it in the agent skipping the cross-file lookup.",
"type": "weighted_checklist",
"checklist": [
{
"name": "Co-locate type with owning module",
"description": "Recommends co-locating a type with the module that owns it as the default, rather than a central types.ts",
"max_score": 8
},
{
"name": "Reframe single source of truth",
"description": "Reframes 'single source of truth' as defined-once, not all-in-one-file",
"max_score": 6
},
{
"name": "Keep shared types shared, no scattering",
"description": "Keeps genuinely shared/global types in a shared or feature-level file and does NOT advise one-type-per-file scattering",
"max_score": 6
},
{
"name": "Grounds in skipped cross-file lookup",
"description": "Grounds it in the agent skipping the cross-file lookup — the central types file is the sibling it won't open",
"max_score": 6
}
]
}