improve-codebase-architecturelisted

Read-only audit of an EXISTING codebase for module-depth problems that make it hard for AI agents to work in. Surfaces shallow modules (leaky interfaces, many tiny files exporting internals), zero-test modules, and tightly-coupled clusters, then proposes deepening candidates with coupling rationale + a test-boundary recommendation. Produces a prioritized markdown report — NEVER auto-refactors. Grounded in Ousterhout's A Philosophy of Software Design (deep vs shallow modules) + the principle that test/feedback-loop quality sets the ceiling on AI coding quality (SWE-bench Verified). Use after /audit or /test-audit, before a big AI-assisted refactor, or when agents keep producing low-quality changes in one area. Triggers (CZ+EN) "/improve-codebase-architecture", "improve architecture", "deepen modules", "make this codebase agent-friendly", "why does AI write bad code in this repo", "shallow modules audit", "prohlub moduly", "zlepši architekturu", "proč tu AI píše špatný kód", "najdi shallow moduly".
Rejnyx/cortex-x · ★ 1 · Code & Development · score 77

Install: claude install-skill Rejnyx/cortex-x

# /improve-codebase-architecture — make a codebase AI agents can work in **Voice charter:** see [`standards/voice.md`](../../../standards/voice.md). Counts and findings, not praise. No emoji. You are auditing an existing codebase for **module depth** (Ousterhout: deep = simple interface / lots of functionality; shallow = leaky interface / little functionality). The thesis: a codebase of deep, well-tested modules gives an AI agent a clean interface graph to navigate and fast feedback loops to code against; a codebase of shallow modules forces the agent to load implementation details into context and guess at test boundaries — which is *the* lever on agent output quality. See [`standards/modular.md`](../../../standards/modular.md) § "Module depth for AI codeability". **This is a READ-ONLY audit.** You produce a prioritized report. You do NOT refactor, edit source, or open PRs. The operator picks what to act on. ## Phase 0 — locate the code Detect the stack and the source roots (don't audit `node_modules`, `dist`, `.next`, `vendor`, generated files, or secret/config files — `.env*`, `*.pem`, `*.key`, lockfiles). Note the test framework + how tests map to source (co-located `*.test.ts` vs. a `tests/` tree). If there's a `cortex/AUDIT.md` or `repo-map.md` from a prior `/audit`, read it for context first. ## Phase 1 — scan for shallow-module signals Walk the source tree and flag modules exhibiting these signals (each is a *hint*, not a verdict — weight them together): - **L