codebase-architecture

# Codebase Architecture Decide a TypeScript codebase's structure, improve it where change has become expensive, and make it hold. The target is a codebase a reader can hold in their head: few surfaces, one canonical way to do each job, and behaviour where you would first look for it. - **IS:** folder structures, module contracts, request context and middleware pipelines, frontend/backend boundaries; architecture briefs; domain language and decision records; domain-informed deepening; guardrail tooling, CI gates, and agent wayfinding. - **IS NOT:** scaffolding a new repo (`scaffold-nextjs` for a Next.js turborepo, `scaffold-cli` for a TypeScript CLI), multi-tenant domain/isolation/routing (`multi-tenant-architecture`), the content of AGENTS.md itself (`agents-md`), a plan for one feature (`planning`), a diff-scoped cleanup pass (`tidy`), or structural review of a local diff (`tidy`). ## Contents - Modes - References - Design mode (new codebase) - Deepen mode (existing codebase) - Harden mode (make it stick) - Validation loop - Output template - Excuses - Gotchas - Related skills ## Modes Pick by the problem, not by the artifact, and say which you picked. | Mode | You are here when | Output | |------|-------------------|--------| | **Design** | Starting a new app, service, or surface, and the structure is not decided yet | An architecture brief | | **Deepen** | The code works, but change is expensive: concepts scattered, seams leaking, one idea under three names | Ranked...