code-to-spec

to-spec — 逆向工程项目规范

分析现有代码库，并生成一份结构化的 SPEC 文档，记录项目的功能、构建方式以及对外提供的契约。这份动态规范可用于从头重建项目，或帮助新贡献者快速上手。

---

适用场景

• 想全面了解现有项目
• 帮助需要了解项目概况的新团队成员上手
• 为没有规范文档的项目编写文档
• 对比实际实现与预期设计
• 为重写或重大重构做准备
• 审查项目的实际功能与人们对它的认知是否相符

---

工作流程

1. 确认范围 — 询问用户要分析的内容（整个仓库、特定目录或特定方面）
2. 深入扫描 — 系统地阅读项目结构、入口、配置、测试和核心逻辑
3. 综合整理 — 生成结构化的 SPEC 文档
4. 审阅 — 提交给用户，收集反馈并迭代
5. 保存 — 将最终 SPEC 写入双方商定的位置

---

第 1 步：确认范围

开始扫描前，询问用户：

What should I analyze?

A. Entire repository (recommended for small-medium projects)
B. Specific directory or module: [path]
C. Specific aspect only (e.g., API surface, data model, auth flow)

Depth level:
1. Overview — high-level architecture + tech stack + key features (fast, ~5 min)
2. Standard — includes API contracts, data models, config, dependencies (default)
3. Deep — adds internal module interactions, error handling patterns, test coverage analysis

如果项目较大（超过 500 个文件），建议从概览或特定模块开始。

---

第 2 步：深入扫描

系统地分析以下内容（根据项目实际情况调整）：

2.1 项目概况

• package.json、go.mod、Cargo.toml、pyproject.toml、pom.xml 等
• README、LICENSE
• Git 历史（首次提交日期、近期活动、贡献者数量）

2.2 架构

• 目录结构和组织模式（单体仓库、分层、六边形等）
• 入口（主文件、CLI 命令、服务引导程序）
• 模块边界和依赖关系图（内部）

2.3 技术栈

• 编程语言及版本约束
• 框架和主要库
• 构建工具和打包工具
• 运行时要求（Node 版本、Docker 等）

2.4 功能与行为

• 路由定义 / CLI 命令 / 导出函数
• 业务逻辑模块及其职责
• 后台任务、cron 任务、事件处理器

2.5 数据模型

• 数据库架构、迁移、ORM
• 关键数据结构及其关系
• 状态管理方式

2.6 API 接口

• HTTP 端点（方法、路径、请求 / 响应结构）
• GraphQL 架构 / gRPC 原型 / WebSocket 事件
• CLI 接口（命令、标志、参数）
• 导出的库 API（公共函数、类、类型）

2.7 配置与环境

• 环境变量及其用途
• 配置文件及其架构
• 功能标志、开关

2.8 外部依赖

• 第三方服务（数据库、队列、API）
• 基础设施要求（云服务、存储）
• 身份验证 / 授权提供方

2.9 测试与质量

• 测试框架和方法（单元、集成、端到端）
• 覆盖情况（已测试和未测试的部分）
• Lint、格式化、类型检查配置

2.10 部署与运维

• CI/CD 配置
• 部署目标和策略
• 监控、日志、健康检查

---

第 3 步：SPEC 文档结构

按以下章节生成 SPEC。省略不适用的章节。

# SPEC: [Project Name]

> Reverse-engineered specification — generated [date] from commit [short-hash]

## 1. Overview

### 1.1 Purpose
[One paragraph: what problem this project solves and for whom]

### 1.2 Key Capabilities
- [Bullet list of what the system can do, from a user's perspective]

### 1.3 Architecture Style
[e.g., "Monolithic Express.js API with React SPA frontend", "CLI tool with plugin system", "Microservices communicating over gRPC"]

---

## 2. Tech Stack

| Layer | Technology | Version |
|-------|-----------|---------|
| Language | ... | ... |
| Framework | ... | ... |
| Database | ... | ... |
| Build | ... | ... |
| Test | ... | ... |
| Deploy | ... | ... |

---

## 3. Project Structure

[Directory tree with annotations explaining each top-level directory's purpose]

---

## 4. Data Model

### 4.1 Core Entities
[For each entity: name, fields, relationships, constraints]

### 4.2 State Transitions
[If applicable: lifecycle states and valid transitions]

---

## 5. API Surface

### 5.1 [Interface Type: REST / CLI / Library / etc.]

[For each endpoint/command/function:]
| Method | Path/Command | Description | Auth |
|--------|-------------|-------------|------|
| ... | ... | ... | ... |

### 5.2 Request/Response Schemas
[Key request/response shapes with field types]

---

## 6. Configuration

| Variable / Key | Required | Default | Description |
|---------------|----------|---------|-------------|
| ... | ... | ... | ... |

---

## 7. External Dependencies

| Service | Purpose | Failure Impact |
|---------|---------|----------------|
| ... | ... | ... |

---

## 8. Business Rules & Constraints

- [Numbered list of invariants, validation rules, and business logic constraints discovered in the code]

---

## 9. Non-Functional Characteristics

### 9.1 Performance
[Observed patterns: caching, pagination, batch processing, etc.]

### 9.2 Security
[Auth mechanism, input validation patterns, secrets management]

### 9.3 Error Handling
[Error strategy: custom error types, error codes, retry policies]

---

## 10. Testing Strategy

| Type | Framework | Coverage Pattern |
|------|-----------|-----------------|
| Unit | ... | ... |
| Integration | ... | ... |
| E2E | ... | ... |

---

## 11. Known Gaps & Assumptions

- [Things that are unclear from the code alone]
- [Assumptions made during analysis]
- [Areas with no tests or documentation]

---

## 12. Appendix

### A. Dependency Graph
[Key module dependencies, import relationships]

### B. Environment Setup
[Steps to run the project locally, derived from config and scripts]

---

第 4 步：审阅与迭代

生成 SPEC 后，将其提交给用户并询问：

SPEC generated. Please review:

- Are there sections that need more detail?
- Are there inaccuracies I should correct?
- Should I add/remove any sections?
- Is the depth level appropriate?

Reply OK to save, or provide feedback for iteration.

根据反馈进行修改并重新提交，直到用户确认。

---

第 5 步：保存

询问用户希望保存到哪个位置：

Where should I save the SPEC?

A. docs/SPEC.md (recommended)
B. SPEC.md (project root)
C. Custom path: [specify]

---

分析方法

识别项目用途

• 首先查看 README 首行、package 描述字段、CLI 帮助文本
• 检查主入口：它会启动什么？
• 查看测试描述：它们通常会用通俗语言说明预期行为

发现架构

• 将 import/require 语句映射为构建依赖关系图
• 根据目录名称识别分层：controllers、services、models、routes、handlers、domain、infra
• 检查依赖注入模式、中间件链和插件注册

提取业务规则

• 查找验证函数、守卫子句、断言语句
• 检查错误消息——它们通常会用业务术语描述出了什么问题
• 查看测试断言——它们编码了预期行为

查找 API 契约

• 路由注册（Express：app.get()，FastAPI：@app.get()，Go：mux.HandleFunc()）
• 如果存在，查看 OpenAPI/Swagger 文件
• 请求验证架构（Joi、Zod、Pydantic、struct 标签）
• CLI 标志/参数定义（cobra、argparse、yargs）

检测数据模型

• ORM 模型定义（Prisma、SQLAlchemy、GORM、TypeORM）
• 迁移文件（按时间顺序）
• 核心领域对象的类型/接口定义
• 数据库种子文件

---

边缘情况

场景	处理方式
项目没有 README 或文档	在“已知缺口”中注明；根据代码推断用途
Monorepo 包含多个服务	询问用户要分析哪些服务；为每个服务生成一份 SPEC，或生成一份边界明确的统一 SPEC
项目使用代码生成	说明生成代码的用途，但重点关注事实来源（架构、proto 文件、模板）
混合使用多种模式的遗留项目	记录观察到的所有模式，并在“已知缺口”中注明不一致之处
项目是一个库（没有运行时）	重点关注导出的 API 接口、类型契约和测试中的用法模式
代码不完整或已损坏	记录现有内容，并明确标记已损坏/不完整的部分
项目文件超过 1000 个	从入口点开始并追踪关键流程；无需逐一详读每个文件
一个仓库包含多种语言	记录每种语言的用途及其交互方式

---

质量标准

一份优秀的逆向工程 SPEC 应通过以下检查：

• 不熟悉该项目的开发者能在 60 秒内了解其用途
• 技术栈部分足够完整，能用于搭建开发环境
• API 契约足够具体，可据此编写客户端
• 数据模型足够完整，可据此重建架构
• 业务规则明确说明（而不是藏在“参见代码”中）
• 如实列出已知缺口（不要编造无法确定的内容）
• SPEC 与实际代码一致（而不是与设想中的文档一致）

---

应避免的反模式

• 不要臆测意图。 如果无法确定某项内容为何存在，就如实说明。不要编造理由。
• 不要将代码复制到 SPEC 中。 描述行为和契约，不要粘贴实现。
• 不要包含临时状态。 SPEC 描述的是系统设计，而非其当前运行时状态。
• 不要过度说明内部细节。 重点关注边界、契约和行为。内部实现细节应写在代码注释中，而不是规格说明里。
• 不要假设 README 准确无误。 README 往往滞后于代码。请根据实际实现核实其中的说法。