improve-codebase-architecture

Files (9)

• APROFUNDAMENTO.md
• DEEPENING.md
• DESIGN-DE-INTERFACE.md
• HTML-REPORT.md
• INTERFACE-DESIGN.md
• LANGUAGE.md
• LINGUAGEM.md
• RELATORIO-HTML.md
• SKILL.md

SKILL.md (first lines)

# Improve Codebase Architecture

Expose architectural friction and propose **deepening opportunities** — refactors that turn shallow modules into deep modules. The goal is testability and AI navigability.

## Glossary

Use these terms exactly in every suggestion. Consistent language is the focal point — do not drift into "component," "service," "API," or "boundary." Full definitions in [LINGUAGEM.md](LINGUAGEM.md).

- **Module** — anything with an interface and an implementation (function, class, package, slice).
- **Interface** — everything a caller needs to know to use the module: types, invariants, error modes, ordering, configuration. Not just the type signature.
- **Implementation** — the internal code.
- **Depth** — leverage at the interface: lots of behavior behind a small interface. **Deep** = high leverage. **Shallow** = interface nearly as complex as the implementation.
- **Seam** — where an interface lives; a place where behavior can be changed without editing in place. (Use this term, not "boundary.")
- **Adapter** — a concrete thing that satisfies an interface at a seam.
- **Leverage** — what callers gain from depth.
- **Locality** — what maintainers gain from depth: change, bugs, knowledge concentrated in one place.

Key principles (see [LINGUAGEM.md](LINGUAGEM.md) for the full list):

- **Deletion test**: imagine deleting the module. If the complexity disappears, it was a pass-through. If the complexity reappears in N callers, it was pulling its weight.
- **The interface is the test surface.**
- **One adapter = hypothetical seam. Two adapters = real seam.**

This skill is *informed* by the project's domain model. The domain language names good seams; ADRs record decisions the skill should not re-litigate.

## Process

### 1. Explore

First read the project's domain glossary and any ADRs in the area you're operating in.

Then use the Agent tool with `subagent_type=Explore` to traverse the code. Do not follow rigid heuristics — explore organically and note where you experience friction:

- Where does understanding a concept require jumping between many small modules?
- Where are modules **shallow** — interface nearly as complex as the implementation?
- Where were pure functions extracted just for testability, but the real bugs hide in how they are called (lacking **locality**)?
- Where do tightly coupled modules leak through their seams?
- Which parts of the code are untested, or hard to test through their current interface?

Apply the **deletion test** to anything you suspect is shallow: would deleting it concentrate complexity or just move it? A "yes, it concentrates" is the signal you want.

### 2. Present candidates as an HTML report

Write a self-contained HTML file in the OS temp directory so nothing lands in the repository. Resolve temp dir from `$TMPDIR`, fallback to `/tmp` (or `%TEMP%` on Windows), and write to `<tmpdir>/architecture-review-<timestamp>.html` so each run produces a fresh file. Open it for the user — `xdg-open <path>` on Linux, `open <path>` on macOS, `start <path>` on Windows — and say the absolute path.

The report uses **Tailwind via CDN** for layout and styling, and **Mermaid via CDN** for diagrams where a graph/flow/sequence communicates structure reliably. Mix Mermaid with handcrafted CSS/SVG visuals — use Mermaid when relationships are graph-shaped (call graphs, dependencies, sequences), and handcrafted divs/SVG when you want something more editorial (mass diagrams, cross-sections, collapse animations). Each candidate gets a **before/after visualization**. Be visual.

For each candidate, the same template as before, but rendered as a card:

- **Files** — which files/modules are involved
- **Problem** — why the current architecture is causing friction
- **Solution** — plain-language description of what would change
- **Benefits** — explained in terms of locality and leverage, and how tests would improve
- **Before / After Diagram** — side by side, handcrafted, illustrating the shallowness and the deepening
- **Recommendation strength** — one of `Strong`, `Worth exploring`, `Speculative`, rendered as a badge

End the report with a **Top recommendation** section: which candidate you'd tackle first and why.

**Use vocabulary from CONTEXT.md for the domain, and vocabulary from [LINGUAGEM.md](LINGUAGEM.md) for the architecture.** If `CONTEXT.md` defines "Order," talk about "the Order entry module" — not "the FooBarHandler," and not "the Order service."

**ADR conflicts**: if a candidate contradicts an existing ADR, only present it when the friction is real enough to justify revisiting the ADR. Mark it clearly on the card (e.g., an alert: *"contradicts ADR-0007 — but worth reopening because…"*). Do not list every theoretical refactor that an ADR prohibits.

See [RELATORIO-HTML.md](RELATORIO-HTML.md) for the full HTML scaffold, diagram patterns, and style guidance.

DO NOT propose interfaces yet. After the file is written, ask the user: "Which of these would you like to explore?"

### 3. Grilling loop

When the user picks a candidate, enter a grilling conversation. Walk the design tree with them — constraints, dependencies, the shape of the deepened module, what lives behind the seam, which tests survive.

Side effects happen inline as decisions crystallize:

- **Naming a deepened module with a concept not in `CONTEXT.md`?** Add the term to `CONTEXT.md` — same discipline as `/grill-with-docs` (see [FORMATO-CONTEXT.md](../entrevista-com-docs/FORMATO-CONTEXT.md)). Create the file on demand if it doesn't exist.
- **Sharpening a vague term during the conversation?** Update `CONTEXT.md` right there.
- **User rejects the candidate with a solid reason?** Offer an ADR, framed as: *"Do you want me to record this as an ADR so future architecture reviews don't suggest it again?"* Only offer when the reason is genuinely necessary for a future explorer to avoid re-suggesting the same thing — skip ephemeral reasons ("not worth it right now") and self-evident ones. See [FORMATO-ADR.md](../entrevista-com-docs/FORMATO-ADR.md).
- **Want to explore alternative interfaces for the deepened module?** See [DESIGN-DE-INTERFACE.md](DESIGN-DE-INTERFACE.md).

From hcb2019/claude-code-skills, MIT.

More from hcb2019/claude-code-skills