SpecDDRefactoring and maintenance
Refactoring and maintenance guides for SpecDD projects. These articles show how to preserve behavior while changing structure, keep local specs aligned with moved code, split and extract modules safely, retire obsolete specs, and remove dead code without leaving stale contracts behind.
- How to refactor with SpecDD
Use SpecDD to make refactoring behavior-preserving: define the contract first, work inside authority, and update specs only when structure or ownership changes.
Read guide - How to refactor with agents safely
Use SpecDD to keep agent-assisted refactors small, behavior-preserving, authorized, and verifiable.
Read guide - How to update specs during refactoring
Keep specs accurate during refactors without inventing behavior changes: update structural sections, path references, tasks, and checks with the code.
Read guide - How to retire obsolete specs
Remove obsolete specs only after confirming their behavior, ownership, references, tasks, and inherited constraints are no longer active.
Read guide - How to split modules with local specs
Use local specs to divide a large module into smaller owned units without losing authority, inherited boundaries, or tests.
Read guide - How to move code without losing spec authority
Keep moved files governed by the right specs: update ownership, same-basename specs, references, paths, tests, and validation with the code move.
Read guide - How to extract a module with SpecDD
Use SpecDD to turn module extraction into a reviewed sequence: capture behavior, define the new owner, move code and tests, and preserve contracts.
Read guide - How to rename or move files without breaking spec resolution
Use a practical SpecDD file-move checklist for same-basename specs, explicit paths, references, case-sensitive names, content roots, and linting.
Read guide - How to remove dead code with SpecDD
Use SpecDD to delete dead code without deleting live behavior: trace authority, update or remove specs, adjust tests, and verify nothing still depends on it.
Read guide
More How-To categories
- Getting started
Start with spec-driven development, write your first local SpecDD spec, and run a small end-to-end change with human-and-agent-friendly guardrails.
11 guides - Install and setup
Install the SpecDD CLI, prepare Node.js when needed, initialize or update projects, and verify the framework files are wired correctly.
9 guides - Set up your agent
Set up Claude Code, Codex, GitHub Copilot, Cursor, Windsurf, Gemini CLI, OpenCode, Junie, Cline, Antigravity, and universal Agent Skills for SpecDD.
15 guides - Editor setup
Install SpecDD editor support, validate .sdd files, resolve path warnings, and use completions and section hints while writing specs.
4 guides - Agent workflows
Use SpecDD with agents by keeping prompts short, plans spec-bound, file changes authorized, context durable, and reviews tied to local .sdd contracts.
15 guides - Write specs by level
Write SpecDD specs at the right level: root specs for project context, module specs for area boundaries, and focused specs for local behavior and contracts.
14 guides - Use spec sections
Use SpecDD sections correctly: write only sections that add local value, keep authority clear, and express behavior, boundaries, tasks, scenarios, paths, and examples.
25 guides - Spec-writing technique
Improve SpecDD craft with techniques for small specs, right-level placement, naming, splitting, explicit rules, draft review, edge cases, and compatibility.
16 guides - Spec-driven workflows
Use SpecDD workflows to draft, review, implement, synchronize, and evolve local specs without losing source-of-truth context.
11 guides - Work with SpecDD skills
Use SpecDD skills deliberately: choose the right skill for the phase, keep authority clear, chain skills safely, and verify each result against local specs.
17 guides - Software design practices
Use SpecDD to make software design decisions operational: responsibility, boundaries, layers, cohesion, debt prevention, public APIs, and dependency direction.
20 guides - Adopt SpecDD on existing projects
Adopt SpecDD gradually in live codebases by starting with active areas, reviewing generated specs, expanding folder by folder, and measuring practical review and delivery signals.
10 guides - Testing and quality
Turn SpecDD specs into practical quality work: TDD and BDD loops, acceptance criteria, coverage tracing, CI checks, regression tests, and testability review.
11 guides - Code review and governance
Use SpecDD in code review and governance by checking local authority, behavior, boundaries, spec updates, agent output, and high-risk contract changes.
9 guides - Security and risk
Use SpecDD to make security and risk constraints local, explicit, reviewable, and hard for humans or agents to weaken accidentally.
13 guides - Teams and process
Use SpecDD as a team process by keeping durable behavior in specs, project planning in tickets, conventions in bootstrap.project.md, and reviews lightweight but consistent.
13 guides - Troubleshooting
Fix common SpecDD problems: agent setup, .sdd highlighting, CLI and Node errors, ambiguous specs, unresolved paths, vague specs, stale criteria, and skill installs.
12 guides