Improve Codebase Architecture

Improve Codebase Architecture

Intent

Use this skill periodically (for example, weekly or after a burst of changes) to improve the structural quality of the codebase.

The goal is to make the code more “agent-friendly”: clear module boundaries, deeper units with simple interfaces, and less scattering of logic across many tiny files.

What to Look For

While exploring the repo, look for:

1. Scattered concepts

   • Understanding one concept (e.g., “orders”, “search”, “auth”) requires jumping between many small files.
   • Logic is split into thin wrappers and helpers that obscure the main flow.

2. Shallow modules

   • Modules that do very little beyond delegating, with real complexity spread out elsewhere.
   • Pure functions extracted solely for testability while the true behavior is in wiring code.

3. Tight coupling and integration risk

   • Modules that know too much about each other’s internals.
   • Cross-cutting concerns implemented ad-hoc in many places instead of via clear layers or utilities.

Workflow

1. Choose a target area

   • Pick a feature, domain, or subsystem experiencing pain: hard to change, buggy, or confusing.
   • Confirm with the user if they have specific hotspots they care about.

2. Map current structure

   • Identify the main entry points (routes, handlers, top-level components, jobs).
   • Trace how data and control flow through modules.
   • Note files or functions that are frequently touched together.

3. Identify deepening opportunities

   • Propose ways to:
     • Merge shallow wrappers into a deeper module that owns a concept end-to-end.
     • Introduce a clear service, use-case, or domain module that encapsulates messy flows.
     • Extract cross-cutting concerns (logging, validation, auth) into well-defined layers.

4. Propose refactor plans

   • For each opportunity, outline a small, testable refactor:
     • Current situation (1–2 sentences).
     • Proposed structure (e.g., “introduce OrderService that owns X/Y/Z”).
     • Expected benefits (testability, clarity, fewer hops).
   • Keep each refactor small enough to fit in a single PR or issue where possible.

5. Connect to testing and TDD

   • For each proposed deep module, describe how it would be tested (unit, integration, or end-to-end).
   • Suggest where a tdd-style workflow would help solidify new boundaries.

Output Format

When using this skill, summarize findings as:

## Architecture Findings
- [Finding 1: short title]
  - Symptoms:
  - Proposed change:
  - Benefits:

- [Finding 2]
  - Symptoms:
  - Proposed change:
  - Benefits:

You may optionally suggest related issues or PRs, or hand off to prd-to-issues if the refactor is large.

Style Guidelines

• Focus on clarity and leverage: a few well-chosen deep modules can simplify many features.
• Avoid massive, risky rewrites; prefer incremental, well-bounded improvements.
• Always ground recommendations in actual code you have inspected, not generic advice.
• Call out quick wins separately from larger, multi-step refactors.