Reverse-engineer a SPEC document from an existing project. Analyzes code, config, tests, and structure to produce a comprehensive specification. Triggers on: code-to-spec, reverse spec, generate spec, 逆向规格, 生成规格文档, 生成设计文档, 生成设计方案, extract spec, document this project, what does this project do.

to spec — Reverse Engineer Project Specification Analyze an existing codebase and produce a structured SPEC document that captures what the project does, how it's built, and what contracts it exposes. The output is a living specification that could be used to rebuild the project from scratch or onboard new contributors. When to Use You want a comprehensive understanding of an existing project Onboarding new team members who need a high level overview Documenting a project that was built without a spec Comparing actual implementation against intended design Preparing for a rewrite or major refactor Auditing what a project actually does vs. what people think it does The Job 1. Scope confirmation — ask user what to analyze (entire repo, specific directory, or specific aspect) 2. Deep scan — systematically read project structure, entry points, config, tests, and core logic 3. Synthesize — produce a structured SPEC document 4. Review — present to user for feedback and iteration 5. Save — write final SPEC to agreed location Step 1: Scope Confirmation Before scanning, ask the user: If the project is large ( 500 files), recommend starting with Overview or a specific module. Step 2: Deep Scan Systematically analyze the following (adapt to what exists): 2.1 Project Identity package.json , go.mod , Cargo.toml , pyproject.toml , pom.xml , etc. README, LICENSE Git history (first commit date, recent activity, contributor count) 2.2 Architecture Directory structure and organization pattern (monorepo, layered, hexagonal, etc.) Entry points (main files, CLI commands, server bootstrap) Module boundaries and dependency graph (internal) 2.3 Tech Stack Language(s) and version constraints Frameworks and major libraries Build tools and bundlers Runtime requirements (Node version, Docker, etc.) 2.4 Features & Behavior Route definitions / CLI commands / exported functions Business logic modules and their responsibilities Background jobs, cron tasks, event handlers 2.5 Data Model Database schemas, migrations, ORMs Key data structures and their relationships State management approach 2.6 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) 2.7 Configuration & Environment Environment variables and their purpose Config files and their schema Feature flags, toggles 2.8 External Dependencies Third party services (databases, queues, APIs) Infrastructure requirements (cloud services, storage) Authentication/authorization providers 2.9 Testing & Quality Test framework and approach (unit, integration, e2e) Coverage patterns (what's tested, what's not) Linting, formatting, type checking setup 2.10 Deployment & Operations CI/CD configuration Deployment targets and strategies Monitoring, logging, health checks Step 3: SPEC Document Structure Generate the SPEC with these sections. Omit sections that don't apply. Step 4: Review & Iteration After generating the SPEC, present it and ask: Apply feedback and re present until user confirms. Step 5: Save Ask user for save location: Analysis Heuristics Identifying Purpose Look at README first line, package description field, CLI help text Check the main entry point — what does it bootstrap? Look at test descriptions — they often describe expected behavior in plain language Discovering Architecture Map import / require statements to build dependency graph Identify layers by directory naming: controllers , services , models , routes , handlers , domain , infra Check for dependency injection patterns, middleware chains, plugin registrations Extracting Business Rules Look for validation functions, guard clauses, assertion statements Check error messages — they often describe what went wrong in business terms Examine test assertions — they encode expected behavior Finding API Contracts Route registrations (Express: app.get() , FastAPI: @app.get() , Go: mux.HandleFunc() ) OpenAPI/Swagger files if present Request validation schemas (Joi, Zod, Pydantic, struct tags) CLI flag/argument definitions (cobra, argparse, yargs) Detecting Data Models ORM model definitions (Prisma, SQLAlchemy, GORM, TypeORM) Migration files (in chronological order) Type/interface definitions for core domain objects Database seed files Edge Cases Scenario Handling Project has no README or documentation Note this in "Known Gaps"; infer purpose from code Monorepo with multiple services Ask user which service(s) to analyze; produce one SPEC per service or a unified SPEC with clear boundaries Project uses code generation Document the generated code's purpose but focus on the source of truth (schemas, proto files, templates) Legacy project with mixed patterns Document all observed patterns, note inconsistencies in "Known Gaps" Project is a library (no runtime) Focus on exported API surface, type contracts, and usage patterns from tests Incomplete or broken code Document what exists, mark broken/incomplete areas explicitly Project 1000 files Start with entry points and trace key flows; don't exhaustively read every file Multiple languages in one repo Document each language's role and how they interact Quality Criteria A good reverse engineered SPEC should pass these checks: [ ] A developer unfamiliar with the project could understand its purpose in 60 seconds [ ] The tech stack section is complete enough to set up a dev environment [ ] API contracts are specific enough to write a client against [ ] Data models are complete enough to recreate the schema [ ] Business rules are explicit (not buried in "see code") [ ] Known gaps are honestly listed (don't invent what you can't determine) [ ] The SPEC matches the actual code (not aspirational documentation) Anti Patterns to Avoid Don't invent intent. If you can't determine WHY something exists, say so. Don't fabricate rationale. Don't copy code into the SPEC. Describe behavior and contracts, don't paste implementations. Don't include transient state. The SPEC describes the system's design, not its current runtime state. Don't over specify internals. Focus on boundaries, contracts, and behavior. Internal implementation details belong in code comments, not specs. Don't assume the README is accurate. READMEs often lag behind code. Verify claims against actual implementation.