AGENT SKILL

improve-codebase-architecture

Scan a codebase for deepening opportunities, present them as a visual HTML report, then grill through whichever one you pick.

License 许可
MIT
最近更新
2026-11-12
Stars
★ 2
Forks
0

01 前言 Front Matter

name
improve-codebase-architecture
description
Scan a codebase for deepening opportunities, present them as a visual HTML report, then grill through whichever one you pick.
disable-model-invocation
true

02 资源文件 1

03 SKILL.md 正文

<!-- vendored: mattpocock/skills@fcf0071 skills/engineering/improve-codebase-architecture (MIT). -->

Improve architecture

Find refactors that turn shallow modules into deep ones. Load nt-vendor:codebase-design and use its terms exactly.

1. Explore

Decide where to look before looking. If the user named a module, subsystem, or pain point, start there. Otherwise read back through git log --oneline for the areas that change most often, because deepening pays off where change keeps happening.

Read CONTEXT.md and any ADRs for that area. Then spawn one agent to walk the code and note where it is hard to follow:

  • one concept spread across many small modules;
  • shallow modules;
  • functions extracted for testing while the bugs sit in how they are called;
  • coupled modules that leak across their seams;
  • code that is untested, or hard to test through its interface.

Apply the deletion test to anything that looks shallow.

2. Report

Write a self-contained architecture-review-<timestamp>.html to the OS temp directory, so nothing is added to the repo. Open it with the platform's open command and tell the user the absolute path. Follow HTML-REPORT.md.

Each candidate gets the files involved, the problem, the solution, the gain in locality, leverage, and tests, a before-and-after visual, and a strength of Strong, Worth exploring, or Speculative. Name domain concepts with the words in CONTEXT.md. Mention a conflict with an ADR only when the problem is serious enough to reopen that ADR. End with one top recommendation.

Do not propose interfaces yet. Ask the user which candidate to explore.

3. Work through the choice

Question the user about the chosen candidate: its constraints, its dependencies, where the seam goes, and which tests survive. As decisions settle:

  • add a new or sharpened domain term to CONTEXT.md right away;
  • offer an ADR when the user rejects a candidate for a lasting reason that a later review would need in order not to suggest it again;
  • for alternative interfaces, use the design-it-twice pattern in codebase-design.

04 同仓库更多 Skills

notambourine
notambourine/agent-plugins

human-voice

Humanize prose by choosing a surgical voice edit or a structural rewrite. Use for AI-sounding drafts, anti-slop passes, editorial reviews, and requests to preserve an author's voice.

★ 2
notambourine
notambourine/agent-plugins

install-anti-slop

Install and configure the anti-slop Oxlint plugin in a local TypeScript or JavaScript repository. Use whenever a user asks to add anti-slop lint rules, copy the anti-slop plugin, configure opinionated Oxlint rules, or migrate an existing local anti-slop setup.

★ 2
notambourine
notambourine/agent-plugins

eli5

Explain a topic like I'm a 5 year old. Use when the user types /eli5 <topic> or asks for a dead-simple picture explainer of how something works.

★ 2
notambourine
notambourine/agent-plugins

codebase-design

Shared vocabulary for designing deep modules. Use when the user wants to design or improve a module's interface, find deepening opportunities, decide where a seam goes, make code more testable or AI-navigable, or when another skill needs the deep-module vocabulary.

★ 2
notambourine
notambourine/agent-plugins

audit-codebase

Read-only whole-codebase audit for simplifications in data structures, state representation, control flow, algorithms, and ownership. Inventories every subsystem as a coverage contract, reviews each one in a bounded subagent, verifies each finding against the repo, then audits its own coverage. Never edits, runs tests, commits, or pushes. Use for "audit this codebase", "find simplifications", or a pre-refactor survey.

★ 2
notambourine
notambourine/agent-plugins

crawl

Crawl a site with Screaming Frog and turn the output into findings a repo can act on. Use for SEO crawls and site audits, redirect or structured-data checks, rich-result eligibility questions, or any request that starts from crawl output.

★ 2