{"slug": "reverse-engineering-existing-code-into-specs", "title": "Reverse Engineering Existing Code into Specs", "summary": "The AI Unified Process ships a `/aiup-core:reverse-engineer` skill that reads an existing project's controllers, views, services and database schema to generate three artifacts: a PlantUML use case diagram, one use case specification per use case, and a Mermaid entity model with attribute tables. The post compares that output with other spec-driven tools, noting Kiro (AWS) generates `product.md`, `tech.md` and `structure.md` steering docs, BMAD Method offers `document-project` and `generate-project-context` workflows, and GitHub Spec Kit's `specify init` does not infer specs for existing behavior, relying instead on community extensions such as Brownfield Bootstrap's `/speckit.brownfield.migrate`. The author cautions that generated specs are only a first draft because code shows what a system does, not why, so hidden business rules need review by domain experts.", "body_md": "## Most Code Already Exists\n\nSpec-Driven Development works great when you start a new project. You write the specs first, and the AI agent implements them. But most of us don’t work on new projects. We work on systems that are five, ten or twenty years old. Often there are no specs at all, or the specs are outdated.\n\nSo the first question in many of my workshops is: How do we get specs for the code we already have?\n\nThe answer is reverse engineering. The AI agent reads the existing code and creates the specs from it. Then you review them, fix them, and from then on you can work spec-driven.\n\nIn this post, I show what the AI Unified Process offers for this, and how other spec-driven tools handle existing code.\n\n## The Reverse-Engineer Skill of the AI Unified Process\n\nThe AI Unified Process has a skill called `/aiup-core:reverse-engineer`. You run it in an existing project, and it creates three kinds of artifacts:\n\n1. **A use case diagram** in PlantUML with all actors and use cases of the system.\n2. **One use case specification per use case** with actors, preconditions, main success scenario, alternative flows, postconditions and business rules.\n3. **An entity model** with a Mermaid ER diagram and attribute tables with data types and validation rules.\n\nThe skill reads controllers, views, services and the database schema. From this, it derives what the users can do with the system and which data the system manages.\n\nThese are the same artifacts that you create in a new project with the AI Unified Process. So after the reverse engineering, there is no difference anymore between a new and an existing project. You use the same skills for the next steps: `/aiup-core:spec-review` to check the quality of the specs, and then the implementation and test skills.\n\nOf course, the generated specs are only a first draft. The code shows what the system does, not why. Business rules that are hidden in the code need a review by people who know the domain.\n\n## What Other Spec-Driven Tools Do\n\nI looked at the popular spec-driven tools and some community projects. All of them have some support for existing code, but they create very different results.\n\n**Kiro** (AWS) has a feature called “Generate Steering Docs”. It analyzes the code and creates three files: `product.md`, `tech.md` and `structure.md` ([Kiro blog](https://kiro.dev/blog/from-chat-to-specs-deep-dive/)). These files give the agent context about the product, the tech stack and the code structure. They are not specs of the features.\n\n**BMAD Method** has the `document-project` workflow. It scans the project and documents the current state, for example architecture and modules. For smaller needs, there is `generate-project-context`, which captures conventions and patterns ([BMad docs](https://docs.bmad-method.org/how-to/established-projects/)). The output is project documentation that later feeds the PRD.\n\n**GitHub Spec Kit** does not do reverse engineering on its own. The official guide says that `specify init` does not infer specs for existing behavior. It recommends writing specs only for the changes you plan ([Spec Kit guide](https://github.github.com/spec-kit/guides/existing-projects.html)). For reverse engineering, there are community extensions like Brownfield Bootstrap with `/speckit.brownfield.migrate` ([PR #2145](https://github.com/github/spec-kit/pull/2145)).\n\nThere are also smaller community tools:\n\n- [InferSpec](https://pypi.org/project/inferspec/) creates OpenSpec specs, one per capability. It uses code, git history and docs, and links every requirement back to file and line. For gaps, it asks the user questions.\n- [StackShift](https://claudepluginhub.com/skills/jschulte-stackshift/analyze) is a Claude Code plugin with a six-step process. The output is for Spec Kit or BMAD.\n- [CoDD](https://pypi.org/project/codd-dev/1.2.1/) has`codd extract` , which creates design documents from the source code.\n- [spec-driven-dev](https://agentskill.sh/plugins/viktordolezel/spec-driven-dev) has a`/retrofit` command that goes through discovery, “archaeology”, gaps and finally specs.\n\n| Tool | Command | What it creates | \n|---|---|---|\n| AI Unified Process | `/aiup-core:reverse-engineer` | Use case diagram, use case specs, entity model | \n| Kiro | Generate Steering Docs | Product, tech and structure context files | \n| BMAD Method | `document-project` | Project documentation (architecture, modules) | \n| Spec Kit | Community extensions | Constitution and feature specs | \n| InferSpec | `/inferspec-scan` | OpenSpec capability specs | \n| CoDD | `codd extract` | Design documents | \n\n## Context for the Agent or Requirements for the Team?\n\nWhen you look at the results, you see two different goals.\n\nMost tools create **context for the AI agent**. Kiro’s steering files and BMAD’s project documentation tell the agent which framework is used, how the code is structured and which conventions to follow. This is useful, but it describes the technology, not the business.\n\nOther tools create **feature or capability specs**. InferSpec and the Spec Kit extensions go further and describe behavior. But their format is specific to the tool, and they don’t model the data.\n\nThe AI Unified Process creates **requirements that people can read and discuss**. Use cases and entity models have been used in requirements engineering for decades. A business analyst, a product owner or a domain expert can review a use case specification without knowing the code. And the entity model shows the data, which is often the most valuable part of a business application.\n\nThis matters because reverse-engineered specs are never correct on the first try. Someone from the business must check them. If the specs are written for the agent, only developers can do this review. If the specs are use cases, the whole team can do it.\n\n## Conclusion\n\nReverse engineering is the door to Spec-Driven Development for existing systems. Many tools offer it, but they answer different questions. Kiro and BMAD help the agent understand the code. InferSpec and the Spec Kit extensions describe features in their own format.\n\nThe AI Unified Process creates use cases and an entity model. These are artifacts the whole team understands, and the same artifacts you use in a new project. So you can start with an existing system and continue with exactly the same process.\n\nTry it on one of your projects and tell me what you think. You find the AI Unified Process at [unifiedprocess.ai](https://unifiedprocess.ai).\n\n*All information about the other tools is as of October 2026. These tools change fast, so please check their documentation for the current state.*", "url": "https://wpnews.pro/news/reverse-engineering-existing-code-into-specs", "canonical_source": "https://martinelli.ch/reverse-engineering-existing-code-into-specs/", "published_at": "2026-10-11 08:49:56+00:00", "updated_at": "2026-10-11 08:53:58.340161+00:00", "lang": "en", "topics": ["ai-agents", "developer-tools", "ai-tools"], "entities": ["AI Unified Process", "Kiro", "AWS", "BMAD Method", "GitHub Spec Kit", "Brownfield Bootstrap", "InferSpec", "StackShift"], "also_reported_by": [], "alternates": {"html": "https://wpnews.pro/news/reverse-engineering-existing-code-into-specs", "markdown": "https://wpnews.pro/news/reverse-engineering-existing-code-into-specs.md", "text": "https://wpnews.pro/news/reverse-engineering-existing-code-into-specs.txt", "jsonld": "https://wpnews.pro/news/reverse-engineering-existing-code-into-specs.jsonld"}}