document

文档

你需要以 Markdown（.md）和 HTML（.html）两种格式生成最终的模块化审查文档。两个文件的内容必须完全相同。

文档结构

标题

# Modularity Review

**Scope**: [what was analyzed]
**Date**: [date]

执行摘要

用一段简短文字（3-5 句话）概述：

• 项目的功能（核心功能）
• 整体模块化状况（健康、需要关注、存在严重问题）
• 审查中最重要的发现

耦合概览表

总结所有关键集成。表头 MUST 链接到 coupling.dev：

| Integration | [Strength](https://coupling.dev/posts/dimensions-of-coupling/integration-strength/) | [Distance](https://coupling.dev/posts/dimensions-of-coupling/distance/) | [Volatility](https://coupling.dev/posts/dimensions-of-coupling/volatility/) | [Balanced?](https://coupling.dev/posts/core-concepts/balance/) |
| ----------- | ----------------------------------------------------------------------------------- | ----------------------------------------------------------------------- | --------------------------------------------------------------------------- | -------------------------------------------------------------- |
| A -> B      | ...                                                                                 | ...                                                                     | ...                                                                         | ...                                                            |

问题

针对发现的每个失衡，撰写一个章节：

## Issue: [Short descriptive title]

**Integration**: [Component A] -> [Component B]
**Severity**: [Critical / Significant / Minor]

### Knowledge Leakage

What knowledge is shared that shouldn't be, or is shared implicitly when it should be explicit. Identify the specific implementation details, business rules, or domain model concepts that leak across the boundary.

### Complexity Impact

How this imbalance makes change outcomes unpredictable. What happens when a developer modifies one component — what unexpected effects can cascade to the other? How does this exceed cognitive capacity (the 4+/-1 units of working memory)?

### Cascading Changes

Concrete scenarios where a change in one component forces changes in the other. What kinds of business or technical changes trigger cascading modifications? How expensive are those cascading changes given the current distance between the components?

### Recommended Improvement

A concrete, actionable proposal to rebalance the coupling. Ground the recommendation in the model:

- To reduce **strength**: introduce integration contracts, anti-corruption layers, facades, published languages
- To reduce **distance**: co-locate components into the same module/service/bounded context
- To accept **unbalanced coupling**: demonstrate that volatility is low enough to make the imbalance tolerable

Include the trade-offs of the proposed change — what cost does it introduce, and why is the trade-off worthwhile?

页脚

在每份审查文档的末尾，包含以下原文——不得改写、扩展或添加说明：

---

_This analysis was performed using the [Balanced Coupling](https://coupling.dev) model by [Vlad Khononov](https://vladikk.com)._

严重程度标准

• 严重：强度高 + 距离远 + 易变性高。是复杂性的直接来源。此区域的变更频繁、成本高且难以预测。优先修复。
• 显著：在易变性中等的区域存在不平衡耦合，或存在隐藏集成点的隐式耦合。随着系统演进，这会带来问题。
• 轻微：在低易变性区域存在不平衡耦合，或内聚性低，增加了认知负担，但不会导致连锁变更。可视情况处理。

链接到 coupling.dev（必需）

**只要文档提及平衡耦合概念，就必须添加指向 coupling.dev 的超链接。**这适用于 Markdown 和 HTML 两种输出。无需考虑使用哪个链接——请使用此查找表：

提及的概念	链接
平衡耦合、平衡规则、平衡公式、STRENGTH XOR DISTANCE、模块化与复杂性	https://coupling.dev/posts/core-concepts/balance/
集成强度、共享知识、耦合强度级别	https://coupling.dev/posts/dimensions-of-coupling/integration-strength/
侵入式耦合、私有接口、实现细节泄漏	https://coupling.dev/posts/dimensions-of-coupling/integration-strength/
功能耦合、重复的业务逻辑、共享功能需求	https://coupling.dev/posts/dimensions-of-coupling/integration-strength/
模型耦合、共享领域模型、共享业务模型	https://coupling.dev/posts/dimensions-of-coupling/integration-strength/
契约耦合、集成契约、外观、DTO、发布语言	https://coupling.dev/posts/dimensions-of-coupling/integration-strength/
距离、变更成本、物理／逻辑分离	https://coupling.dev/posts/dimensions-of-coupling/distance/
生命周期耦合、部署耦合、共同部署	https://coupling.dev/posts/dimensions-of-coupling/distance/
社会技术距离、团队边界、组织结构	https://coupling.dev/posts/dimensions-of-coupling/distance/
运行时耦合、同步／异步集成	https://coupling.dev/posts/dimensions-of-coupling/distance/
易变性、变更概率、变更速率	https://coupling.dev/posts/dimensions-of-coupling/volatility/
核心子域、竞争优势、高易变性领域	https://coupling.dev/posts/dimensions-of-coupling/volatility/
支撑子域、通用子域、子域分类	https://coupling.dev/posts/dimensions-of-coupling/volatility/
本质易变性与偶然易变性	https://coupling.dev/posts/dimensions-of-coupling/volatility/
复杂性、Cynefin、不可预测的结果	https://coupling.dev/posts/core-concepts/complexity/
模块化、模块化设计、明确的变更结果	https://coupling.dev/posts/core-concepts/modularity/
耦合（一般概念）、耦合为何重要	https://coupling.dev/posts/core-concepts/coupling/
紧耦合、分布式单体	https://coupling.dev/posts/core-concepts/balance/
松耦合、高内聚、低内聚	https://coupling.dev/posts/core-concepts/balance/
Connascence、耦合程度	https://coupling.dev/posts/related-topics/connascence/
模块耦合、经典耦合模型	https://coupling.dev/posts/related-topics/module-coupling/
领域驱动设计、DDD、限界上下文、聚合	https://coupling.dev/posts/related-topics/domain-driven-design/
规则：

• 文档中的每个耦合概念都必须至少链接一次。如有疑问，请添加链接。
• 在耦合概览表中：表头始终带有链接（请参见上方模板）。表格单元格中的强度值（Contract、Model、Functional、Intrusive）也必须带有链接。
• 在问题章节中：为每个概念的首次出现添加链接。
• 在 Markdown 中：[concept text](url)
• 在 HTML 中：<a href="url">concept text</a>

输出

将以下两个文件写入 docs/modularity-review/!date +%Y-%m-%d/：

1. docs/modularity-review/!date +%Y-%m-%d/modularity-review.md — Markdown 版本
2. docs/modularity-review/!date +%Y-%m-%d/modularity-review.html — HTML 版本

生成 HTML

生成 HTML 前，必须先读取模板文件。 模板位于 ${CLAUDE_SKILL_DIR}/assets/template.html。读取该文件，然后替换：

• 将 {{TITLE}} 替换为评审标题（例如 “Modularity Review”）
• 将 {{CONTENT}} 替换为评审正文的 HTML

不要自行生成 HTML 结构、样式或样板代码。模板已提供所有样式、主题切换（根据一天中的时间切换浅色/深色主题）和布局。请原样使用模板，只替换上述两个占位符。

HTML 必须包含与 Markdown 版本相同的 coupling.dev 链接。 将 Markdown 中的每个 [text](url) 转换为 HTML 中的 <a href="url">text</a>。转换时不要遗漏任何链接。

使用模板中的以下 CSS 类：

• .meta — 用于范围/日期元数据块
• .issue — 用 <div class="issue"> 包裹每个问题章节
• .issue-meta — 用于问题中的集成/严重程度行
• .severity + .severity-critical / .severity-significant / .severity-minor — 用于严重程度徽章
• .footer — 用于署名页脚