#Technical design specs

A technical design spec defines how to build what the requirements ask for, in a form an agent implements against. This page covers the three forms it takes and where each one fits in the artifact chain.

#High-level design

The high-level design (HLD) translates the approved PRD into an architectural blueprint. It answers structural questions before any API or implementation detail is specified.

#C4 levels

The design documents the system at four levels:

#Technology stack

Each technology choice in the stack carries a version pin and a trade-off note: why this option, and what the alternatives gave up. The version pin makes the implementation reproducible across agent runs.

#Architecture decision records

An architecture decision record (ADR) captures a key choice: the context that drove it, the options considered, the decision, and its consequences. ADRs are written at decision time and stay in the design permanently.

#Non-functional requirement mapping

Each NFR from the PRD maps to the architectural decisions that satisfy it. This tracing lets a reviewer verify that every non-functional requirement has a design answer.

#Contract index

The Contract Index names every operation in the system and which component owns it. Full request and response bodies are deferred to the owning feature spec; the index records the operation name and the owning component.

#Interface and detailed design

The interface spec (ICD) and the detailed design expand the HLD into complete, implementable contracts.

#OpenAPI 3.1 document

Each REST boundary gets one complete OpenAPI 3.1 document. The document covers:

#Error contract

All error responses share a single RFC 9457 ProblemDetails shape:

A shared shape means clients parse errors the same way across every endpoint.

#What detailed design adds

Beyond the API contract, a detailed design includes a C4 component diagram for each service, a sequence diagram for each significant flow, and the database schema with an entity-relationship diagram.

#Coding standards

A coding standards spec (CS) sets the conventions the implementation run follows across the whole project:

• Naming conventions for files, types, variables, and exported symbols
• File and directory organization within each service or package
• Error-handling patterns: how errors are wrapped, propagated, and logged
• Testing expectations: coverage targets, required test kinds, and test organization
• Linting and formatting rules and the exact tool configuration
• Commit message conventions
• Pull request review standards: what a reviewer checks and what a PR requires before merge

The coding standards spec drafts when the PRD is approved, alongside the high-level design, and applies to every coding run in the project.

#Where technical design sits

The high-level design and coding standards draft as soon as the PRD is approved. The detailed design follows once the epic and the high-level design are both approved.

1. 1PRD
2. 2HLD + CS
3. 3Detailed design
4. 4Coding

Once approved, the technical design specs feed the coding run. The agent reads the interface spec, the approved coding standards, and the story to write code that matches the agreed contracts and conventions.

See requirements specs for the upstream spec the technical design depends on, and work items for how the coding run is dispatched.

#Next steps

• Requirements specs: the PRD and its requirements notation.
• UI/UX specs: the design artifact that drafts alongside the high-level design.
• Review findings: the verifier agent's findings and how to address them.
• Approve an artifact: what blocks approval and how to clear it.