design

高层设计

根据功能需求设计模块化高层架构，并编写全面的设计文档。所有架构决策都应用平衡耦合模型（从 balanced-coupling 技能预加载）。

输入

如果 $ARGUMENTS 包含文件路径，请读取该文件作为功能需求输入。 如果 $ARGUMENTS 为空或不是有效的文件路径，请使用 AskUserQuestion 请求路径。标题：“需求”。问题：“请提供功能需求文件的路径。” 在获得有效文件路径并成功读取文件之前，不得继续。

使用 TaskCreate 跟踪以下 6 个步骤：理解需求、设计模块化架构、编写模块设计文档、编写模块测试规范、编写架构文档、模块化审查。

交互规则

始终使用 AskUserQuestion 获取用户输入。遵循以下原则：

• 一次只问一个问题。 切勿在一条消息中批量提出多个问题。
• 优先使用多项选择。 提供 2-4 个具体选项并附上说明。这样比开放式问题更容易回答。
• “其他”选项会自动提供。 该工具始终提供可自由填写文本的“其他”选项，因此无需自行添加。
• 使用标题。 使用简短标签（最多 12 个字符），例如“批准”“子域”“耦合”。

流程

严格遵循以下步骤。每个步骤在进入下一步之前都需要获得用户明确批准。如果遇到任何歧义，请暂停并使用 AskUserQuestion 向用户澄清。切勿自行假设。

步骤 1：了解需求

阅读功能需求文件。然后：

1. 用自己的话重述功能需求。将其整理为相互关联的功能领域。

2. 找出耦合感知设计所缺少的信息。 思考做出良好平衡耦合决策所需的信息——领域分类（决定易变性）、组织结构（决定距离）和集成模式（决定强度）。找出需求中的缺口，尤其是：

   • 核心、支撑和通用分类存在歧义的业务领域——提出你的理解，并请用户确认或纠正
   • 会影响模块边界的组织约束（团队所有权、部署单元、共享基础设施）
   • 会影响易变性最高领域以及设计投入方向的战略方向
   • 适当耦合强度不明确的集成需求

   使用 AskUserQuestion 逐项询问用户各个缺口。对于需求中明确的内容，跳过不问。不要询问答案不会改变设计的问题——每个问题都必须解决会影响耦合决策的歧义。你不局限于这些类别——如果需求中存在其他会影响架构决策的歧义，也要询问。问题应基于你读到的具体需求。

3. 使用 DDD 子域（核心／支撑／通用）对领域进行分类。这决定了易变性以及设计投入方向。分析需求并自行提出分类。以表格形式展示：

子域	分类	理由
{area 1}	核心	{why}
{area 2}	支撑	{why}
{area 3}	通用	{why}

然后使用 AskUserQuestion 请用户确认：

标题	问题	选项
子域	这些子域分类是否正确？	1. 已批准 - 全部正确 2. 部分有误 - 我会告诉你需要更改哪些分类 3. 缺少子域 - 还有未列出的领域

如果用户表示部分分类有误，请询问哪些分类有误，以及正确的分类应该是什么。

使用 AskUserQuestion 向用户展示你的完整理解，以供确认：

标题	问题	选项
确认	对需求的理解是否正确？	1. 已批准 - 继续进行架构设计 2. 需要修改 - 我会说明哪里有误 3. 缺少背景信息 - 我还有更多信息要告诉你

获得批准前，不要继续。

第 2 步：设计模块化架构

使用平衡耦合模型：

1. 确定高层模块、各自的职责以及它们之间的集成关系。
2. 使用 DDD 子域对易变性分类（核心 = 高易变性，支撑型／通用型 = 低易变性）。这决定了设计投入应集中在哪些方面。
3. 评估耦合程度：针对每项集成，从三个维度（集成强度、距离、易变性）进行评估。
4. 应用平衡规则：BALANCE = (STRENGTH XOR DISTANCE) OR NOT VOLATILITY
   • 对于高易变性组件，应设计集成方式，使强度和距离保持平衡：
     • 必须共享大量知识（功能／模型耦合）的组件应放在一起（低距离） -> 高内聚。
     • 距离较远的组件（独立服务、独立团队）应通过契约集成（低强度） -> 松耦合。
   • 对于低易变性组件，应承认务实的捷径是可以接受的。
5. 标记不平衡的耦合：高强度 + 高距离（存在分布式单体风险），或低强度 + 低距离（存在低内聚／大泥球风险）。
6. 提出建议，说明如何通过具体措施重新平衡存在问题的集成。

向用户展示耦合评估表：

集成	强度	距离	易变性	是否平衡？	操作
A -> B	模型	高（独立服务）	高（核心）	否 — 紧耦合	降低强度：通过 API 引入契约

使用 AskUserQuestion 与用户逐步推进。每一步都需要用户批准。在用户完全确认模块化架构之前，不要开始编写设计文档。

标题	问题	选项
批准	这个模块化架构看起来正确吗？	1. 已批准 - 继续编写设计文档 2. 需要修改 - 我会说明需要调整的内容 3. 重新考虑 - 让我们重新审视模块边界

第 3 步：编写模块设计文档

使用第 2 步中已确认的架构，为每个模块创建 docs/design/!date +%Y-%m-%d/{module-name}/design.md，内容如下：

# {Module Name}

## Functional Responsibilities

What this module does — the functionality it implements and the business capabilities it provides.

## Encapsulated Knowledge

What this module knows that no other module should — the domain concepts, business rules, and implementation details it owns.

## Subdomain Classification

Core / Supporting / Generic — and the rationale for the classification.

## Integration Contracts

For each module this one integrates with:

- **Direction**: Which module depends on which
- **Contract type**: The integration strength level (contract / model / functional)
- **What is shared**: The specific knowledge exchanged
- **Contract definition**: The interface, API, events, or data structures that define the boundary

## Change Vectors

Reasonable future changes that would require ONLY this module to change — the axes of evolution this module's boundary is designed to support.

无需逐份征求批准，直接编写所有模块设计文档。模块化架构已在第 2 步获得批准，这些文档是对该已批准设计的直接转化。

编写完所有模块文档后，使用 AskUserQuestion 向用户展示完整文档集以供审阅：

标题	问题	选项
模块	所有模块设计文档均已编写完成。你觉得怎么样？	1. 已批准 - 继续编写测试规范 2. 需要修改 - 我会说明哪些模块需要调整 3. 重新审视架构 - 文档暴露出边界问题

反复迭代，直到获得批准。

第 4 步：编写模块测试规范

对于每个模块，创建 docs/design/!date +%Y-%m-%d/{module-name}/tests.md，其中包含：

# {Module Name} — Test Specification

## Unit Tests

Tests for the module's internal logic in isolation. Covers business rules, calculations, state transitions, and edge cases.

## Integration Contract Tests

Tests that verify the module honors its integration contracts — that it produces the correct outputs given valid inputs according to its contract definitions.

## Boundary Tests

Tests that verify the module correctly rejects invalid inputs, handles edge cases at its boundaries, and maintains its encapsulation (nothing leaks).

## Behavior Tests

Tests that verify the module's functional responsibilities from an outside-in perspective — given a business scenario, the module behaves as expected.

每个测试部分都应包含具体且命名明确的测试用例，其中包括：

• 测试名称：描述性名称
• 场景：要测试的内容
• 预期行为：正确的结果

无需征求批准，直接编写所有测试规范。模块设计已获批准，测试规范直接基于这些设计编写。

第 5 步：编写架构文档

创建 docs/design/!date +%Y-%m-%d/architecture.md，其中包含：

# Architecture Overview

## Functional Requirements Summary

Brief summary of the requirements this architecture addresses.

## Module Map

List of all modules with one-line descriptions.

## How the Modules Work Together

For each key functional flow / use case:

- Which modules participate
- How data/control flows between them
- What contracts govern the interactions

## Coupling Assessment

The coupling assessment table from the modular architecture analysis, with commentary on the key design decisions and their rationale grounded in the Balanced Coupling model.

## Design Decisions and Trade-offs

Key architectural decisions, what was considered, what was chosen, and why — grounded in the coupling dimensions and balance rule.

## Unresolved Risks

Anything the design intentionally leaves open, along with the conditions under which it should be revisited.

无需征求批准，直接编写架构文档。该文档综合了已获批准的模块设计。

第 6 步：模块化审查

编写完所有文档后，审查自己的设计，检查模块化是否存在失衡。对于每个模块间集成：

1. 梳理集成关系：共享了哪些知识？这些知识是隐式共享还是显式共享？集成强度处于什么级别？
2. 评估全部三个维度：强度、距离和波动性。
3. 应用平衡规则：BALANCE = (STRENGTH XOR DISTANCE) OR NOT VOLATILITY
4. 标记失衡：重点关注既失衡又具有波动性的集成关系。

对于发现的每个问题，都要对其严重程度进行分类：

• 严重：强度高 + 距离远 + 波动性高。
• 显著：中等波动区域中的耦合失衡，或隐藏集成点的隐式耦合。
• 轻微：低波动区域中的耦合失衡，或增加认知负担但不会导致连锁变更的低内聚性。

如果存在严重或显著问题：

1. 使用第 2 步耦合评估表的相同结构向用户呈现问题，并说明每个问题中的知识泄漏及建议的改进方案。
2. 提出具体的设计变更，以重新平衡耦合。
3. 用户批准变更后，更新受影响的设计文档（模块设计、测试规范和架构文档）。
4. 重复此步骤——再次审查更新后的设计。持续进行，直至不再存在严重或显著问题。

应在架构文档的“未解决风险”部分记录轻微问题，但这些问题不会阻碍完成。

重要约束

• 绝不臆测。 如果有任何不清楚的地方，先询问用户。
• 编写可执行的文档。 每份设计文档都应提供足够的上下文，让开发者能够开始实现。每份测试规范都应提供足够的上下文，让开发者能够开始编写测试。
• 绝不建议“直接把所有东西都解耦”。 这忽略了强度与距离之间的平衡。
• 绝不要只用一个维度评估耦合。 始终考虑强度、距离和波动性这三个维度。
• 区分本质波动与偶然波动。 提交频率高可能表明设计不佳（偶然波动），而不是领域本身具有波动性。
• 考虑距离的组织层面因素。 相同的代码结构 + 不同的团队 = 更高的实际距离。
• 让每项建议都以模型为依据。 指出支撑每项设计决策的具体维度和原则。