← improve-codebase-architecture · 技能图谱

HTML Report Format

HTML 报告格式

The architectural review is rendered as a single self-contained HTML file in the OS temp directory. Tailwind and Mermaid both come from CDNs. Mermaid handles graph-shaped diagrams reliably; hand-built divs and inline SVG handle the more editorial visuals (mass diagrams, cross-sections). Mix the two — don't lean on Mermaid for everything, it'll start to look generic.

架构审查以单个独立的 HTML 文件呈现，写入操作系统临时目录。Tailwind 和 Mermaid 均通过 CDN 加载。Mermaid 可靠地处理图形状图表；手工构建的 div 和内联 SVG 处理更具编辑性的视觉元素（体量图、剖面图）。两者混合使用——不要事事依赖 Mermaid，否则会显得千篇一律。

Scaffold

脚手架

<!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>
<!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, and a compact legend: solid box = module, dashed line = seam, red arrow = leakage, thick dark box = deep module. No introduction paragraph — straight into the candidates.

仓库名称、日期以及紧凑的图例：实心框 = 模块，虚线 = 接缝，红色箭头 = 泄露，粗黑框 = 深模块。没有引言段落——直接进入候选方案。

Candidate card

候选方案卡片

The diagrams carry the weight. Prose is sparse, plain, and uses the glossary terms (from the /codebase-design skill) without ceremony.

图表承载主要内容。文字简洁朴素，直接使用词汇表中的术语（来自 /codebase-design 技能），不加修饰。

Each candidate is one <article>:

每个候选方案是一个 <article>：

  • Title — short, names the deepening (e.g. "Collapse the Order intake pipeline").
  • Badge row — recommendation strength (Strong = emerald, Worth exploring = amber, Speculative = slate), plus a tag for the dependency category (in-process, local-substitutable, ports & adapters, mock).
  • Files — monospaced list, font-mono text-sm.
  • Before / After diagram — the centrepiece. Two columns, side by side. See patterns below.
  • Problem — one sentence. What hurts.
  • Solution — one sentence. What changes.
  • Wins — bullets, ≤6 words each. e.g. "Tests hit one interface", "Pricing logic stops leaking", "Delete 4 shallow wrappers".
  • ADR callout (if applicable) — one line in an amber-tinted box.
  • 标题——简短，命名深化内容（例如"折叠 Order intake 管道"）。
  • 徽章行——推荐强度（Strong = 翡翠色，Worth exploring = 琥珀色，Speculative = 石板色），以及依赖分类标签（in-process、local-substitutable、ports & adapters、mock）。
  • 文件——等宽字体列表，font-mono text-sm。
  • 前后对比图——核心内容。两列并排。见下方模式。
  • 问题——一句话。什么在造成困扰。
  • 方案——一句话。什么会改变。
  • 收益——要点，每个≤6词。例如"测试命中一个接口"、"定价逻辑停止泄露"、"删除 4 个浅包装器"。
  • ADR 提示（如适用）——琥珀色框中的一行。

No paragraphs of explanation. If the diagram needs a paragraph to be understood, redraw the diagram.

不要解释段落。如果图表需要一段文字才能理解，那就重新画图。

Diagram patterns

图表模式

Pick the pattern that fits the candidate. Mix them. Don't make every diagram look the same — variety is part of the point.

选择适合候选方案的模式。混合使用。不要让每个图表看起来都一样——多样性本身就是目的之一。

Mermaid graph (the workhorse for dependencies / call flow)

Mermaid 图（依赖关系/调用流程的主力）

Use a Mermaid flowchart or graph when the point is "X calls Y calls Z, and look at the mess." Wrap it in a Tailwind-styled card so it doesn't feel parachuted in. Style with classDef to colour leakage edges red and the deep module dark. Sequence diagrams work well for "before: 6 round-trips; after: 1."

当重点在于"X 调用 Y，Y 调用 Z，看看这团乱麻"时，使用 Mermaid 的 flowchart 或 graph。将其包裹在 Tailwind 样式的卡片中，使其不显得突兀。使用 classDef 将泄露边染成红色，深模块染成深色。序列图适用于"之前：6 次往返；之后：1 次"的场景。

    <div class="rounded-lg border border-slate-200 bg-white p-4">
      <pre class="mermaid">
        flowchart LR
          A[OrderHandler] --> B[OrderValidator]
          B --> C[OrderRepo]
          C -.leak.-> D[PricingClient]
          classDef leak stroke:#dc2626,stroke-width:2px;
          class C,D leak
      </pre>
    </div>
    <div class="rounded-lg border border-slate-200 bg-white p-4">
      <pre class="mermaid">
        flowchart LR
          A[OrderHandler] --> B[OrderValidator]
          B --> C[OrderRepo]
          C -.leak.-> D[PricingClient]
          classDef leak stroke:#dc2626,stroke-width:2px;
          class C,D leak
      </pre>
    </div>

Hand-built boxes-and-arrows (when Mermaid's layout fights you)

手构建框与箭头（当 Mermaid 的布局不顺手时）

Modules as <div>s with borders and labels. Arrows as inline SVG <line> or <path> elements positioned absolutely over a relative container. Reach for this when you want the "after" diagram to feel like one thick-bordered deep module with greyed-out internals — Mermaid won't render that with the right weight.

模块以带边框和标签的 <div> 呈现。箭头以内联 SVG 的 <line> 或 <path> 元素实现，在相对定位的容器上绝对定位。当你希望"之后"图看起来像一个粗边框的深模块，内部呈灰色显示时使用——Mermaid 无法以正确的权重渲染这种效果。

Cross-section (good for layered shallowness)

剖面图（适用于分层浅度）

Stack horizontal bands (h-12 border-l-4) to show layers a call passes through. Before: 6 thin layers each doing nothing. After: 1 thick band labelled with the consolidated responsibility.

堆叠水平条带（h-12 border-l-4）来展示调用经过的层次。之前：6 个薄层，每层无所作为。之后：1 个粗条带，标注合并后的职责。

Mass diagram (good for "interface as wide as implementation")

体量图（适用于"接口与实现一样宽"）

Two rectangles per module — one for interface surface area, one for implementation. Before: interface rectangle is nearly as tall as the implementation rectangle (shallow). After: interface rectangle is short, implementation rectangle is tall (deep).

每个模块两个矩形——一个表示接口表面积，一个表示实现。之前：接口矩形几乎与实现矩形一样高（浅）。之后：接口矩形变矮，实现矩形变高（深）。

Call-graph collapse

调用图折叠

Before: a tree of function calls rendered as nested boxes. After: the same tree collapsed into one box, with the now-internal calls shown faded inside it.

之前：函数调用树呈现为嵌套框。之后：同一棵树折叠成一个框，现在内部的调用在其中以淡化方式显示。

Style guidance

样式指南

Lean editorial, not corporate-dashboard. Generous whitespace. Serif optional for headings (font-serif works well with stone/slate).

偏向编辑风格，而非企业仪表板。充足的空白。标题可选择衬线字体（font-serif 与 stone/slate 色系搭配效果良好）。

Colour sparingly: one accent (emerald or indigo) plus red for leakage and amber for warnings.

谨慎使用颜色：一种强调色（翡翠绿或靛蓝），红色表示泄露，琥珀色表示警告。

Keep diagrams ~320px tall so before/after sits comfortably side by side without scrolling.

保持图表约 320px 高，使前后对比能舒适地并排显示，无需滚动。

Use text-xs uppercase tracking-wider for module labels inside diagrams — they should read as schematic, not as UI.

图表内部的模块标签使用 text-xs uppercase tracking-wider——它们应读作示意图，而非 UI。

The only scripts are the Tailwind CDN and the Mermaid ESM import. The report is otherwise static — no app code, no interactivity beyond Mermaid's own rendering.

唯一的脚本是 Tailwind CDN 和 Mermaid ESM 导入。报告其他部分都是静态的——没有应用代码，没有超出 Mermaid 自身渲染的交互性。

Top recommendation section

首选推荐部分

One larger card. Candidate name, one sentence on why, anchor link to its card. That's it.

一个较大的卡片。候选方案名称、一句为什么选它的理由、指向其卡片的锚点链接。仅此而已。

Tone

语气

Plain English, concise — but the architectural nouns and verbs come straight from the /codebase-design skill. Concision is not an excuse to drift.

简明英语，简洁——但架构名词和动词直接来自 /codebase-design 技能。简洁不是偏离的借口。

Use exactly: module, interface, implementation, depth, deep, shallow, seam, adapter, leverage, locality.

精确使用：模块、接口、实现、深度、深、浅、接缝、适配器、杠杆收益、局部性。

Never substitute: component, service, unit (for module) · API, signature (for interface) · boundary (for seam) · layer, wrapper (for module, when you mean module).

切勿替换：component、service、unit（代替模块）· API、signature（代替接口）· boundary（代替接缝）· layer、wrapper（在指模块时代替模块）。

Phrasings that fit the style:

符合风格的表述：

  • "Order intake module is shallow — interface nearly matches the implementation."
  • "Pricing leaks across the seam."
  • "Deepen: one interface, one place to test."
  • "Two adapters justify the seam: HTTP in prod, in-memory in tests."
  • "Order intake 模块是浅的——接口几乎与实现匹配。"
  • "定价逻辑在接缝处泄露。"
  • "深化：一个接口，一处测试。"
  • "两个适配器证明了接缝的合理性：生产环境用 HTTP，测试用内存。"

Wins bullets name the gain in glossary terms: "locality: bugs concentrate in one module", "leverage: one interface, N call sites", "interface shrinks; implementation absorbs the wrappers". Don't write "easier to maintain" or "cleaner code" — those terms aren't in the glossary and don't earn their place.

收益要点用词汇表中的术语命名收益："局部性：bug 集中在一个模块"、"杠杆收益：一个接口，N 个调用点"、"接口缩小；实现吸收包装器"。不要写"更易维护"或"代码更整洁"——这些术语不在词汇表中，没有资格出现。

No hedging, no throat-clearing, no "it's worth noting that…". If a sentence could be a bullet, make it a bullet. If a bullet could be cut, cut it. If a term isn't in the /codebase-design glossary, reach for one that is before inventing a new one.

不要含糊其辞，不要清嗓子的开场白，不要"值得注意的是……"。如果一个句子可以写成要点，就写成要点。如果一个要点可以删掉，就删掉。如果一个术语不在 /codebase-design 词汇表中，先找一个已有的词汇，不要发明新词。