An implementation constraint limits how a solution may be built, not just what it must do. Architectural boundaries, technical expectations, and standards belong in the specification alongside the intended outcome and how that outcome will be verified. section 2.1
Correct behavior, wrong construction
A URL shortener’s redirect feature keeps HTTP handling in routes, behavior in services, persistence behind repositories, and domain rules free of framework dependencies. A later expiry or click-analytics feature can pass its acceptance tests while putting business logic in a route and accessing persistence directly. The feature works, but it violates the construction constraints. section 3.2.3
Put recurring constraints in durable project-level context rather than repeating them in each agent conversation. For an individual change, use the design conversation to identify affected components, integration points, and security, performance, or compliance constraints. Then make the task breakdown reflect both the acceptance criteria and the chosen technical approach. section 3.2.3 section 2.2.1
Listing 3.3 Establish construction constraints in OpenSpec config.yaml
schema: spec-driven
context: |
Tech stack: Node.js
Domain: URL shortener
Conventions: Simple, dependency-free, and use built-in modules.
Construction Constraints:
- Keep routes thin.
- Routes handle HTTP only.
- Put behavior in services.
- Keep the domain rules framework-free.
- Access data through repositories.
rules:
proposal:
- Always ask about error handling for invalid inputs
and an appropriate responseThe configuration makes the URL shortener’s standing construction constraints explicit: thin HTTP-only routes, services for behavior, framework-free domain rules, and repository-mediated data access. section 3.2.3
When an implementation collapses an architectural boundary, fix the current specification and change the workflow context if the same mistake could recur. Passing behavior checks alone does not establish that construction intent survived. If regeneration from the same specification produces different behavior, strengthen its fidelity rather than treating the generated code as the specification. section 3.2.5 section 3.5.3
