SpecDDSoftware design practices
Software design practices expressed through SpecDD. These guides show how to turn design intent into local, reviewable specs that preserve responsibility, boundaries, dependency direction, public contracts, and domain behavior while humans and agents change the code.
- How to maintain the Single Responsibility Principle with SpecDD
Use Purpose, Owns, Must, Must not, and local tasks to keep each module, service, model, adapter, or component responsible for one coherent thing.
Read guide - How to separate concerns with local specs
Use local specs to keep responsibilities distinct: one spec owns behavior, sibling specs reference each other intentionally, and non-goals prevent overlap.
Read guide - How to define and enforce module and architecture boundaries with specs
Use SpecDD specs as architecture guardrails: module specs define responsibility, local specs narrow behavior, and Forbids and Must not keep changes inside the intended boundary.
Read guide - How to prevent cross-layer coupling
Use Depends on, Forbids, Must not, and local ownership to stop UI, API, domain, and infrastructure layers from reaching past their boundaries.
Read guide - How to keep UI components focused
Use component specs to keep UI code responsible for presentation and interaction while domain rules, persistence, and API behavior stay in their owning specs.
Read guide - How to avoid leaky abstractions
Use SpecDD contracts to keep callers depending on stable behavior rather than storage details, vendor APIs, database shapes, or framework internals.
Read guide - How to design testable code with specs
Use specs to shape code that is easier to test: local responsibilities, explicit dependencies, scenarios as inputs, and boundaries that keep setup small.
Read guide - How to define interfaces before implementation
Use SpecDD interface contracts to agree on what callers can use before deciding how the implementation will work internally.
Read guide - How to avoid god objects and god modules
Use local specs to prevent one object, service, module, or directory from accumulating unrelated behavior and becoming the place every change goes.
Read guide - How to split large features into small safe changes
Use SpecDD to turn a large feature into bounded, reviewable changes: one local spec at a time, with clear ownership, dependencies, and Done when checks.
Read guide - How to design for low coupling and high cohesion
Use SpecDD specs to keep related behavior together, dependencies intentional, and unrelated modules separated by clear contracts.
Read guide - How to write specs that prevent technical debt
Use SpecDD to prevent recurring debt patterns: vague ownership, convenience dependencies, duplicated rules, hidden shortcuts, and unfinished local tasks.
Read guide - How to use non-goals to prevent the wrong work
Write non-goals as practical Must not rules that stop likely overreach while keeping specs short, local, and maintainable.
Read guide - How to compare spec-driven development vs TDD
SpecDD defines durable behavior, ownership, and boundaries; TDD drives implementation through tests. Used together, specs explain why and tests prove what works.
Read guide - How to compare spec-driven development vs BDD
BDD centers shared behavior examples; SpecDD can include scenarios but also defines source-adjacent ownership, authority, non-goals, dependencies, and tasks.
Read guide - How to compare SpecDD specs vs architecture docs
Architecture docs explain broad decisions; SpecDD specs place durable behavior, ownership, and boundaries beside the code that must follow them.
Read guide - How to keep business rules in the domain layer
Use domain, model, policy, and service specs to own business rules while UI, API, jobs, and infrastructure delegate instead of duplicating decisions.
Read guide - How to prevent duplicate logic with specs
Use SpecDD specs to make duplicated logic visible, choose the owning rule, block secondary implementations, and review callers against the owner.
Read guide - How to design stable public APIs with specs
Use SpecDD API specs to make public contracts intentional and reviewable before implementation details become client-facing commitments.
Read guide - How to manage dependency direction with specs
Use SpecDD specs to make dependency direction explicit so modules, layers, packages, services, and adapters do not depend on the wrong things.
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 - 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 - Refactoring and maintenance
Use SpecDD to keep maintenance safe: preserve specified behavior, maintain authority while moving code, keep specs current, and delete obsolete contracts carefully.
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