Retrofitting OpenSpec Into Existing Projects: A Practical Playbook

Most teams don't have the luxury of starting from a clean slate. They have production systems, active customers, shipping deadlines, and years of accumulated decisions. That's exactly where OpenSpec delivers the most value.

The objective isn't to stop development and rewrite documentation. It's to capture reality, improve visibility, and make the existing system easier for both engineers and AI to understand.

The fastest path to ROI is incremental adoption alongside normal development.

Start With an Architecture Audit

Don't begin by writing specifications. Begin by understanding what already exists.

Inventory the major parts of the application:

• Business domains
• APIs
• Database models
• Background jobs
• Events
• External integrations
• Authentication
• Authorization
• Infrastructure

For each business capability, answer a few practical questions:

• What problem does it solve?
• Where does the code live?
• What triggers it?
• What data comes in?
• What data goes out?
• Which systems depend on it?

Ignore implementation details. Focus on system boundaries.

---

Organize Around Business Domains

Many mature codebases are organized by technical layers:

• Controllers
• Models
• Services
• Helpers

Those folders don't describe the business.

Instead, identify stable business capabilities:

• Orders
• Billing
• Inventory
• Customers
• Notifications
• Reporting

Each capability becomes an OpenSpec module. This structure remains stable even as implementation evolves.

---

Document the System as It Exists

Resist the urge to redesign while documenting.

Specifications should describe today's production behavior—not tomorrow's architecture.

If placing an order currently reserves inventory, captures payment, generates an invoice, and sends an email, document exactly that sequence.

Future improvements belong in future specifications. Accuracy is more valuable than aspiration.

---

Turn Existing APIs Into Specifications

Every API endpoint already defines a contract.

Extract that contract into a structured specification:

• Endpoint
• Inputs
• Validation rules
• Business behavior
• Responses
• Error conditions

The implementation already contains this information. The goal is simply to make it explicit and discoverable.

---

Surface Business Rules

Business rules are often scattered throughout the codebase:

• Service classes
• Validation logic
• Authorization policies
• Helper methods
• Database triggers
• Stored procedures

Collect them into a single source of truth.

Examples include:

• Orders above a certain value require approval.
• Administrators may bypass approval.
• Refunds are only allowed before settlement.
• Inactive users cannot create new orders.

These rules define how the business operates. They deserve to be documented independently of implementation.

---

Map the Domain Model

Specifications should describe the business entities that matter.

For each entity, capture:

• Fields
• Relationships
• Lifecycle
• Immutable attributes
• Derived values
• Calculated fields

This creates a shared understanding of the data model without requiring engineers to reverse-engineer the database.

---

Capture Workflows and Events

Modern systems are driven by workflows and events.

Document the flow from one business event to the next.

For example:

1. Order created
2. Inventory reserved
3. Payment requested
4. Payment confirmed
5. Invoice generated
6. Customer notified

These workflows often span multiple services and repositories. Making them explicit improves onboarding, debugging, and future refactoring.

---

Inventory External Dependencies

Every production system relies on external services.

Document each dependency along with:

• Purpose
• Authentication method
• Retry strategy
• Failure behavior
• Rate limits
• Fallback process

This information becomes invaluable during incidents and reduces operational risk as the system grows.

---

Prioritize High-Value Domains

Don't attempt to specify the entire platform in one sprint.

Start with the areas that carry the greatest business value.

A typical priority order looks like:

1. Authentication
2. Payments
3. Orders
4. Billing
5. Notifications
6. Reporting

Early wins build momentum while delivering immediate operational benefits.

---

Keep Specifications Close to the Code

Specifications should live alongside the implementation they describe.

Keeping documentation within each domain makes updates part of normal development instead of a separate maintenance task.

When specifications travel with the code, they're far more likely to remain accurate over time.

---

Validate Against Production

A specification should be complete enough that another engineer could implement the feature without reading the original code.

If critical information is missing, add it:

• Validation rules
• Permissions
• Edge cases
• Retry behavior
• Error handling
• Idempotency requirements

Specifications should reduce ambiguity, not introduce it.

---

Make Specifications Part of Every Pull Request

Specifications shouldn't be written once and forgotten.

Instead, make them part of the development workflow:

1. Update the specification.
2. Implement the change.
3. Update or add tests.
4. Review both specification and code together.

Treating specifications as part of the definition of done keeps documentation synchronized with production.

---

Generate Better Tests

Every documented workflow naturally becomes a set of test cases.

A simple "Cancel Order" workflow expands into scenarios such as:

• Customer cancels their own order
• Administrator cancels an order
• Order already shipped
• Order already cancelled
• Payment pending
• Refund already processed

Using specifications to drive testing increases coverage while ensuring tests reflect business behavior rather than implementation details.

---

Give AI Context Instead of Source Code

Large codebases overwhelm both people and AI.

Instead of exposing hundreds of thousands of lines of implementation, provide structured specifications for the relevant domains.

AI gains access to:

• Business terminology
• System boundaries
• Workflows
• Constraints
• Business rules

The result is more accurate code generation, better architectural suggestions, and fewer hallucinations caused by missing context.

---

Adopt Incrementally

Successful OpenSpec adoption doesn't require a migration project.

Instead, improve the specification whenever a feature is touched.

The workflow becomes simple:

• Update the specification.
• Modify the implementation.
• Update the tests.

Over time, undocumented legacy systems become well-defined, verifiable, and significantly easier to evolve—without interrupting product delivery.

---

Immediate ROI

Teams typically see value long before the migration is complete.

Within the first few weeks, OpenSpec can provide:

• A shared architectural map
• Searchable business rules
• Clear API contracts
• Documented workflows
• Improved onboarding
• Better AI-assisted development
• More reliable regression testing
• Faster incident response through documented dependencies

Each improvement compounds as more of the system becomes specified.

---

Common Pitfalls

The most common mistakes are surprisingly consistent:

• Documenting the desired architecture instead of production behavior
• Attempting to specify the entire platform before shipping
• Organizing specifications around technical layers instead of business domains
• Storing documentation in a separate repository
• Treating specifications as a one-time migration effort
• Refactoring implementation before accurately documenting existing behavior

Avoid these traps, and adoption remains low-risk and sustainable.

---

A 30-Day Rollout Plan

A practical rollout can fit comfortably into a single month without slowing feature delivery.

Week 1: Audit the system, identify business domains, and inventory dependencies.

Week 2: Fully specify the highest-value domain, including APIs, models, workflows, and business rules.

Week 3: Make specification updates part of every pull request and code review.

Week 4: Expand into adjacent domains while generating tests from the documented workflows.

By the end of the month, the team has a living specification, better onboarding materials, stronger regression coverage, and AI-ready documentation—all achieved without pausing product development.

Ship the System You Have

Retrofitting OpenSpec isn't about replacing your architecture. It's about making your current architecture understandable, verifiable, and easier to evolve.

Start by documenting reality. Keep specifications close to the code. Update them alongside every meaningful change.

The result isn't just better documentation. It's a development workflow where architecture, implementation, testing, and AI assistance all operate from the same source of truth.