Harness SDD + OpenSpec: Spec‑Driven Development for Stable AI‑Assisted Changes

Problem Statement

When developers rely on an AI coding assistant, the generated code may work initially, but later the conversation context is lost, requirements exist only in chat logs, design decisions are invisible to teammates, and the rationale behind the code is unclear. These issues arise from the collaboration model with AI rather than the AI itself.

Spec‑Driven Development (SDD)

SDD places an executable specification contract at the center of development. Before any code is written, humans and AI must agree on what to build . The method merges requirement analysis, behavior definition, verification evidence, and version release into a closed‑loop system, turning “write‑then‑test” into “define‑then‑implement”.

Core concepts

Spec : a single source of truth describing current system behavior as Requirement + Scenario, without implementation details.

Change : a proposed modification packaged in its own folder, containing proposal, delta spec, design, and tasks.

Delta : the difference of a change relative to the current spec (added/modified/removed); merged into the main spec during archiving.

Design philosophy (OpenSpec)

Fluid, not rigid – stage gates can be reordered as needed.

Artifact‑easy, not complex – minimal ceremony, incremental strictness.

Brownfield‑first – prioritize existing systems, describe deltas first.

Challenges in the AI‑Coding Era

Context drift – AI does not retain team knowledge, leading to inconsistent outputs.

Acceptance without evidence – no standardized behavior definition, reviews rely on memory.

Untracked changes – cross‑repo modifications lack a unified entry point.

Manual regression – each release requires human verification, making defects common.

SDD Solution

SDD introduces a behavior contract that serves three roles:

Requirement : the proposal explains why a change is needed; the spec (GIVEN/WHEN/THEN) describes what the change looks like.

Test : matrix.yaml is loaded by verification scripts; the spec itself becomes the test.

Gate : a change can be archived only after passing two verification rounds, preventing unchecked merges.

Engineer responsibilities shift from writing business logic to designing constraints. Before SDD, engineers write code , debug manually , and rely on oral agreements; after SDD, they design specs , define matrix cases , and let machines verify .

Why OpenSpec

Three mainstream SDD implementations were compared:

Spec Kit (GitHub) : feature‑complete but heavyweight, with rigid stage gates, extensive Markdown requirements, and a Python environment; high onboarding cost.

Kiro (AWS) : powerful but locked to AWS IDE and Claude model; incompatible with existing toolchains and hard to migrate.

OpenSpec (Fission AI) : lightweight Markdown + AI slash command, tool‑agnostic, brownfield‑friendly, and supports >25 tools with zero migration cost.

OpenSpec Core Advantages

Less rigid stage gates – artifacts can be created in any order, strictness added on demand.

Tool‑independent – works with Claude Code, Cursor, Codex, etc.

Project Structure and Design Logic

The design separates change metadata from the system state , allowing multiple changes to proceed in parallel without conflict. Each change is a complete delivery unit consisting of: proposal.md – answers “why”, “what”, and “risk”; audience: reviewers/managers. spec.md (delta) – lists added/modified/removed behavior; audience: machines and humans. design.md – explains alternative solutions and rationale; audience: architects. tasks.md – breaks the change into stages and self‑test steps; audience: implementers/QA. matrix.yaml – maps scenarios to machine‑executable cases; audience: verification scripts. reports/ – real‑device run results and baseline comparisons; audience: CI/archive decisions.

Example proposal snippet (Why section must reference a concrete report line) :

## Why  数据依据（必须引用具体报告行）:
- `reports/probe-<date>-<time>.csv:L23` utterance "切到模式A" ...
- MCP Server :<mcp-port>/sse tools/list 中无 setMode
- Agent 中枢 fast-path-rules.json grep feature_mode 结果为空

The design follows the OpenSpec principle “Agree before you build”. Without data‑backed justification, a change cannot be archived.

Spec delta example (describes only the changes) :

--- id: feature-control version: 0.1.0 status: draft evaluators:
  - scripts/tool_smoke.py
  - scripts/intent_probe.py contracts:
  - matrix/feature-control.yaml owners:
  - team-maintainer ---
## ADDED Requirements
### Requirement: setMode SHALL 互斥写入指定模式
#### Scenario: 切换到模式A（正向）
- GIVEN 总开关 enabled=true, capabilities 包含 modeA
- WHEN setMode("MODE_A")
- THEN 设备 API 对应字段写入，其余字段 false
- AND 返回文案包含 "已切换到模式A"
#### Scenario: 云台关时切模式（negative）
- GIVEN 设备总开关 enabled=false
- WHEN setMode("MODE_B")
- THEN 返回文案 "设备未开启，请先打开设备"
- AND 无功能模式写入请求
## MODIFIED Requirements
### Requirement: 设备状态查询 (Previously 只能查询开关状态，现在同时返回当前模式名)

matrix.yaml defines cases with multiple utterance variants, positive & negative cases, safe arguments vs. destructive actions, and explicit setup preconditions. Example excerpt:

schema_version: 1
suite: feature-control
cases:
- id: fc-set-mode-a
  intent: 切换到模式A
  utterances:
    - "模式A"
    - "模式A变体"
    - "模式A变体"
  expected:
    route: fast-path
    rule: mode_rule_a
    tool: device.setMode
    args: {mode: MODE_A}
    response_template: "已切换到模式A"
    latency_p95_ms: 800
    safe_args: {mode: MODE_A}
    destructive: false
- id: fc-switch-off-negative
  setup: {deviceSwitch: false}
  utterances: ["切到模式B"]
  expected:
    response_contains: "设备未开启"
    destructive: false

_thresholds.yaml centralizes acceptance thresholds so that any change to a value automatically propagates to all specs and CI checks:

latency:
  fast-path:
    p50_ms: 1500
    p95_ms: 2000
skill:
  p95_ms: 5000
text:
  short_reply:
    max_codepoints: 20
hit_rate:
  fast-path: {min_pass: 0.95}
  demo: {min_pass: 1.00}
  tool_match: {min_pass: 0.90}

This avoids silent mismatches such as “spec says 2000 ms, CI checks 3000 ms”.

The change lifecycle currently shows nine states (archived, in_progress, draft) for items like verification-baseline, feature-control, demo-readiness, etc., illustrating how each change progresses through verification, archiving, and dependency resolution.

Harness Engineering with OpenSpec

Harness engineering is an AI‑centred method that constrains AI behaviour through five modules:

Identity – defined in openspec/AGENTS.md; specifies the AI’s role and enforces that every change must answer “which report line triggered this change?”.

Rules – enforced via spec frontmatter and _thresholds.yaml; binds verification scripts, mandates owners, and centralizes numeric thresholds.

Skills – encapsulate complex actions as repeatable atomic operations. Existing skill /spec-breakdown turns natural‑language requirements into a full change skeleton.

Context – the openspec/specs/ directory serves as structured, versioned project memory that is machine‑readable (YAML frontmatter + GIVEN/WHEN/THEN) and more reliable than README/Wiki.

Orchestration – the change workflow is a multi‑step orchestration where agents exchange structured files ( proposal, spec, matrix, reports) instead of relying on chat context, enabling deterministic hand‑offs.

These modules make AI a stable, repeatable collaborator: the AI reads AGENTS.md to know it must follow the SDD process, Rules enforce that no change proceeds without data‑backed justification, Skills provide reusable actions, Context supplies up‑to‑date system knowledge, and Orchestration coordinates the multi‑agent workflow.