源代码解构（需求）

本文件中的 templates/... 均指本技能目录下的 templates/ 子目录。

1. 所有源代码包/模块必须逐一分析，不得跳过任何模块
2. 每个模块的需求文档必须完整包含所有章节
3. 业务规则必须从代码中深度挖掘，不得遗漏
4. 执行进度必须记录，确保可追溯：优先使用 todowrite；宿主未提供时写入 docs/todo/ 下的 TODO 文件
5. 需求必须提炼技术实现背后的根本原因，不得把技术实现形态当成需求
6. 最终输出必须通过完整性检查清单验证

违反以上约束视为执行失败，必须重新执行。 </HARD-GATE>

核心原则

从代码逆向提炼需求，完整收集业务意图。解答为什么建立项目的问题。

根本需求优先（强制）

代码里的类、方法、消息、缓存、表结构、锁、批处理，都是技术实现形态，不是需求本身。需求文档必须回答「为什么必须这样实现」，再说明「当前如何实现」。

写作要求：

1. 每条需求/规则先写「根本需求」，再写「参考技术实现」，最后写「代码证据」。
2. 根本需求必须落在业务价值/风险/合规层面（如数据安全、强一致、零差错、实时性、可用性、可审计、防舞弊、合规），而不是「调用某方法」「写某表」「发某消息」。
3. 禁止用「系统做了 X」代替「系统必须保证 Y」。若无法判断根本原因，标注「待业务确认」，不得臆造。
4. 跨模块重复的技术手段（锁、广播、缓存、分表）应归纳为同一条根本需求，避免把实现细节误当业务规则。
5. 代码中的技术实现是「参考实现」，不是唯一实现，也不是需求本身。同一根本需求可以有多种满足方式（换一种锁、换一种消息、换一种存储同样成立）；文档只把当前代码作为证据/参考，不得据此推断「需求就是这样做」，也不得把实现细节写成排他性约束。

执行步骤

1. 扫描项目结构：列出所有包/模块，形成完整模块清单
2. 逐一分析模块：按模块清单顺序，逐个深入分析
3. 挖掘业务规则：从每个模块代码中深度挖掘业务规则
4. 编写需求文档：为每个模块生成完整需求文档
5. 汇总全局需求：整合所有模块需求，生成全局需求文档

进度记录

使用 todowrite 记录执行进度；宿主未提供该工具时，按 rules/interaction.rules.md 写入 docs/todo/ 下的 TODO 文件：

- [ ] 扫描项目结构，列出模块清单
- [ ] 分析模块: {module1}
- [ ] 分析模块: {module2}
- [ ] ...
- [ ] 汇总全局需求文档
- [ ] 完整性检查

模块梳理要求

模块清单

生成 docs/requirements/module_inventory.md，模板见 templates/module_inventory.md

分析顺序

1. 核心业务模块优先
2. 辅助功能模块次之
3. 工具/配置模块最后

模块分析完整性

业务规则挖掘

挖掘方法

AST 辅助挖掘（ast-grep-mcp 联动）

当 ast-grep-mcp 可用时，使用 find_code_by_rule 自动扫描业务规则候选点。

条件判断挖掘：

find_code_by_rule(
  project_folder: "<project_root>",
  yaml: '''
    id: business-condition
    language: java
    rule:
      pattern: 'if ($VAR.equals("$VAL"))'
    constraints:
      VAL:
        regex: '(?i)(ACTIVE|PENDING|APPROVED|REJECTED|ENABLED|DISABLED|SUCCESS|FAILED|PAID|SHIPPED|CANCELLED)'
  '''
)

状态赋值挖掘：

find_code_by_rule(
  project_folder: "<project_root>",
  yaml: '''
    id: state-assignment
    language: java
    rule:
      pattern: '$OBJ.setStatus("$VAL")'
    constraints:
      VAL:
        regex: '(?i)(ACTIVE|INACTIVE|PENDING|APPROVED|REJECTED|ENABLED|DISABLED|SUCCESS|FAILED|PAID|SHIPPED|CANCELLED)'
  '''
)

异常类挖掘：

find_code(pattern: 'throw new $EXCEPTION($$$ARGS)', language: java, project_folder: "<dir>")

SQL 来源提取：复用 sql-extract 技能的 rule，参见 sql-extract/SKILL.md。

注意：AST 命中结果为候选点，需人工确认业务语义后写入规则文档。

规则输出格式

每条规则需记录：规则ID、规则名称、根本需求、参考技术实现（当前代码中的一种实现，非唯一、仅供参考）、触发条件/适用场景、代码位置、异常处理

• 「根本需求」列写该规则要保障的业务价值/风险/合规目标，禁止复述技术手段。
• 「参考技术实现」列记录代码中的当前做法，仅作参考与证据；它不是唯一实现，不得据此推断需求，也不得排除其他合理实现方式。

模板见 templates/business_rules.md

需求分析维度

需求识别技巧

源代码类型

直接源码

Java(*.java)、Python(*.py)、C++(*.cpp/*.hpp)、ANSI C(*.c/*.h)、 JavaScript(*.js/*.mjs)、TypeScript(*.ts/*.tsx)、Rust(*.rs)、 Go(*.go)、Kotlin(*.kt)、Scala(*.scala)、Shell(*.sh)、Batch(*.bat/*.ps1)

SQL 来源

SQL 提取正则

(?i)(SELECT|INSERT|UPDATE|DELETE|CREATE|ALTER|DROP|TRUNCATE)\s+
(?i)(SELECT|INSERT|UPDATE|DELETE|CREATE|ALTER|DROP)\s+[\w\s\*,\.\(\)]+(FROM|INTO|TABLE|SET|VALUES|WHERE|JOIN|ORDER|GROUP|HAVING)

输出目录结构

docs/requirements/
├── module_inventory.md           # 模块清单（必须）
├── global_requirements.md        # 全局需求文档
├── {package}/                    # 分模块需求文档
│   └── requirements.md

输出模板

完整性检查清单

模块覆盖

• 所有模块已列入 module_inventory.md
• 所有模块均有对应的需求文档
• 需求文档数量与模块数量一致

文档完整性

• 模块概述章节
• 根本需求章节（含价值目标+技术实现→根本原因映射）
• 业务场景章节（含场景列表+场景详情）
• 功能需求章节（含核心功能+辅助功能）
• 业务规则章节（独立章节，含规则分类+规则详情）
• 数据需求章节（含数据实体+数据流转）
• 非功能需求章节
• 约束条件章节

业务规则检查

• 业务规则已从代码中深度挖掘
• 业务规则已分类整理
• 每条规则有代码位置引用
• 规则详情包含触发条件、适用场景
• 每条规则已提炼根本需求，未把技术实现形态当成需求
• 根本需求落在业务价值/风险/合规层面，而非类/方法/表/消息

全局文档检查

• 模块清单已生成
• 全局需求文档已生成
• 全局文档包含「根本需求」汇总，能回答系统为什么这样设计
• 业务规则汇总章节存在
• 功能全景章节存在
• 数据全景章节存在

关联技能

设计解构请使用技能：code-deconstruct

SQL 提取请使用技能：sql-extract（ast-grep-mcp 联动，精准提取内嵌 SQL）