Improve Codebase Architecture
Deepen shallow modules safely by classifying dependencies and applying ports, adapters, and seam discipline before merging structural refactors.
Install
npx skills add https://github.com/vinvcn/mattpocock-skills-zh-cn --skill improve-codebase-architectureWhat is this skill?
- Four dependency categories: in-process, local-substitutable, remote-but-owned, true external
- Ports-and-adapters pattern for network-owned services with production vs in-memory adapters
- Seam rule: one adapter is indirection; two justified adapters define a real seam
- Distinguishes internal seams (test-only) from external interface seams
- Uses shared vocabulary: module, interface, seam, adapter (LANGUAGE.md)
Adoption & trust: 520 installs on skills.sh; 485 GitHub stars; 3/3 security scanners passed (skills.sh audits).
Recommended Skills
Improve Codebase Architecturemattpocock/skills
Zoom Outmattpocock/skills
Caveman Reviewjuliusbrussee/caveman
Requesting Code Reviewobra/superpowers
Receiving Code Reviewobra/superpowers
Request Refactor Planmattpocock/skills
Journey fit
Primary fit
Architecture deepening is done while building or refactoring backend modules, before quality gates at ship. Dependency categories (in-process through true external) and port/adapter guidance target backend module boundaries and testability.
Common Questions / FAQ
Is Improve Codebase Architecture safe to install?
skills.sh reports 3 of 3 security scanners passed. Review the Security Audits panel on this page before installing in production.
SKILL.md
READMESKILL.md - Improve Codebase Architecture
# Deepening 给定依赖关系，如何安全地 deepen 一组 shallow modules。假设你使用 [LANGUAGE.md](LANGUAGE.md) 中的词汇：**module**、**interface**、**seam**、**adapter**。 ## Dependency categories 评估 deepening candidate 时，先分类它的 dependencies。类别决定 deepened module 如何跨 seam 测试。 ### 1. In-process 纯计算、in-memory state、无 I/O。总是可以 deepen：合并 modules，并直接通过新 interface 测试。不需要 adapter。 ### 2. Local-substitutable 存在本地 test stand-ins 的 dependencies（Postgres 用 PGLite、in-memory filesystem）。如果 stand-in 存在，就可以 deepen。deepened module 在 test suite 中用 stand-in 测试。seam 是内部的；module 外部 interface 上不需要 port。 ### 3. Remote but owned (Ports & Adapters) 你自己控制的跨 network boundary 服务（microservices、internal APIs）。在 seam 处定义 **port**（interface）。deep module 拥有逻辑；transport 作为 **adapter** 注入。tests 使用 in-memory adapter。production 使用 HTTP/gRPC/queue adapter。 推荐表达：_"Define a port at the seam, implement an HTTP adapter for production and an in-memory adapter for testing, so the logic sits in one deep module even though it's deployed across a network."_ ### 4. True external (Mock) 你不控制的第三方服务（Stripe、Twilio 等）。deepened module 把外部 dependency 作为 injected port；tests 提供 mock adapter。 ## Seam discipline - **One adapter means a hypothetical seam. Two adapters means a real one.** 除非至少有两个 adapters 有正当理由（通常 production + test），否则不要引入 port。单 adapter seam 只是 indirection。 - **Internal seams vs external seams.** deep module 可以有 internal seams（implementation 私有，由自己的 tests 使用），也可以有 interface 上的 external seam。不要因为 tests 使用 internal seams，就把它们暴露到 interface 上。 ## Testing strategy: replace, don't layer - 一旦 deepened module interface 上有 tests，旧的 shallow modules unit tests 就变成浪费，删除它们。 - 在 deepened module 的 interface 上写新 tests。**interface is the test surface**。 - Tests 通过 interface 断言 observable outcomes，而不是 internal state。 - Tests 应经受 internal refactors；它们描述 behaviour，不描述 implementation。如果 implementation 改变时 test 也必须改变，那它测过了 interface。 # HTML Report Format Architectural review 会被渲染成一个 self-contained HTML file，放在 OS temp directory。Tailwind 和 Mermaid 都来自 CDNs。Mermaid 能稳定处理 graph-shaped diagrams；手写 divs 和 inline SVG 更适合 editorial visuals（mass diagrams、cross-sections）。两者混用，不要所有东西都依赖 Mermaid，否则看起来会很 generic。 ## Scaffold ```html <!doctype html> <html lang="en"> <head> <meta charset="utf-8" /> <title>Architecture review — {{repo name}}</title> <script src="https://cdn.tailwindcss.com"></script> <script type="module"> import mermaid from "https://cdn.jsdelivr.net/npm/mermaid@11/dist/mermaid.esm.min.mjs"; mermaid.initialize({ startOnLoad: true, theme: "neutral", securityLevel: "loose" }); </script> <style> /* small custom layer for things Tailwind doesn't cover cleanly: dashed seam lines, hand-drawn-feeling arrow heads, etc. */ .seam { stroke-dasharray: 4 4; } .leak { stroke: #dc2626; } .deep { background: linear-gradient(135deg, #0f172a, #1e293b); } </style> </head> <body class="bg-stone-50 text-slate-900 font-sans"> <main class="max-w-5xl mx-auto px-6 py-12 space-y-12"> <header>...</header> <section id="candidates" class="space-y-10">...</section> <section id="top-recommendation">...</section> </main> </body> </html> ``` ## Header Repo name、date，以及紧凑 legend：solid box = module，dashed line = seam，red arrow = leakage，thick dark box = deep module。不要 introduction paragraph，直接进入 candidates。 ## Candidate card Diagrams 承担主要信息量。Prose 要稀疏、直白，并直接使用 glossary terms（[LANGUAGE.md](LANGUAGE.md)），不要铺垫。 每个 candidate 是一个 `<article>`： - **Title** — 简短，命名 deepening（例如 “Collapse the Order intake pipeline”）。 - **Badge row** — recommendation strength（`Strong` = emerald，`Worth exploring` = amber，`Speculative` = slate），再加一个 dependency category tag（`in-process`、`local-substitutable`、`ports & adapters`、`mock`）。 - **Files** — monospaced list，`font-mono text-sm`。 - **Before / After diagram** — 核心内容。两列并排。见下面的 patterns。 - **Problem** — 一句话。痛点是什么。 - **Solution** — 一句话。改变什么。 - **Wins** — bullets，每条不超过 6 个词。例如 “Tests hit one interface”、“P