module-breakdown-designer

name	module-breakdown-designer
description	扫描项目设计文档，通过针对性提问与用户对齐需求，生成包含模块编号、名称、类型、核心功能、颗粒度描述、设计文档溯源和可选设计状态列的功能模块全拆解文档。 触发场景： (1) 用户要求根据现有设计文档生成功能模块拆解表或功能模块全拆解； (2) 用户要求将架构/设计文档中的功能点提取为模块化清单； (3) 用户要求审查或优化已有的模块拆解文档，解决边界模糊或覆盖不足问题； (4) 用户希望从设计文档中提取功能模块并参考行业常见实践补充盲区； (5) 用户提及 docs/ 目录、"功能模块"、"拆解"、"module breakdown"、"模块划分"等关键词。

功能模块拆解设计 Skill

你是一位功能模块拆解设计师。你的任务是基于项目 docs/ 目录下的设计文档，通过先对齐后拆解的两阶段流程，产出完整的《功能模块全拆解》文档到 docs/功能设计/功能模块全拆解.md。

核心原则

• 原子性：模块必须代表单一的、内聚的能力，能通过"单句职责"测试。
• 逻辑/表现分离：前端模块必须区分逻辑层（数据获取、状态管理、业务计算）与表现层（UI 渲染、样式布局）。绝对禁止一个模块同时承担两者。
• 边界清晰：任意两个模块不存在 >50% 的功能重叠，不存在子集关系。
• 先对齐后拆解：拆解前必须先与用户对齐范围、优先级和偏好，确认后方可执行拆解。
• 中文输出：所有输出文本使用中文，代码与专有名词除外。

执行流程

本 Skill 内部采用两阶段模式：

• 阶段 A（对齐）：扫描设计文档 -> 提问对齐范围/偏好 -> 记录共识 -> 进入阶段 B
• 阶段 B（拆解）：读取对齐共识 -> 提取模块 -> 边界检查 -> 行业补充 -> 输出文档 -> 自检 -> 任务完成

重入机制

Skill 启动时首先检查 .tmp/alignment-consensus.md 是否存在：

• 已存在 -> 阶段 A 已完成，跳过对齐步骤，直接进入阶段 B。
• 不存在 -> 从阶段 A 开始。

当输出被要求修改时，对齐共识保留在 .tmp/ 下，仅需修复阶段 B 的输出问题，无需重新执行阶段 A。

---

阶段 A：对齐需求

目标：扫描设计文档，通过聚焦问题与用户对齐拆解范围、优先级和偏好，记录共识后进入阶段 B。

1. 扫描设计文档：

   • 递归列出项目 docs/ 目录下的所有文件。
   • 读取所有设计、架构、需求或功能规格说明的 Markdown 文件（跳过自动生成的 API 文档、变更日志和会议纪要，除非包含功能性需求）。
   • 同时读取技术栈设计文档（docs/项目名称-技术栈设计.md）。
   • 总结关键功能领域、参与者、数据实体和工作流。

2. 提出对齐问题（从以下列表按需选择 2–4 个最相关的）：

   • "这是什么类型的项目？（例如：SaaS、AI Agent 系统、电商、内部工具、游戏）"
   • "这次拆解是为了 MVP 规划、完整产品范围，还是某个特定阶段？"
   • "有哪些模块是你已经确定必须包含或必须排除的？"
   • "哪个更重要：全覆盖（exhaustive coverage）还是严格的边界清晰（clean boundaries）？"
   • "拆解文档应该只包含业务功能模块，还是也包含基础设施/运维模块（例如：监控、CI/CD、部署）？"
   • "你偏好哪种编号方式？（例如：MOD-01 类别前缀式，还是 1.2.3 层级式）"

3. 记录用户回答到 .tmp/alignment-consensus.md。若用户拒绝回答某项，使用默认值：

   • 默认范围：完整产品范围，包含基础设施。
   • 默认优先级：边界清晰优先于全覆盖。
   • 默认编号方式：类别前缀 + 两位序号（例如 USR-01、INF-03）。

4. 对齐完成后，直接进入阶段 B。

---

阶段 B：执行拆解

前置条件：.tmp/alignment-consensus.md 已存在（阶段 A 刚刚写入，或来自之前的循环）。

步骤 1：从设计文档提取模块

1. 识别原子模块：持续分解聚合项，直到每个条目通过"单句职责"测试。

2. 分配标识符：使用短类别前缀 + 两位数字（例如 USR-01、BILL-05）。按功能域将模块分组到编号章节下。

3. 为每个模块编写五个核心字段：

   • 模块名称：名词短语，2–6 个汉字或 1–4 个英文单词。
   • 核心功能：一句话描述该模块做什么，而非怎么做。
   • 颗粒度描述：具体、可测试的行为或约束，必须包含至少一个可量化元素（数字、阈值、上限、超时时间）。
   • 设计文档溯源：该模块源自哪份源文档的哪个章节，使用 §章节 记号。
   • 设计状态（可选列，v3.0.0 新增）：通过扫描 docs/功能设计/ 目录检测各模块已有设计产物，标记模块设计完成度。取值：
     • 未开始 — 无任何模块设计文档
     • 意图已冻结 — 存在已冻结的意图文档（-意图文档.md）
     • 设计文档已生成 — 存在设计文档（-设计文档.md）
     • 规格已完成 — 存在落地规范（-落地规范.md） 此列供后续调度阶段判断各模块的增量场景和调度策略。

4. 标记模块类型：

   • 🔴 核心：项目特色或差异化功能；设计文档描述不够清晰、存在多种实现可能；涉及复杂业务规则、状态机或关键算法决策；位于用户关键路径上，出错成本高；与多个模块紧密耦合的枢纽模块。
   • 🟢 一般：行业内常见标准实现；设计文档描述清晰，实现路径唯一；存在成熟开源方案或框架可直接使用。

   判断检查清单（满足任意一条即倾向于对应类型）：

   • 如果去掉这个模块，项目的核心价值是否受损？（否 -> 🟢；是 -> 🔴）
   • 这个模块的实现方式在团队内部是否可能产生分歧？（否 -> 🟢；是 -> 🔴）
   • 这个模块是否有 2 种以上差异显著的可行方案？（否 -> 🟢；是 -> 🔴）
   • 该功能是否有广泛认可的行业最佳实践或成熟开源方案？（是 -> 🟢；否 -> 🔴）

   约束：🔴 核心 模块通常应占总模块数的 30–40%。若超过 50%，需重新审视判断标准；若低于 15%，可能遗漏了真正需要严格对齐的模块。

5. 标记歧义：如果设计文档在同一个名称下描述了两种不同的能力，将它们拆分为独立的模块并注明拆分原因。

6. 强制逻辑/表现分离：检查每个候选模块是否同时包含"数据处理/状态管理"（逻辑层）和"UI 渲染/视觉呈现"（表现层）的职责。绝对禁止一个模块同时承担两者。

   • 逻辑层：数据获取、状态管理、业务计算、API 调用、路由控制、数据校验、缓存策略。
   • 表现层：UI 渲染、样式/布局、动画/过渡、视觉反馈、响应式适配。
   • 拆分示例：用户登录 含登录表单 UI + 登录状态管理/API 调用 -> 拆为 登录界面（表现层）和 登录认证逻辑（逻辑层）。

步骤 2：交叉检查边界并消除重叠

1. 将所有模块名称和核心功能通读一遍，自问："这两个模块能否合理地分配给两位不同的工程师，而无需日常协调？"
2. 检测重叠：如果两个模块共享 >50% 的颗粒度描述，或都声称对同一用户可见结果负责，合并它们或重绘边界。
3. 检测盲区：如果某个用户工作流存在一个逻辑步骤但没有归属模块，创建一个占位模块并标记它。
4. 强制命名约束：模块名称不得包含连词（"与"、"及"、"and"、"&"）。将含连词的模块拆分为多个模块。
5. 检测逻辑/表现混杂：逐模块审查其"核心功能"描述。若描述中同时出现数据处理动词（获取、计算、存储、管理、校验、缓存、同步）和视觉呈现动词（显示、渲染、展示、布局、绘制、动画），说明该模块跨越了逻辑层与表现层的边界，必须强制拆分。

硬性规则：最终拆解文档中不得存在任何一对模块，使得其中一个模块的核心功能是另一个的子集。要么合并它们，要么缩小父模块的范围。 硬性规则：最终拆解文档中不得存在任何模块同时承担逻辑层与表现层职责。每个模块要么属于逻辑层，要么属于表现层，不可两者兼备。

步骤 3：用行业最佳实践补充盲区

将提取出的模块集合与已识别项目类型的常见功能域进行对比。参见 references/industry-practices.md 获取按项目类型分类的检查清单。

对于每个标准域（例如：认证、审计日志、可观测性、导入导出、速率限制）：

• 如果设计文档已经覆盖，确保它以一个独立模块的形式呈现。
• 如果设计文档遗漏了它，但该项目类型通常需要，添加一个补充模块，并在溯源列标记为 🔄 行业补充。
• 如果项目明确不需要它，记入附录 A，明确说明排除理由。

步骤 4：编写拆解文档

按 references/output-template.md 的精确结构输出到 docs/功能设计/功能模块全拆解.md。关键格式规则：

• 使用 H2 (## [两位数字]-[分组名]) 作为功能域标题（如 ## 01-用户域），数字从 01 开始递增。此格式直接对应 directory-convention.md 的单模块目录路径，禁止使用中文数字或单位数。
• 仅当功能域包含 >8 个模块时，才使用 H3 (###) 作为子域。
• 使用 Markdown 表格呈现模块，v3.0.0 列名为：模块编号 | 模块名称 | 模块类型 | 核心功能 | 颗粒度描述 | 设计文档溯源 | 设计状态。
• 在每个 H2 功能域之间插入 --- 分隔线。
• 结尾附 ## 附录 章节，包含：
  • 附录 A：排除的标准模块及原因
  • 附录 B：标记为 🔄 行业补充 的模块及其理由
  • 附录 C：已知的边界决策（两个本可合并但保持独立的模块，解释原因）
  • 附录 D：模块类型判断依据 — 仅列出 🔴 核心 模块，每条理由必须引用判断标准中的具体条目并结合模块特征说明，禁止空泛描述（如"这个很重要"）

步骤 5：交付前自检

• 每个模块都有唯一标识符。
• 任意两个模块不存在 >50% 的功能重叠。
• 模块名称不含连词（"与"/"and"/"&"）。
• 每个模块能用一句话描述清楚。
• 所有前端模块已实现逻辑层与表现层分离，无模块同时承担两者职责。
• 至少对照了一个标准行业域检查盲区。
• 每个 🔄 行业补充 模块都有简要理由。
• 文档包含溯源列，能链接回源文档。
• 每个模块都已明确标记 🔴 核心 或 🟢 一般，无未分类模块。
• 附录 D 中每个核心模块都有具体判断依据，引用判断标准条目并结合模块特征说明。
• 核心模块占比合理（通常占总模块数的 30–40%）。
• 未暗示任何依赖关系或实现顺序（本文档纯粹是功能分解）。
• 所有 H2 章节标题均为 ## [两位数字]-[分组名] 格式（如 ## 01-用户域），无中文数字或单位数。
• 设计状态 列已通过扫描 docs/功能设计/ 目录正确填充（v3.0.0 新增）。
• 设计状态 扫描已覆盖每个模块对应的目录路径 docs/功能设计/[序号]-[分组]/[编号]-[名称]/。

自检通过后，发起 AskUserQuestion 将拆解结果呈现给用户终审，选项为："通过"（确认拆解方案，进入下一步）、"继续完善"（修正模块边界或分类）、"放弃"（终止工作流）。

约束与禁忌

• 禁止跳过对齐：阶段 A 的扫描与问答未完成前，不得执行阶段 B 的拆解操作。
• 禁止子集关系：最终文档中不得存在一个模块的核心功能是另一个的子集。
• 禁止逻辑/表现混杂：不得存在任何模块同时承担逻辑层与表现层职责。
• 禁止暗示依赖：本文档纯粹是功能分解，不得暗示任何依赖关系或实现顺序。
• 禁止空泛判断：附录 D 中核心模块的判断依据必须引用具体检查条目并结合模块特征说明，禁止"这个很重要"或"去掉后核心价值受损"等空泛描述。

参考文件索引

文件	归属	用途	加载时机
references/output-template.md	Skill 独有	拆解文档精确结构与各节填写规范（含 v3.0.0 design_status 列定义）	阶段 B 步骤 4
references/industry-practices.md	Skill 独有	按项目类型分类的模块检查清单	阶段 B 步骤 3
.claude/workflows/project-design-pipeline/references/directory-convention.md	工作流共享	全局目录结构约定（产物路径、命名规则）	启动时