reverse-engineering-specs

逆向工程规格说明

概述

对于缺少文档的棕地／遗留项目，此技能会通过全面分析现有代码，生成不含实现细节的规格说明。输出内容会完整描述项目行为，为基于现有代码库的自主开发提供依据，从而实现安全重构、添加功能和现代化改造。

**核心原则：**记录实际行为，包括缺陷。在明确标记待修复之前，缺陷都是“已记录的功能”。

**这是一项严格的技能。**必须追踪每条代码路径，不得假设，不得跳过。

阶段 1：全面调查代码

**[HARD-GATE]**必须追踪每条代码路径，不得假设，不得跳过。

通过 Agent 工具并行启用子 Agent（最多 500 个，subagent_type="Explore"），分析以下内容：

分析目标	记录内容	优先级
入口点	调用系统的所有方式（HTTP、CLI、事件、cron）	P0
代码路径	每个分支、循环、条件和提前返回	P0
数据流	每条处理管道的输入 → 转换 → 输出	P0
状态变更	读取、写入或删除状态的所有位置	P0
错误处理	Try/catch 代码块、错误代码、回退行为	P0
副作用	外部调用、文件 I/O、数据库写入、事件发出	P1
配置	环境变量、配置文件、功能标志	P1
依赖项	使用的外部服务、库和 API	P1
并发	异步操作、竞态条件、锁定机制	P2
隐式行为	基于约定的路由、中间件链、装饰器	P2

调查策略决策表

代码库规模	策略	子 Agent 数量
小型（<50 个文件）	单次完整扫描	5-10
中型（50-500 个文件）	按模块扫描	50-100
大型（500+ 个文件）	先查入口点，再深入扫描	200-500

调查完成后停止——概述发现的入口点、数据流和行为。生成规格说明前，先征求确认。

阶段 2：生成行为规格说明

按照 spec-writing 技能的格式，将代码分析结果转换为不含实现细节的规格说明。

转换规则

规则	说明
删除所有实现细节	不包含函数名、变量名或技术引用
描述是什么，而不是如何实现	仅描述可观察到的行为
记录实际行为（包括缺陷）	在规格说明中将缺陷视为“当前行为”
使用 Given/When/Then 格式	用于所有验收标准
包含数据契约	输入结构、输出结构、不变量
单独列出已知问题	缺陷应放在 KNOWN_ISSUES.md 中，不要内联记录

删除实现细节

代码构件	你看到的内容	规格说明中的写法
jwt.verify(token, secret)	使用 JWT 验证令牌	“根据身份验证系统验证凭证”
redis.get(cacheKey)	查询 Redis 缓存	“从缓存中获取先前计算的结果”
if (user.role === 'admin')	角色检查	“特权操作需要管理员权限”
res.status(429).json(...)	速率限制响应	“请求过多时返回速率限制错误”
bcrypt.hash(pw, 12)	对密码进行哈希处理	“以不可逆的格式存储密码”

规格说明生成完成后停止——整理前先运行完整性检查清单。

阶段 3：整理规格说明

按照命名约定创建规格文件：

specs/
├── 01-[first-capability].md
├── 02-[second-capability].md
├── ...
├── NN-[last-capability].md
└── KNOWN_ISSUES.md

KNOWN_ISSUES.md 格式

# Known Issues

## [Issue Title]
- **Current behavior:** [What actually happens]
- **Expected behavior:** [What should happen, if known]
- **Affected specs:** [Which spec files reference this behavior]
- **Severity:** [Critical | High | Medium | Low]
- **Notes:** [Additional context]

严重性分类

严重性	标准	操作
严重	数据丢失、安全漏洞、系统崩溃	开发任何新功能之前修复
高	结果不正确、工作流中断	在下个版本中修复
中	用户体验差、性能问题	规划后续修复
低	外观问题、轻微不一致	有机会时修复

组织完成后停止——提交规范文件列表和 KNOWN_ISSUES 供审查。

阶段 4：质量验证

[硬性关卡] 本阶段完成前，必须通过所有检查。

#	检查项	问题	状态
1	入口点	是否记录了所有入口点？	[ ]
2	代码路径	是否追踪了所有分支和条件？	[ ]
3	数据流	是否描述了所有输入→输出管道？	[ ]
4	状态变更	是否记录了所有状态变更？	[ ]
5	错误处理	是否记录了所有错误路径？	[ ]
6	副作用	是否注明了所有外部交互？	[ ]
7	边缘情况	是否描述了边界条件？	[ ]
8	并发	是否记录了异步行为？	[ ]
9	配置	是否列出了所有配置选项？	[ ]
10	依赖项	是否识别了所有外部依赖项？	[ ]
11	不涉及实现细节	规范中是否完全没有代码、技术名称或架构？	[ ]
12	Given/When/Then	所有验收标准是否都采用正确格式？	[ ]

具体示例：从代码到规范的转换

代码（输入——需要分析的内容）：

function checkAuth(req, res, next) {
  const token = req.headers.authorization?.split(' ')[1];
  if (!token) return res.status(401).json({ error: 'No token' });
  try {
    const decoded = jwt.verify(token, process.env.JWT_SECRET);
    req.user = decoded;
    next();
  } catch (e) {
    return res.status(403).json({ error: 'Invalid token' });
  }
}

规范（输出——需要产出的内容）：

# Request Authentication

## Job to Be Done
When a request arrives at a protected endpoint, I want to verify the
caller's identity, so I can ensure only authorized users access the system.

## Acceptance Criteria

### Valid Credentials
- Given a request with valid credentials in the authorization header
- When the request is processed
- Then the request proceeds to the next handler
- And the authenticated user identity is available to downstream handlers

### Missing Credentials
- Given a request without credentials
- When the request is processed
- Then a 401 status is returned
- And an error message indicates missing credentials

### Invalid Credentials
- Given a request with invalid or expired credentials
- When the request is processed
- Then a 403 status is returned
- And an error message indicates invalid credentials

## Edge Cases
- Malformed authorization header (missing "Bearer" prefix): treated as missing credentials
- Expired credentials: treated as invalid credentials

## Data Contracts
- Input: Authorization header in "Bearer <credential>" format
- Output on success: User identity object attached to request context
- Output on failure: JSON error response with appropriate status code

请注意：不提及 JWT、中间件、Express、环境变量或任何实现细节。

反模式 / 常见错误

错误	错误原因	正确做法
跳过“枯燥”的代码路径	未记录的行为会在重构期间引发错误	追踪每条路径，包括错误处理程序
在规范中泄露实现细节	有违行为规范的目的	删除所有技术名称、函数名称和代码
将缺陷标记为“正确行为”	会丢失其属于缺陷这一信息	在 KNOWN_ISSUES.md 中记录并注明严重性
跳过异步/并发分析	竞态条件是最难发现的错误	记录所有异步行为
只分析正常路径	大多数错误都出现在错误路径中	记录所有错误处理路径
不追踪代码而是猜测行为	规范会沦为虚构	阅读每一行——不要做任何假设
未经用户审查就生成规范	误解会不断传播	每个阶段完成后提交审查

防止合理化的约束

• [硬性关卡] 不要跳过任何代码路径——必须追踪每个分支、条件和错误处理程序
• [硬性关卡] 规范中不得包含任何实现细节——不能有代码、技术名称或架构
• [硬性关卡] 在全部 12 项检查都通过之前，不要将完整性清单标记为已完成
• 不要跳过并发分析——即使代码“看起来是同步的”
• 不要跳过配置分析——环境变量和功能标志会改变行为
• 不要根据函数名称推断行为——要阅读实际代码
• 不要在逆向工程期间修复缺陷——将其记录在 KNOWN_ISSUES.md 中

集成点

技能	关系
spec-writing	输出遵循 spec-writing 格式；生成后使用它进行审查
autonomous-loop	规范将作为规划模式的输入，用于差距分析
acceptance-testing	从逆向工程得出的验收标准中派生测试
self-learning	将发现的项目上下文填入记忆文件
planning	规范完成后，规划改进或新功能
systematic-debugging	已知问题有助于确定调试优先级

逆向工程后的工作流

步骤	技能	目的
1	reverse-engineering-specs（本技能）	根据代码生成行为规范
2	spec-writing（审查模式）	验证质量和完整性
3	planning	找出差距并规划改进
4	autonomous-loop	以规范为指导实现功能或修复问题

验证关卡

在宣称逆向工程已完成之前：

1. 验证完整性检查清单（全部 12 项）均已通过
2. 验证所有规范文件中均不包含实现细节
3. 验证所有验收标准均采用 Given/When/Then 格式
4. 验证 KNOWN_ISSUES.md 存在，且已对发现的所有缺陷进行分类
5. 验证用户已审阅规范集和 KNOWN_ISSUES

技能类型

灵活 — 根据代码库规模调整调查深度和子 Agent 数量，同时遵循彻底调查和不包含实现内容的输出规则。不得跳过任何代码路径。