Skip to content
ModernizeSpec

Quick Start

Add ModernizeSpec to your legacy project in 5 minutes. After this guide, any AI coding agent will understand your modernization context.

Prerequisites

Section titled “Prerequisites”
  • A legacy codebase you want to modernize
  • Node.js 18+ (for the CLI) or a text editor (for manual setup)

Option A: Using the CLI

Section titled “Option A: Using the CLI”

  1. Initialize ModernizeSpec

    Terminal window
    npx modernizespec init

    The interactive wizard asks about your legacy system (language, framework, LOC, entity count) and target architecture. It generates the .agents/modernization/ directory with starter files.

  2. Review the generated files

    Terminal window
    ls .agents/modernization/
    # manifest.json  domains.json  complexity.json  MODERNIZATION.md

    The wizard creates manifest.json with your project metadata and stub files for domains, complexity, and the human-readable overview.

  3. Run analysis (optional)

    Terminal window
    npx modernizespec analyze

    Scans your codebase and suggests bounded contexts, complexity hotspots, and extraction tiers. Review and adjust the suggestions.

  4. Validate

    Terminal window
    npx modernizespec validate

    Checks all files against JSON Schemas. Fix any validation errors before committing.

  5. Commit to version control

    Terminal window
    git add .agents/modernization/
    git commit -m "feat: add ModernizeSpec modernization context"

    The spec files are now part of your project. Any AI agent reading the repository will discover them.

Option B: Manual Setup

Section titled “Option B: Manual Setup”

If you prefer not to use the CLI, create the files by hand.

  1. Create the directory

    Terminal window
    mkdir -p .agents/modernization

  2. Create manifest.json

    {
      "modernizespec": "0.1.0",
      "project": "YourProject",
      "legacy": {
        "framework": "django",
        "language": "python",
        "loc": 85000,
        "entities": 120,
        "endpoints": 200
      },
      "target": {
        "language": "typescript",
        "architecture": "modular-monolith",
        "pattern": "strangler-fig"
      },
      "files": {
        "domains": "domains.json"
      }
    }

    Adjust the values to match your project.

  3. Create domains.json

    Start with your most important bounded contexts:

    {
      "contexts": [
        {
          "name": "Orders",
          "type": "core",
          "entities": ["Order", "OrderItem", "OrderStatus"],
          "aggregateRoot": "Order",
          "loc": 15000,
          "endpoints": 25,
          "coupling": {
            "internal": 0.80,
            "external": 0.25
          },
          "dependencies": ["Inventory", "Payments"],
          "godClasses": []
        }
      ],
      "contextMap": []
    }

  4. Create MODERNIZATION.md

    # Modernization Overview
    

    This project is migrating from Django/Python to TypeScript
    using the Strangler Fig pattern.
    

    ## Current Status
    

    Phase 1: Orders module extraction (in progress)
    

    ## Key Decisions
    

    - Hexagonal architecture in target system
    - Parity tests for every extracted module
    - No Big Bang — incremental extraction

  5. Commit

    Terminal window
    git add .agents/modernization/
    git commit -m "feat: add ModernizeSpec modernization context"

What Happens Next

Section titled “What Happens Next”

Once the files are committed, any AI coding agent that reads your project will discover the modernization context:

Claude Code reads .agents/ directories automatically at session start. It will see the bounded contexts, complexity tiers, and extraction plan without any additional configuration.

Verify It Works

Section titled “Verify It Works”

Ask your AI agent:

“What bounded contexts exist in this project and what is the extraction plan?”

The agent should respond with information from your domains.json and extraction-plan.json files, not generic guesses.

Next Steps

Section titled “Next Steps”