Przejdź do treści
Biblioteka skilli
Programowanie · Przegląd i audyt

improve-codebase-architecture

/improve-codebase-architecture

Skanuje bazę kodu pod kątem pogłębiania modułów, pokazuje wyniki w wizualnym raporcie HTML i przepytuje wybraną przez użytkownika propozycję.

Repozytorium
runwield ↗
Licencja
MIT
Ostatnia zmiana repozytorium
27.10.2026

Ocena i bezpieczeństwo

100/ 100Klasa: dobry
Format25 / 25
Frontmatter z nazwą i opisem, poprawna nazwa, opis do 1024 znaków, nazwa zgodna z folderem.
Odkrywalność25 / 25
Opis mówi, kiedy użyć skilla, ma sensowną długość i jest w 3. osobie.
Treść35 / 35
Co najmniej 150 słów i do 500 linii, nagłówki, listy kroków, przykłady albo kod.
Higiena15 / 15
Bez zaślepek typu TODO, bez ścieżek Windows, z licencją.
Ryzykobrak sygnałów w skanie
Pliki w paczce
6
Skrypty
0
Komentarze HTML
0
Adresy URL w SKILL.md
1
Przestarzałość

Brak sygnałów. Repozytorium zmienione 27.10.2026, bez odwołań do wycofanych modeli i API.

Licencja

MIT, otwarta: można używać i zmieniać, z zachowaniem informacji o autorze.

Co robi i kiedy

Skanuje bazę kodu pod kątem pogłębiania modułów, pokazuje wyniki w wizualnym raporcie HTML i przepytuje wybraną przez użytkownika propozycję.

Oryginalny opis (EN)

Scan a codebase for deepening opportunities, present them as a visual HTML report, then grill through whichever one the user picks. Use when the user wants to improve architecture, find refactoring opportunities, consolidate tightly-coupled modules, or make the codebase more testable and AI-navigable.

Jak działa

  1. Process
Sekcje z nagłówków SKILL.md, w oryginale · 89 linii, 690 słów
Podgląd SKILL.md
---
name: improve-codebase-architecture
description: Scan a codebase for deepening opportunities, present them as a visual HTML report, then grill through whichever one the user picks. Use when the user wants to improve architecture, find refactoring opportunities, consolidate tightly-coupled modules, or make the codebase more testable and AI-navigable.
license: MIT; complete terms in LICENSE
license_details: This complete `src/skills/improve-codebase-architecture/` Skill package is licensed under MIT; see `LICENSE`. It is
    adapted from Matt Pocock's skills repository at `https://github.com/mattpocock/skills/`. This nested license
    covers only this Skill package and does not change the root RunWield license or any other repository path.
---

# Improve Codebase Architecture

Surface architectural friction and propose **deepening opportunities** — refactors that turn shallow modules into deep
ones. The aim is testability and AI-navigability.

This skill uses the shared [codebase-design](../codebase-design/SKILL.md) vocabulary: **module**, **interface**,
**implementation**, **depth**, **deep**, **shallow**, **seam**, **adapter**, **leverage**, and **locality**. Use those
terms exactly in every suggestion.

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

## Process

### 1. Explore

Read the project's `docs/domain-language.md` if it exists and any ADRs in the area you're touching first. Then read
[codebase-design](../codebase-design/SKILL.md) and its [DEEPENING.md](../codebase-design/DEEPENING.md) reference.

Then use `delegate_agent` with `mode: "read"` to walk the codebase in a bounded Delegated Agent Session. Don't follow
rigid heuristics — explore organically and note where you experience friction:

- Where does understanding one concept require bouncing between many small modules?
- Where are modules **shallow** — interface nearly as complex as the implementation?
- Where have pure functions been extracted just for testability, but the real bugs hide in how they're called (no
  **locality**)?
- Where do tightly-coupled modules leak across their seams?
- Which parts of the codebase 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, concentrates" is the signal you want.

### 2. Present candidates as an HTML report

Write a self-contained HTML report to the OS temp directory; do not write it into the repo. Resolve the temp directory
from `$TMPDIR`, then `/tmp`, then `%TEMP%` on Windows, and write to:

```text
<tmpdir>/architecture-review-<timestamp>.html
```

Open it for the user when the environment allows it. If opening the file requires approval or is unavailable, report the
absolute path.

The report uses Tailwind via CDN for layout and Mermaid via CDN for graph-shaped diagrams. Use hand-built HTML/CSS/SVG
when a custom before/after visual better communicates the architecture. See [HTML-REPORT.md](HTML-REPORT.md) for the
scaffold, diagram patterns, and style rules.

For each candidate, render a card with:

- **Files** — which files/modules are involved
- **Problem** — why the current architecture is causing friction
- **Solution** — plain English description of what would change
- **Benefits** — explained in terms of locality, leverage, and how tests would improve
- **Before / After diagram** — side-by-side, custom-drawn or Mermaid
- **Recommendation strength** — `Strong`, `Worth exploring`, or `Speculative`

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

**Use docs/domain-language.md vocabulary for the domain and [codebase-design](../codebase-design/SKILL.md) vocabulary
for the architecture.** If `docs/domain-language.md` defines "Order," talk about "the Order intake module" — not "the
FooBarHandler," and not "the Order service."

**ADR conflicts**: if a candidate contradicts an existing ADR, only surface it when the friction is real enough to
warrant revisiting the ADR. Mark it clearly (e.g. _"contradicts ADR-0007 — but worth reopening because…"_). Don't list
every theoretical refactor an ADR forbids.

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

### 3. Grilling loop

Once the user picks a candidate, drop into a grilling conversation. Walk the design tree with them — constraints,
dependencies, the shape of the deepened module, what sits behind the seam, what tests survive.

Side effects happen inline as decisions crystallize:

- **Naming a deepened module after a domain concept not in `docs/domain-language.md`?** Ask the user whether that term
  should become canonical. If they confirm, update `docs/domain-language.md` using the canonical
  domain-language-format.md bundled in `agent-definitions/document-formats/`.
- **Sharpening a fuzzy domain term during the conversation?** Ask the user to confirm the canonical term, avoided
  aliases, and any stable domain relationship or durable flagged ambiguity before updating `docs/domain-language.md`.
- **Architecture vocabulary is not domain language.** Do not add terms such as **module**, **interface**, **seam**,
  **adapter**, **depth**, **leverage**, or **locality** to `docs/domain-language.md`.
- **User rejects the candidate with a load-bearing reason?** Offer an ADR only when future architecture reviews would
  otherwise re-suggest the same candidate. Skip ephemeral reasons like "not worth it right now."
- **Want to explore alternative interfaces for the deepened module?** Use the design-it-twice process in
  [codebase-design/DESIGN-IT-TWICE.md](../codebase-design/DESIGN-IT-TWICE.md).
Pliki w paczce (6)
  • DEEPENING.md 3 KB
  • HTML-REPORT.md 4 KB
  • INTERFACE-DESIGN.md 3 KB
  • LANGUAGE.md 4 KB
  • LICENSE 1 KB
  • SKILL.md 6 KB

Wersje

RepozytoriumWynikLicencja
Ta strona · runwield/runwield100MIT
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
cravingmaker/skills100MIT

Migawka bazy z 13.11.2026 · wersja paczki fa2f81c29343 (skrót SHA-256 całej paczki)

Pobrania w ostatnich 30 dniach: 0 · ranking

Zgłoś problem z tym skillem: szkodliwa treść, błędny opis albo prośba autora o usunięcie.

Podobne skille

  • 100codebase-improve-architecture
    Eksploruje bazę kodu w poszukiwaniu usprawnień architektury i zwiększa testowalność przez pogłębianie płytkich modułów oraz łączenie modułów ściśle ze sobą sprzężonych.
  • 100jidoka-improve-architecture
    Przegląda bazę kodu pod kątem możliwości pogłębienia modułów, opisuje je w raporcie w czacie i zapisuje wybraną jako specyfikację.
  • 100architecture
    Wyszukuje możliwości usprawnienia architektury, płytkie moduły i szwy, konsoliduje ściśle sprzężone moduły i poprawia testowalność kodu.
  • 81architecture
    Wskazuje płytkie moduły i hipotetyczne szwy w bazie kodu, szuka okazji do refaktoryzacji i konsolidacji ściśle sprzężonych modułów, by kod był lepiej testowalny i czytelny dla AI.
  • 100deep-codebase-audit
    Znajduje okazje do pogłębienia architektury kodu, wskazuje tarcia i proponuje refaktoryzacje zamieniające płytkie moduły w głębokie, dla lepszej testowalności i bezpieczniejszej pracy agentów AI.
  • 100codebase-design
    Dostarcza wspólne słownictwo do projektowania głębokich modułów, szukania możliwości ich pogłębiania, wyboru położenia szwów i poprawy testowalności kodu.

Uwagi i zgłoszenia

Wiadomość trafi do Bartosza Sokolińskiego. Adres e-mail jest potrzebny tylko do odpowiedzi. Szczegóły w polityce prywatności.