# Acceptance Criteria IDs (ACIDs)

Acceptance Criteria IDs are short stable identifiers attached to each item in a list of acceptance criteria — `AUTH-1`, `AUTH-2-1`, `ENG-3` — used as bidirectional anchors between the spec and the code, tests, and review notes that satisfy them. Coined in [[specsmaxxing|the specsmaxxing post on acai.sh]], where the convention emerged when a subagent unilaterally started numbering requirements and referencing them in inline comments.

The pattern is older than the name — Gherkin scenarios, EARS-formatted requirements, and aerospace-style traceability matrices all produce something like ACIDs. What's new in 2026 is using them as the pivot point between LLM-generated code and a human-curated spec, with tooling that tracks "acceptance coverage" the way coverage tools track "test coverage."

## The shape

A spec organized by ACIDs has three properties:

1. **Stable numbering.** Each requirement gets an ID that doesn't change when other requirements are added, reordered, or removed. Components or sections (`AUTH`, `BILLING`, `ENG`) namespace them; numbers within a section are append-only.
2. **Code-side references.** Implementations cite the ACID they satisfy, typically as inline comments — `// AUTH-1` — though anything the tooling can grep for works.
3. **State tracking.** Each ACID has a status: drafted, assigned, in-progress, completed, accepted, rejected, deprecated. State lives outside the source file (the acai.sh dashboard is one design; a JSON sidecar or git-notes layer would be another).

Hierarchical sub-IDs (`AUTH-2-1`) handle "this requirement has a clarifying sub-requirement." Adjacent metadata (`AUTH-2-note`) carries cross-references and design rationale without polluting the requirement text.

## Why it works for LLM-assisted code

Three properties matter once an agent is writing the implementation:

- **Reviewability shifts from files to requirements.** Instead of reading a 600-line PR file-by-file, you check off ACIDs and ask "is the code that claims to satisfy `AUTH-3` actually doing that?" The reviewer's mental model and the reviewable artifact match.
- **Re-prompting becomes mechanical.** "Implement `AUTH-2-1`" is a tighter prompt than "make sure tokens are validated correctly." The spec is the prompt; iteration loops back to the spec rather than to free-form follow-ups in chat.
- **Coverage gaps are visible.** ACIDs without code references are unimplemented; ACIDs without test references are unverified. This is a cheap, deterministic check that doesn't depend on the LLM grading itself.

The tight coupling between spec and code that ACIDs introduce is the thing the [[specsmaxxing|specsmaxxing author]] initially flinched at — every spec change forces a code refactor. The reframe is that this is the discipline you wanted: if the spec changes and the code doesn't follow, the spec was just decoration.

## Why it works for humans too

ACIDs predate LLMs by decades. Aerospace and medical-device development use **requirement traceability** — every line of safety-critical code traces back to a numbered requirement, and audit tooling enforces it. ISO 26262 (automotive), DO-178C (avionics), IEC 62304 (medical software) all assume this convention. The novelty in the LLM-coding context isn't the technique; it's that the cost of maintaining the traceability has collapsed because the agent does the bookkeeping.

## Tradeoffs the [[specsmaxxing]] piece calls out

- **Re-alignment cost.** Renaming an ACID or reordering numbering breaks all code references. `deprecated` and `replaced_by` flags inside the spec are one mitigation; treating ACIDs as never-reused (append-only) is another.
- **Granularity discipline.** Specs at "API endpoint accepts JSON" granularity produce useful ACIDs; specs at "button is blue" granularity produce noise. The acai.sh advice is to keep ACIDs to behavior and constraints — leave UI nail-polish out.
- **Format lock-in.** Once code comments reference ACIDs by ID, the spec format becomes load-bearing. Switching from `feature.yaml` to OpenSpec or EARS without a migration script orphans every reference.

## Adjacent conventions

- **EARS syntax** (Easy Approach to Requirements Syntax) — a constrained natural-language format ("When `<trigger>`, the `<system>` shall `<response>`"). Compatible with ACIDs but separate; EARS is about *how* to phrase a requirement, ACIDs are about *how to address* one.
- **Gherkin** (`Given/When/Then`) — same shape: addressable scenarios that test code references back to. ACIDs generalize this past the test-frame-only context.
- **Issue tracker IDs** — `JIRA-1234` referenced in commit messages is the same idea at a coarser granularity. ACIDs operate inside a single feature spec rather than across a whole project.
- **TODO comments with ticket links** — informal, lossy version of the same pattern. ACIDs differ in being part of the spec rather than annotations on code.

## Tools in this space

- [[toolbox/acai]] — `feature.yaml` + CLI + dashboard; the canonical implementation as of 2026.
- GitHub SpecKit — different shape (vibe-coding-with-prompts), no ACID concept.
- OpenSpec, Kiro, Traycer.ai — covered in the [[specsmaxxing]] comparison; varying degrees of structure.

## See also

- [[specsmaxxing]] — origin of the term and the full argument
- [[toolbox/acai]] — the toolkit
- [[clean-code-coding-agents]] — adjacent argument that code structure should be optimized for agent navigation
- [[ai-assisted-workflow]] — Barbero's spec-before-code workflow, compatible
- [[building-syntaqlite-ai]] — case study where lack of stable spec discipline produced rework
- [[agent-built-deterministic-tools]] — sibling pattern: stable artifacts that agents reference instead of re-interpreting from scratch
- [[1password-agentic-refactoring]] — production-scale example of the same spec-bounded-agent shape