Skip to content
Skills Library
Programming · Analysis

improve-codebase-architecture

/improve-codebase-architecture

Assess or improve an existing codebase's architecture when the user asks about module boundaries, coupling, scattered ownership, testability, change locality, deep modules, seams, or behavior-preserving structural refactoring. Use for cross-module design rather than ordinary diff review or a confirmed edge-case bug fix.

Repository
skills ↗
Licence
MIT
Last repository change
22.10.2026

Assessment and security

90/ 100Class: good
Format25 / 25
Frontmatter with name and description, valid name, description up to 1,024 characters, name matching the folder.
Discoverability25 / 25
Description explains when to use the skill, has a reasonable length and uses third person.
Content25 / 35
At least 150 words and at most 500 lines, headings, step lists, examples or code.
Hygiene15 / 15
No placeholders such as TODO, no Windows paths, with a licence.
Riskno signals detected in the scan
Files in this package
2
Scripts
0
HTML comments
0
URLs in SKILL.md
0
Deprecation

No signals detected. Repository changed on 22.10.2026, without references to retired models or APIs.

Licence

MIT, open: use and modify while retaining author attribution.

What it does and when to use it

Assess or improve an existing codebase's architecture when the user asks about module boundaries, coupling, scattered ownership, testability, change locality, deep modules, seams, or behavior-preserving structural refactoring. Use for cross-module design rather than ordinary diff review or a confirmed edge-case bug fix.

Original author description

Assess or improve an existing codebase's architecture when the user asks about module boundaries, coupling, scattered ownership, testability, change locality, deep modules, seams, or behavior-preserving structural refactoring. Use for cross-module design rather than ordinary diff review or a confirmed edge-case bug fix.

How it works

  1. Establish Scope
  2. Assess
  3. Refactor Safely
Original SKILL.md headings · 37 lines, 575 words
SKILL.md preview
---
name: improve-codebase-architecture
description: Assess or improve an existing codebase's architecture when the user asks about module boundaries, coupling, scattered ownership, testability, change locality, deep modules, seams, or behavior-preserving structural refactoring. Use for cross-module design rather than ordinary diff review or a confirmed edge-case bug fix.
---

# Improving Codebase Architecture

Find evidence-backed structural improvements that concentrate behavior and ownership behind smaller, clearer interfaces. Treat review, assessment, diagnosis, and planning requests as read-only. Improvement, refactoring, or implementation requests authorize in-scope local edits and non-destructive validation. Require confirmation before external writes, destructive actions, an incompatible public API or data migration, or material scope expansion.

## Establish Scope

1. Read repository instructions and the domain glossary, architecture documents, and ADRs relevant to the target. Missing optional architecture documents are not blockers.
2. Use the area, pain point, or behavior named by the user. Trace only its actual callers, contracts, dependencies, data and state ownership, tests, and directly affected runtime paths.
3. When no target is named, inspect recent change history and repeatedly modified paths to bias the assessment toward architecture where future work is likely. Widen the scan only when no meaningful hotspot emerges.
4. If multiple incompatible directions remain equally plausible, or the work would break a public API, require a migration, or cross the requested boundary, ask one focused question before choosing.

## Assess

Load [the architecture assessment reference](references/architecture-assessment.md) when evaluating candidates.

- Observe concrete friction: concepts split across files, callers coordinating the same policy, state with unclear ownership, wide or unstable interfaces, leaking dependencies, duplicated adaptation, or tests that must bypass the intended interface.
- Measure the interface by everything callers must know, including ordering, invariants, errors, configuration, side effects, and performance—not only method count.
- Apply the deletion test: reject a proposed module when deleting it would only move the same complexity into callers. Reject speculative seams, pass-through abstractions, style-only rearrangement, and abstractions without a demonstrated variation or ownership need.
- Compare the current and proposed ownership, interface, dependency direction, test surface, and migration path. Prefer the smallest structural change that improves locality or leverage without hiding important operational behavior.
- Keep claims tied to source, tests, history, or executable evidence. Label assumptions and unverified risks.

For an assessment-only request, return at most three candidates ordered by expected leverage, migration risk, and confidence. For each, include evidence paths, current friction, proposed seam and ownership, expected locality or leverage, migration risk, and a concrete verification method. Name the top recommendation and explain why it outranks the alternatives. Do not create a visual report unless the user asks for one.

## Refactor Safely

For an authorized implementation request:

1. Select one highest-confidence, bounded candidate. Do not bundle unrelated cleanup.
2. Establish a behavioral baseline with existing checks and, when practical, characterization or regression coverage at the current public contract.
3. Move ownership in small, reversible steps. Preserve externally observable behavior and existing contracts unless the request explicitly changes them; keep the worktree runnable between steps when practical.
4. Put policy at its owning module and adapt dependencies at the narrowest justified seam. Remove superseded paths instead of leaving parallel abstractions.
5. Run focused checks after each meaningful step, then affected integration tests and the repository gate. Reinspect callers, dependency direction, tests, and the final diff to confirm the candidate's claimed benefit was actually achieved.
6. Stop after the selected candidate is complete. Report changed ownership and interface, behavior evidence, checks run, residual risk, and any stronger candidate deferred because it needs a product or migration decision.

Use `review-code` for ordinary diff or pull-request correctness review. Use `harden-code-paths` for confirmed edge-case and failure-mode bugs; an architecture finding may explain the root cause, but do not turn this workflow into a generic bug sweep.
Files in this package (2)
  • SKILL.md 5 KB
  • references/architecture-assessment.md 4 KB

Versions

RepositoryScoreLicence
This page · narumiruna/skills90MIT
TerminalSkills/skills100Apache-2.0
callmeteus/gti-skills100MIT
akillness/jeo-skills100MIT
sammcj/agentic-coding100Apache-2.0
drvoss/everything-copilot-cli100MIT
hachemsoft/ia-toolkit100MIT
niekcandaele/claude-helpers100MIT
runwield/runwield100MIT

Database snapshot: 13.11.2026 · package version 75f37fccf02b (SHA-256 digest of the entire package)

Downloads in the last 30 days: 0 · ranking

Report a problem with this skill: harmful content, incorrect descriptions or an author’s removal request.

Similar skills

  • 100improve-ts-pkg-architecture
    Review architecture for a TypeScript package without nuxt.config.ts. Use for package-native refactors, exports, workspaces, module boundaries, and testability.
  • 100architecture
    This skill should be used when the user asks to "map the architecture", "show module dependencies", "analyze coupling", "dependency graph", "how are modules connected", "module boundaries", or mentions keywords related to architectural analysis and dependency mapping.
  • 90codebase-design
    Design and evaluate module interfaces, depth, seams, adapters, locality, and testability. Use when deciding what a module should hide, what callers should know, where dependencies should vary, whether an abstraction earns its cost, or how to make one subsystem easier to test and…
  • 90review-architecture
    Reviews the structural quality of code. Use when reviewing structural changes in a diff, checking a new or edited module boundary, or auditing the architecture of a codebase.
  • 100architecture
    Use when the user asks to improve architecture, find refactoring opportunities, surface deepening opportunities, consolidate tightly-coupled modules, or make a codebase more testable and AI-navigable. Surfaces shallow modules and hypothetical seams using a precise vocabulary…
  • 90architecture-deepening-review
    Review a codebase for architecture deepening opportunities: shallow modules, weak seams, scattered domain logic, low testability, high coupling, and AI-navigability friction. Use when the user asks for architecture improvement, refactoring opportunities, modularity, test seams,…

Feedback and reports

Your message goes to Bartosz Sokoliński. An email address is needed only for a reply. See the privacy policy.