{
  "markdown": "# Refactoring-Driven Development (RDD)\n\n> A Claude Code plugin for **rewriting code with parity guarantees**, from spec through characterization tests to a working port.\n\nRDD is to refactoring/migration what TDD is to greenfield development: a discipline that forces you to **lock current behavior in tests before you touch a line of code**, then rewrite confidently.\n\n> **A note on \"TDD\".** Classical TDD (Beck) writes a failing test for code that doesn't exist yet, then makes it pass. RDD applies the same test-first principle to **legacy code that already exists** — what Michael Feathers called *characterization testing*. Tests describe what the legacy *does*, not what it *should do*. The discipline is the same (red → green → refactor); the starting point differs.\n\nIt works equally for:\n\n- **Migration between stacks** — Edge Functions → backend service, Express → NestJS, Rails → Phoenix, monolith → services\n- **In-place refactor of a legacy module** — same stack, but cleaner code under a behavior-locking test suite\n- **Vendor escape** — moving off a managed service to self-hosted with the same observable contract\n- **Language port** — JS → TS, Python 2 → Python 3, etc.\n- **Idiomatic improvement** — clean up a parity-correct module after porting, with tests as a safety net\n\n## The 6 skills\n\n**Core pipeline (4 skills):**\n\n```\n/rdd-specify-01        →  Decide where to migrate: stack, architecture, conventions\n/rdd-map-codebase-02   →  Survey the legacy, identify modules, propose order\n/rdd-specify-03        →  Capture business rules from code (single module or batch-all-via-subagents)\n/rdd-refactor-04       →  Plan characterization tests, lock legacy, port with parity (per module)\n```\n\n**Optional (2 skills):**\n\n```\n/rdd-improve-05        →  After parity, refactor the new code idiomatically — tests guard parity\n/rdd-status            →  Show migration progress across all modules and phases\n```\n\nThree skills to **specify and map** (specify-01 → map-codebase-02 → specify-03) before one skill to **refactor with TDD** (refactor-04, which merges test planning + parity port), with one to **polish** (improve-05) and one to **observe** (status). Each reads the artifacts the previous one wrote, so you can stop and resume across sessions. Artifacts live under `rdd/` (configurable).\n\n## Workflow\n\n```\n        ┌──────────────────┐\n        │ /rdd-specify-01  │  ← decide architecture, framework, conventions\n        └────────┬─────────┘\n                 ▼\n           rdd/TARGET.md  +  populates .rdd.yml target block\n                 │\n                 ▼\n        ┌────────────────────────┐\n        │ /rdd-map-codebase-02   │  ← survey legacy with target in mind\n        └────────┬───────────────┘\n                 ▼\n            rdd/MAP.md\n                 │\n                 ▼  (per module, repeat)\n        ┌──────────────────┐      ┌──────────────────┐      ┌──────────────────┐\n        │ /rdd-specify-03  │  →   │ /rdd-refactor-04 │  →   │ /rdd-improve-05  │\n        └────────┬─────────┘      └────────┬─────────┘      └────────┬─────────┘\n                 ▼                         ▼                         ▼\n          rdd/<m>/SPEC.md      rdd/<m>/TESTS.md (Phase 1)    idiomatic code\n                               + parity-correct code         (same green tests\n                               + green tests on legacy        still pass)\n                                 AND target\n\n           /rdd-status  ← run anytime to see where each module is\n```\n\n## Principles\n\n1. **Parity first, refactor later.** First port mimics current behavior exactly. Improvement is a separate step, after green tests prove parity.\n2. **Decide before mapping.** Target architecture (TD-01, TD-02...) is decided up front and recorded with rationale. Module grouping and test posture flow from those decisions.\n3. **Spec before code.** Every module gets a written spec with numbered business rules (BR-01, BR-02...) before any porting.\n4. **Characterization, not aspiration.** Tests describe what the system *does*, not what it *should do*. Bug-for-bug parity is the default; intentional behavior changes are tracked explicitly.\n5. **Tests that earn their keep.** Every test maps 1:1 to a business rule or observable side effect, written using AC template formulas (`[METHOD] [/path] with [input] returns [status] with [body]`). No snapshot-of-everything, no \"controller calls service\", no `expect(x).toBeDefined()`.\n6. **Validate before generating.** Each skill runs a pre-flight check against its inputs (config consistency, cross-document contradictions, missing decisions) before writing a single line of output.\n7. **Resumable execution.** Long-running ports persist state in a progress file (`REFACTOR.progress.md`) and a per-entry-point task list. Stop after each entry point and wait for explicit \"Continuar?\" — unless the user opted into continuous mode.\n8. **Fix-loop discipline.** When tests fail during porting, max 3 focused attempts before escalating. No weakening tests, no skipping, no swallowing errors.\n9. **Strangler-style cutover.** New code coexists with legacy behind a feature flag. Cutover is gradual and reversible.\n\n## Installation\n\nInside Claude Code, add the marketplace and install the plugin:\n\n```\n/plugin marketplace add gabriel-f-santos/refactoring-driven-development\n/plugin install refactoring-driven-development@gabriel-f-santos\n```\n\nVerify the skills are available by typing `/` in Claude Code — you should see `/rdd-specify-01`, `/rdd-map-codebase-02`, `/rdd-specify-03`, `/rdd-refactor-04`, `/rdd-improve-05`, and `/rdd-status`.\n\nThen in any project where you want to use RDD, just invoke `/rdd-specify-01` — the skill auto-creates `.rdd.yml` from the bundled template if it doesn't exist and walks you through filling in legacy + target stack.\n\n## Configuration: `.rdd.yml`\n\n```yaml\nlegacy:\n  stack: \"Supabase Edge Functions (Deno)\"\n  source: \"supabase/functions/\"\n  database: \"Postgres (Supabase)\"\n  notes: \"RLS policies in migration files; some shared utilities in _shared/\"\n\ntarget:\n  stack: \"NestJS + Fastify\"\n  source: \"apps/api/src/\"\n  test_framework: \"Vitest\"\n  test_strategy: \"integration-first; testcontainers Postgres; mocks only at HTTP boundary\"\n\nartifacts_dir: \"rdd/\"\n\nconventions:\n  business_rule_prefix: \"BR\"\n  module_dir_pattern: \"rdd/{module}/\"\n\n# Optional: skip /rdd-specify-01 when target stack is already established\n# (e.g., in-place refactor of a consolidated codebase). The skill produces\n# a minimal TARGET.md focused on conventions.\nskip_target: false\n```\n\nThe skills read this file. **Never** hardcode stack assumptions — write them here once.\n\n## Lightweight mode\n\nThe full pipeline is calibrated for **high-stakes work** — production migrations, multi-month rewrites, multi-tenant SaaS. For smaller scopes, skip what doesn't pay for itself:\n\n| Scope | Skip | Why |\n|-------|------|-----|\n| In-place refactor with target = legacy stack | Set `skip_target: true` | No architectural decisions to make; conventions already established |\n| Single small module (≤5 entry points) | Skip `/rdd-map-codebase-02` | Module boundary is obvious; just go straight to `/rdd-specify-03` |\n| Pure cosmetic refactor (rename, extract method) inside an already-tested module | Skip everything; use tests directly | RDD overhead doesn't pay off for a 10-minute change |\n| Greenfield code | Don't use RDD | RDD assumes legacy code to characterize; for new code use spec-kit or similar |\n\n**Heuristic:** if the change touches >300 lines of legacy code OR has >2 reasonable architectures OR will be in production for >12 months, run the full pipeline. Otherwise, drop phases that don't earn their keep.\n\n## Use cases\n\n### Use case 1: Cross-stack migration\n\nYou have a legacy backend (Edge Functions, monolithic Rails app, PHP service, etc.) and want to migrate to a new stack module by module.\n\n```bash\n/rdd-specify-01                  # decide target stack, architecture, conventions → rdd/TARGET.md\n/rdd-map-codebase-02             # survey the legacy with target in mind → rdd/MAP.md\n/rdd-specify-03                  # batch mode: parallel-spec ALL modules → rdd/<m>/SPEC.md each\n/rdd-refactor-04 products        # → rdd/products/TESTS.md + parity port (one module at a time)\n/rdd-refactor-04 customers       # next module\n# ... repeat per module\n```\n\n`rdd-specify-01`, `rdd-map-codebase-02`, and `rdd-specify-03` (in batch mode) run **once each up front** — they're analysis steps that don't affect production. Then `rdd-refactor-04` runs **per module** because porting must be sequential (parity verification, fix-loop discipline, cutover). Cut over via feature flag when each module is ready.\n\nIf you prefer to spec one module at a time (e.g., to interview tribal knowledge per module), invoke `/rdd-specify-03 <module>` instead — same skill, single-module mode.\n\n### Use case 2: In-place refactor\n\nSame stack, but a module accumulated cruft and you want to rewrite it cleanly. The same flow works — `legacy` and `target` in `.rdd.yml` point to the same stack but different source directories (or branches).\n\n### Use case 3: Vendor escape\n\nMoving off a SaaS dependency. Treat the old vendor's API as `legacy`. Treat your replacement as `target`. Run the flow per consumer surface.\n\n### Use case 4: Idiomatic improvement after porting\n\nYou ran `/rdd-refactor-04 products` and the new module is parity-correct but ugly — direct copy of legacy structure, repeated code, no value objects. Run `/rdd-improve-05 products` to clean up incrementally. The same characterization tests from `/rdd-refactor-04` guard parity: any refactor that breaks observable behavior shows up immediately.\n\n```bash\n/rdd-improve-05 products       # → rdd/products/IMPROVE.md (refactor plan), then incremental refactors\n```\n\n### Use case 5: Tracking progress across many modules\n\nFor a multi-module migration spanning weeks or months, you need a quick way to see where each module is. Run `/rdd-status` anytime:\n\n```bash\n/rdd-status                 # reads existing artifacts, prints a per-module phase table\n```\n\nNo persistent state file — `/rdd-status` infers progress from what's on disk.\n\n## What this is not\n\n- **Not a code generator from scratch.** RDD assumes you have working legacy code to characterize. For greenfield work, use spec-kit or similar.\n- **Not a linter or autofix.** It coordinates a human + LLM workflow; it doesn't blindly transform code.\n- **Not microservices-specific.** The Strangler Fig pattern that inspired part of this is *one* cutover strategy among many.\n\n## Anti-pattern: tests that don't earn their keep\n\nRDD has strong opinions on what tests to write — and not write — during refactoring. Summary:\n\n| Write                                | Don't write                              |\n|--------------------------------------|------------------------------------------|\n| End-to-end use cases from spec       | \"Controller calls service\"               |\n| Domain invariants                    | DTO validation already enforced by lib   |\n| Observable error paths (403, 422)    | Snapshots of mutable JSON                |\n| Idempotency of webhooks              | `expect(x).toBeDefined()` without intent |\n| Property-based for calculations      | Mock-of-mock-of-mock                     |\n| Boundary cases discovered in code    | Tests that break on every refactor       |\n\nIf a test breaks during refactor *without changing observable behavior*, it was testing implementation. Delete it.\n\n## Contributing\n\nPRs welcome. Especially:\n\n- Examples of RDD applied to other migration scenarios (add to `examples/`)\n- Improvements to skill prompts based on real-world usage\n- Translations of the skill prompts (current: English; the methodology is language-agnostic)\n\n## License\n\nMIT\n",
  "bytes": 11739,
  "sha": "0e3256ad6414167862a0d7dce14d70e02d885d58af93eb64a950628c401340a4",
  "repo_slug": "gabriel-f-santos/refactoring-driven-development",
  "fonte": "repo",
  "truncated": false,
  "api": "https://agentalog.com/api/listings/plg_gabriel_f_santos_refactoring_driven_deve_6ddce1d0/readme"
}