improve-codebase-architecture · git:20260908.dc3bb11 · 2026-09-08 · sha256 12f19b28658fe9c7

improve-codebase-architecture git:20260908.dc3bb11A

Immutable. This exact content never changes and is served at /api/v1/blob/12f19b28658fe9c7.

No tool to install first
claude plugin marketplace add https://markdownregistry.com/mp/a/art_cxq5rzk5v5e7wujt/12f19b28658fe9c7247a31a367d177d29f496b29fc201b5f27282fbdbffd34ef.json

Then /plugin install improve-codebase-architecture@markdownregistry-cxq5rzk5v5e7wujt in Claude Code. It installs this exact version, the one graded A here, pinned to the commit it was graded at, and leaves it there.

---
name: improve-codebase-architecture
description: Audit a repository or broad subsystem for architectural friction, then rank evidence-backed improvement opportunities. Use for architecture reviews, technical-debt surveys, or requests to decide what structural work matters next. For a known interface or refactor that needs concrete design options, use codebase-design instead.
---

# Improve Codebase Architecture

Produce evidence-backed opportunities, not a generic refactoring wishlist.

Use this skill to discover and prioritize problems across a broad scope. Once the user selects a specific boundary or refactor, hand the design work to `codebase-design`.

## Scope and inspect

1. Read `AGENTS.md`, architecture docs, specifications, ADRs, and domain documentation.
2. Use the scope named by the user. Otherwise identify likely hot spots from recent history, recurring changes, defects, and tests; do not assume churn alone means poor design.
3. Inspect representative callers, implementations, dependencies, and tests. Use `codebase-design` as a vocabulary and reasoning reference while preserving repository terminology.
4. Note friction such as duplicated policy, scattered changes, leaky interfaces, unclear ownership, hard-to-test behavior, and shallow pass-through modules. Apply the deletion test and consider operational constraints.

Sub-agents are optional and may be used only when available, authorized, and useful for a large scope.

For simplification candidates, name what would disappear and what would take over its responsibilities: existing code, a specific library API, a platform feature, or nothing for confirmed dead behavior. Check callers, configuration, dynamic registration, and external contracts before claiming something is unused. A single implementation or caller is a lead to investigate, not proof that an abstraction should be removed.

Read existing debt notes when they explain a candidate's limits. Identify the condition that would justify revisiting the decision and whether current evidence meets it. Missing triggers are uncertainty to resolve, not permission to implement deferred work.

When dependency cycles, forbidden imports, or structural regression are part of the question, read [structural evidence](references/structural-evidence.md). Use comparable measurements and source-confirmed edges to assess candidates. Keep aggregate quality scores subordinate to repository contracts and observed maintenance cost.

Consider discovery, setup, invocation, feedback, and recovery costs for actual users, developers, agents, and operators when they explain architectural friction. Use [experience and interfaces](../codebase-design/references/experience-and-interfaces.md) for affected boundaries. Name the consumer and a representative failing or costly journey before recommending another interface or abstraction.

## Report

Default to a concise Markdown report in the response. Create a file only when the user requests an artifact. For each candidate include:

- affected paths and evidence
- current failure or maintenance cost
- proposed direction, without prematurely specifying a final interface
- compatibility and migration risks
- expected testability/locality benefit
- confidence: strong, worth exploring, or speculative

Rank candidates by expected benefit, risk, and relevance to likely future changes. Explicitly identify proposals that conflict with an ADR.

Show how each replacement preserves the required behavior and identify any semantic gap that prevents it. Keep correctness and verification obligations in the assessment. Line or dependency reductions are secondary estimates, and dependency removal requires checking remaining consumers. Do not invent savings against an implementation that was never built, or treat the absence of complexity findings as approval to ship.

If the user requests a visual HTML report, read [HTML-REPORT.md](HTML-REPORT.md), write it under a temporary directory, and provide its path. Do not load CDN assets or open a browser without appropriate network/GUI authorization.

## Explore a candidate

After the user selects a candidate, use `grilling` for consequential unresolved decisions and `codebase-design` for alternative interfaces. Use `domain-modeling` only when the work truly changes domain concepts. Do not edit code, glossaries, or ADRs until the user authorizes implementation or documentation changes.