从现有代码库逆向生成项目 SPEC 时，系统扫描代码、配置…

当你需要理解、归档、审计或准备重写一个没有规格文档的现有项目时，逆向生成结构化 SPEC。

适用场景

解决思路

1. 在扫描前询问用户要分析的范围：A 整个仓库（中小项目推荐）、B 特定目录或模块 [path]、C 仅特定方面（如 API surface、data model、auth flow）。
2. 询问深度级别：1 Overview（高层架构+技术栈+关键功能，快约 5 分钟）、2 Standard（包含 API contracts、data models、config、dependencies，默认）、3 Deep（增加内部模块交互、error handling patterns、test coverage analysis）。
3. 如果项目大于 500 个文件，建议从 Overview 或特定模块开始。
4. 系统分析项目身份：读取 package.json、go.mod、Cargo.toml、pyproject.toml、pom.xml 等；读取 README、LICENSE；查看 Git history（first commit date、recent activity、contributor count）。
5. 分析架构：识别目录结构和组织模式（monorepo、layered、hexagonal 等）；识别入口点（main files、CLI commands、server bootstrap）；梳理模块边界和内部依赖图。
6. 分析技术栈：识别语言和版本约束；框架和主要库；构建工具和 bundler；运行时要求（Node version、Docker 等）。
7. 分析功能与行为：识别路由定义、CLI commands、导出函数；业务逻辑模块及其职责；后台任务、cron tasks、event handlers。
8. 分析数据模型：读取数据库 schemas、migrations、ORMs；识别关键数据结构及其关系；识别状态管理方式。
9. 分析 API surface：识别 HTTP endpoints（method、path、request/response shapes）；GraphQL schema、gRPC protos、WebSocket events；CLI interface（commands、flags、arguments）；exported library API（public functions、classes、types）。
10. 分析配置与环境：识别环境变量及其用途；配置文件及其 schema；feature flags、toggles。
11. 分析外部依赖：识别第三方服务（databases、queues、APIs）；基础设施要求（cloud services、storage）；认证/授权 providers。
12. 分析测试与质量：识别测试框架和方法（unit、integration、e2e）；覆盖模式（哪些测了、哪些没测）；linting、formatting、type checking 配置。
13. 分析部署与运维：读取 CI/CD 配置；识别部署目标和策略；识别 monitoring、logging、health checks。
14. 按 SPEC 模板生成文档，并省略不适用的章节；模板以 # SPEC: [Project Name] 开头，并标注 Reverse-engineered specification — generated [date] from commit [short-hash]。
15. 写入第 1 节 Overview：1.1 Purpose 用一段话说明项目解决什么问题、为谁解决；1.2 Key Capabilities 从用户视角列出系统能做什么；1.3 Architecture Style 说明架构风格。
16. 写入第 2 节 Tech Stack：用表格列出 Layer、Technology、Version，覆盖 Language、Framework、Database、Build、Test、Deploy。
17. 写入第 3 节 Project Structure：给出目录树，并注释每个顶层目录的用途。
18. 写入第 4 节 Data Model：4.1 Core Entities 对每个实体列出 name、fields、relationships、constraints；4.2 State Transitions 如适用，列出生命周期状态和有效转换。
19. 写入第 5 节 API Surface：5.1 按接口类型（REST / CLI / Library 等）用表格列出 Method、Path/Command、Description、Auth；5.2 Request/Response Schemas 列出关键请求/响应形状和字段类型。
20. 写入第 6 节 Configuration：用表格列出 Variable / Key、Required、Default、Description。
21. 写入第 7 节 External Dependencies：用表格列出 Service、Purpose、Failure Impact。
22. 写入第 8 节 Business Rules & Constraints：用编号列表记录从代码中发现的 invariants、validation rules 和业务逻辑约束。
23. 写入第 9 节 Non-Functional Characteristics：9.1 Performance 观察 caching、pagination、batch processing 等模式；9.2 Security 记录 auth mechanism、input validation patterns、secrets management；9.3 Error Handling 记录 custom error types、error codes、retry policies。
24. 写入第 10 节 Testing Strategy：用表格列出 Type、Framework、Coverage Pattern，覆盖 Unit、Integration、E2E。
25. 写入第 11 节 Known Gaps & Assumptions：列出仅凭代码不清楚的地方、分析中做的假设、没有测试或文档的区域。
26. 写入第 12 节 Appendix：A. Dependency Graph 列出关键模块依赖和 import relationships；B. Environment Setup 根据配置和脚本推导本地运行步骤。
27. 生成 SPEC 后展示给用户，并询问：哪些章节需要更多细节、有哪些不准确需要更正、是否增删章节、深度级别是否合适；让用户回复 OK 保存或提供反馈迭代。
28. 应用反馈并重新展示，直到用户确认。
29. 询问保存位置：A docs/SPEC.md（推荐）、B SPEC.md（项目根目录）、C 自定义路径 [specify]；将最终 SPEC 写入约定位置。
30. 识别项目目的时：先看 README 第一行、package description 字段、CLI help text；检查主入口点 bootstrap 了什么；查看测试描述，它们常用自然语言描述预期行为。
31. 发现架构时：映射 import/require 语句构建依赖图；按目录命名识别层，如 controllers、services、models、routes、handlers、domain、infra；检查 dependency injection patterns、middleware chains、plugin registrations。
32. 提取业务规则时：查找 validation functions、guard clauses、assertion statements；检查 error messages，它们常用业务术语描述哪里出错；检查 test assertions，它们编码了预期行为。
33. 查找 API contracts 时：查找 route registrations（Express: app.get()、FastAPI: @app.get()、Go: mux.HandleFunc()）；查找 OpenAPI/Swagger files；查找 request validation schemas（Joi、Zod、Pydantic、struct tags）；查找 CLI flag/argument definitions（cobra、argparse、yargs）。
34. 检测数据模型时：查找 ORM model definitions（Prisma、SQLAlchemy、GORM、TypeORM）；按时间顺序查看 migration files；查看核心领域对象的 type/interface definitions；查看 database seed files。
35. 项目没有 README 或文档时：在 Known Gaps 中注明，并从代码推断目的。
36. monorepo 有多个服务时：询问用户分析哪个/哪些服务；为每个服务生成一份 SPEC，或生成一份带清晰边界的统一 SPEC。
37. 项目使用代码生成时：记录生成代码的用途，但聚焦 source of truth（schemas、proto files、templates）。
38. 遗留项目混用模式时：记录所有观察到的模式，并在 Known Gaps 中注明不一致。
39. 项目是 library 无运行时：聚焦 exported API surface、type contracts，以及从 tests 中提取的 usage patterns。
40. 代码不完整或损坏时：记录已存在内容，并明确标记 broken/incomplete 区域。
41. 项目大于 1000 个文件时：从入口点开始并追踪关键流程，不要穷尽读取每个文件。
42. 一个仓库有多种语言时：记录每种语言的角色以及它们如何交互。
43. 最终前做质量检查：不熟悉项目的开发者能在 60 秒内理解目的；tech stack 足以搭建开发环境；API contracts 足以编写客户端；data models 足以重建 schema；business rules 显式列出而非埋在 see code；known gaps 诚实列出，不虚构无法确定的内容；SPEC 与实际代码一致，不是理想化文档。
44. 避免编造意图：如果无法确定某事物存在的原因，就说明无法确定，不要捏造理由。
45. 避免把代码复制进 SPEC：描述行为和契约，不要粘贴实现。
46. 避免包含瞬态状态：SPEC 描述系统设计，而不是当前运行时状态。
47. 避免过度指定内部实现：聚焦边界、契约和行为；内部实现细节属于代码注释，不属于 SPEC。
48. 避免假设 README 准确：README 常落后于代码，要用实际实现验证其声明。

适用边界 · 注意事项

• 不要用于需要分析实时运行时状态或动态行为，而代码与配置中无法体现的情况；SPEC 只描述设计而非当前运行时状态。
• 不要用于必须确定作者意图或历史决策原因、但仓库无文档/提交信息的情况；不能编造理由。
• 不要用于要求对大于 1000 个文件的项目逐文件穷尽读取的场景；应改为从入口点追踪关键流程。