Frontend · Frontend Engineering · Code Standards

OpenSpec: The Markdown Spec Layer That Makes AI-Generated Code Safe to Ship

By miss · Nov 10, 2026

Read original on juejin.cn ↗ Google Translate ↗ Alt translation

Teams already face the cost of AI code that nobody trusts enough to ship; OpenSpec shifts review from reading diffs to checking spec deltas, so a legacy codebase can accumulate a source of truth that survives session resets, staff turnover, and context-window compression. For anyone running AI coders on existing projects, this is a concrete workflow for making "done" explicit and auditable before a line of code is written.

Summary

AI coding tools now write code faster than anyone can review it, and the bottleneck has moved from writing to alignment and acceptance. OpenSpec, an open-source framework from Fission-AI, addresses this by adding a specification layer on top of 30+ AI coding tools like Claude Code, Cursor, and Copilot. All artifacts are pure Markdown in Git, so they are naturally diffable and reviewable, with no private syntax, database, or server.

The workflow is a five-step loop: Explore, Propose, Review, Apply, Archive. In Explore, AI reads code and lays out options without writing anything. Propose generates a change folder with four artifacts: proposal.md (why/what), specs/ (what counts as done), design.md (how to build), and tasks.md (checklist). Review happens on text, not code, so changes cost minutes instead of hours. Apply works from a clean session and tracks progress via task checkboxes, and Archive merges delta specs back into the main spec, keeping the spec synchronized with code.

OpenSpec is designed for brownfield projects: a dual-directory model lets old codebases gradually transcribe behavior into specs without a big-bang rewrite. The framework deliberately avoids phase gates and heavy process, betting that a fluid, low-friction approach will outlast stricter alternatives in real projects. It also plays well with code map and skill tools, forming a pipeline where maps show where to touch, specs define when it's right, and archive keeps the understanding current.

Takeaways

— OpenSpec supports 30+ AI coding tools via generated skills, commands, and AGENTS.md, with no IDE or model lock-in.

— The core loop is Explore → Propose → Review → Apply → Archive; the critical gate is that no business code is written before the plan is reviewed.

— Each change produces four artifacts: proposal.md (why/what), specs/ (behavioral contract), design.md (technical approach), and tasks.md (checklist with checkboxes).

— Spec delta files support ADDED, MODIFIED, REMOVED, and RENAMED operations; MODIFIED must include the full old Requirement block or archiving loses historical scenarios.

— Capabilities should be named after persistent system behaviors (e.g., user-auth) rather than tasks (e.g., add-login-button), and pure refactors can set skip_specs: true to avoid forced requirements.

— For team adoption, commit the code and change folder together in a PR, run `openspec validate --strict` in CI, and use config.yaml to inject team rules like mandatory test tasks.

— The CLI offers commands like `openspec list --specs` to inventory existing capabilities and `openspec schema fork` to derive custom schemas when config.yaml isn't enough.

— A 2026-era version of OpenSpec is noted; the article points to the README for current command syntax and artifact formats.

Conclusions

OpenSpec's design philosophy makes a bet that the biggest risk for spec frameworks is team abandonment from over-engineering, not weakness of enforcement; that's why it skips phase gates and stays fluid.

By separating "what counts as done" (spec delta) from "how to build it" (design/tasks), OpenSpec converts code review into a contract check rather than an implementation audit, which is a practical answer to the trust problem AI coding creates.

The framework's value compounds on brownfield projects: each archived change becomes part of a living spec that new developers can read, directly countering the knowledge loss that chat-based requirements create.

Concepts & terms

Spec-Driven Development (SDD)

A development approach where system behavior is written as structured, reviewable Markdown contracts before code is written. The spec is the authoritative agreement; code is just one implementation of it, and AI and humans align against the spec.

spec drift

The situation where code moves forward while the shared understanding of what the system does stays stale. It happens when requirements live in chat logs, no single source of truth exists, and review degenerates into checking for errors rather than verifying behavior.

delta spec

An incremental specification that describes only the change relative to the current main spec, using operations like ADDED, MODIFIED, REMOVED, and RENAMED. Delta specs are merged into the main spec during archiving, keeping the source of truth current.

Source: juejin.cn ↗ Google Translate ↗ Backup ↗