IntentSpec:
The Open Standard for
Spec-Driven Development.
Functional Guardrails for your AI Agents. Prevent architectural drift, wrong dependencies, and hallucinated APIs.
---
id: "INT-EXPORT-JSON-001"
objective: "Allow users to export filtered data to JSON"
outcomes:
- "User clicks Export → JSON file downloads to device"
- "Export contains only the currently filtered dataset"
- "No PII fields are included in the output"
constraints:
- "Must run client-side only (no server round-trip)"
- "File size must not exceed 10MB"
edgeCases:
- scenario: "Empty dataset"
expected: "Show toast: 'Nothing to export' — no file created"
- scenario: "10k+ rows"
expected: "Stream to file, show progress indicator"
healthMetrics:
- "Page load time must not increase"
- "Existing CSV export must continue to work"
---The Problem: Probabilistic Engineering
You prompt an agent. It works. Two weeks later, another developer prompts it differently, and it breaks. "Vibe coding" is not engineering. Prompts are ephemeral; they don't survive context switching.
The Solution: Functional Guardrails
IntentSpec is a structured contract that lives in your repo. It tells any agent (Cursor, Windsurf, Augment) exactly what "Done" looks like before it writes a single line of code.
How It Works
Three steps to go from vibe coding to spec-driven development.
Write an intent.md
Define the objective, expected outcomes, constraints, and edge cases in a Markdown file with YAML frontmatter. Commit it alongside your code.
your-repo/ ├── src/ ├── intent.md ← your spec └── package.json
Point your AI agent to it
Reference the spec in your agent's context. One line is all it takes — the agent now knows exactly what "Done" means.
# CLAUDE.md / .cursorrules Read intent.md before implementing any feature.
Validate in CI
Add the GitHub Action to enforce schema compliance on every PR. Prevent drift before it reaches main.
- uses: JanneL/validate-
intentspec-action@v1
with:
file: intent.mdIntentSpec vs. AGENTS.md
| Feature | AGENTS.md | IntentSpec |
|---|---|---|
| Format | Unstructured Text | Markdown + YAML + JSON Schema |
| Validation | None (Vibe Check) | Automated (CI/CD Enforceable) |
| Goal | Context Injection | Application Logic Standard |
| Testability | Low | High (Deterministic) |
Format Agnostic
Works with any LLM or Agent tool. It's just context.
Human Writable
It's just Markdown with frontmatter. No proprietary lock-in.
The Application Logic Standard
Claude Code
Add intent.md to CLAUDE.md or context.
Cursor / Windsurf
Add intent.md to context to keep agents on track.
Augment
Use IntentSpecs as the portable source of truth.
GitHub Copilot
Reference the spec in your copilot instructions.
Any LLM
Paste the spec to strictly define "Done".
Start Specifying Today
You can write IntentSpecs by hand, or use the visual editor reference implementation.