Advanced OpenSpec: Turning Requirements into Contracts to Prevent Drift – Standardized Templates for AI‑Era Documentation

Introduction

A team used OpenSpec to describe an insurance‑form page with a single line: “Insurance fields follow Figure 4, keep it consistent.” After delivery they discovered three missing fields, a wrong date‑picker type, and unclear validation rules, costing one day of rework and another day of review.

OpenSpec itself is fine; the problem is insufficient document granularity that leaves too much freedom for AI and humans.

Why Drift Happens Even When Using OpenSpec

The root cause is that a picture or table is only an expression, not a contract. When a spec says “follow Figure 1/4”, the following issues arise:

Only images are referenced → fields are omitted, controls are mis‑chosen, validation is missing.

Implementation constraints are not fixed → AI picks a generic solution and deviates.

Open Questions remain open → developers make default assumptions that later get rejected.

Switch‑type clearing strategies are undefined → the most frequent source of rework.

Three Core Principles

Principle 1: Evidence > Claims

Any claim of “completed” must be backed by concrete evidence such as runnable commands ( build/lint/test), screenshots, or recordings. Empty assertions are prohibited.

Principle 2: Open Questions Are Hard Gates

All uncertain items—field names, clearing strategies, copy, permissions—must be explicitly listed in the documentation and kept as unfinished items in tasks.md. Declaring “requirements aligned” before closing them is forbidden.

Principle 3: “Follow the Picture” Is Not Enough – Use a Field Matrix

Whenever the phrase “follow the picture” appears, a detailed field‑matrix must accompany it without exception.

Three Common Pitfalls and Correct Practices

Pitfall 1: Saying “follow the picture” Without a Field List

Incorrect: “Insurance fields follow Figure 4, keep it consistent.”

Correct: “Insurance fields must match field-matrix.md . Any missing field, wrong control, or mismatched validation is considered incomplete.”

Example matrix (excerpt):

# Field Matrix: <module>
| Field | Control | Required | Default | Limit |
|---|---|---|---|---|
| 标的名称 | Input | ✅ | — | max 50 |
| 标的类型 | Select | ✅ | “房产” | enum: 房产/车辆/其他 |
| 车辆品牌 | Input | 条件 | — | max 30 |
| 购置日期 | DatePicker | ✅ | — | ≤ today |
| 购置价格 | InputNumber | ✅ | — | min 0, precision 0.01 |
| ... | ... | ... | ... | ... |

Pitfall 2: Not Fixing Implementation Constraints

Incorrect: “Province/City/District uses a cascade selector.”

Correct: “Province/City/District must use area-data as the data source and the <AreaCascader /> component. Creating a custom data source or switching to a plain Input is prohibited.”

Pitfall 3: No Strategy for Clearing Fields When Switching Types

Scenario: User changes “Property” to “Vehicle”. Should the previously entered area be kept?

Incorrect: “After switching, show the corresponding fields.”

Correct: “After switching, hide fields exclusive to the previous type and do not submit them. If the user switches back, restore the original values. Acceptance test: switch → save → refresh → verify no residual fields.”

Standardized Templates (Four Files)

spec.md

– Main requirement document. field-matrix.md – Detailed field contract (the matrix above). design.md – Fixed implementation constraints. tasks.md – Gates, tasks, and evidence checklist.

Each file has a prescribed structure; for example, spec.md starts with:

# 需求/规格：<功能名>
## 0. TL;DR（30 秒读懂）
- 解决什么问题：
- 做完算成功的标准：
- 不做什么（边界）：
## 1. 背景（Why）
- 现状：
- 痛点：
- 业务价值：
... (subsequent sections omitted for brevity)

Four‑Step Fill‑In Workflow

Write field-matrix.md first – translate designs or tables into a matrix; this catches the most omissions.

Write design.md next – lock component, data‑source, clearing, and submission strategies.

Write spec.md – reference the matrix and define acceptance scenarios.

Finally write tasks.md – list open questions as gates and enumerate evidence commands such as openspec validate <change-id> --strict, pnpm run build, and pnpm run lint.

Real‑World Outcome

Applying the matrix to the insurance form replaced the vague “follow Figure 4” with a concrete list of 11 fields, each with control type, required flag, visibility, validation, and error copy. The result: zero missing fields, zero wrong controls, and zero review rework.

Final Rule

Never allow “follow the picture” in a requirement; always accompany it with a field matrix, fixed design constraints, and verifiable evidence so that the document becomes a true quality gate rather than a loose description.