Spec-driven development

Spec-driven development is the habit of writing a short, testable contract before autonomous coding agents (or offshore contractors) touch your repository. The spec names the user-visible outcome, the verify commands that must pass, and what must remain untouched. PunkSolid treats specs as merge law—not as optional preamble in a chat window. This guide sits in the learn cluster beside AI agents explained and Claude Code vs Cursor.

Why specs matter more with agents

Language models excel at plausible code. They do not automatically inherit your roadmap, compliance boundaries, or canonical URL policy. Without a spec, reviewers debate whether a refactor “felt helpful” instead of checking a checklist. That ambiguity shows up in rescue work: silent redirect edits, duplicate sitemaps, and lockfile churn.

A written spec turns review into pass/fail. Did pnpm test pass? Did redirects match the signed inventory? Did the agent stay out of infra/? Those questions do not depend on which vendor produced the diff.

Minimum sections in every agent spec

PunkSolid uses the same skeleton on migrations, CMS seeds, and feature slices:

1. Problem — What a user or operator can do after the change that they could not do before. One paragraph maximum.
2. Constraints — Stack, style, performance, regulatory copy, branding, and deployment model. Link to ADRs instead of pasting architecture essays.
3. Acceptance — Exact commands: unit tests, typecheck, content validate, link scan, build. Mirror what CI already runs.
4. Out of scope — Directories and concerns the agent must not touch: payments, DNS, unrelated packages, dependency major bumps.
5. Review — Who signs off, whether a second human must read regulated HTML, and whether merge waits on staging.

Optional but valuable: Rollback — how to revert if acceptance passes locally but staging fails (feature flag, revert commit, DNS hold).

Spec vs ticket vs AGENTS.md

Artifact	Audience	Lifetime
Ticket / issue	Humans prioritizing work	Closes when shipped
Spec (this guide)	Agent + reviewers for one slice	Archived with the PR
AGENTS.md	Every future agent session	Living repo doc

AGENTS.md belongs at repository root: install steps, verify commands, forbidden paths. A spec is task-specific. Do not paste a multi-day feature spec into AGENTS.md; link the ticket instead.

Cursor rules encode habits (git remotes, no force-push). Rules steer style; specs bound intent for a single branch.

Acceptance commands must be real

“If tests pass” is not acceptance. Name filters: pnpm --filter @scope/web test, pnpm validate, site build <id> --pull. The command should be the same one you would run before asking a human reviewer for a LGTM.

On PunkSolid monorepos, content agents run package validators before claiming a page is ready for reviewed. Client apps mirror that pattern so Claude Code and Cursor sessions cannot shortcut with a verbal “all good.”

Scoping paths and privileges

Agents with shell access can touch more than you intended. The spec should list allowed path globs when the task is narrow: apps/ai-network/src/content/pages/punksolid/** only, for example. Pair that list with deny rules in AGENTS.md for infra/, commerce webhooks, and secret stores.

Least privilege beats heroic prompting. If the task is “rewrite five guides,” the spec should not invite dependency updates or deploy script edits.

Spec-driven agentic coding workflow

A practical loop for mixed Cursor and Claude Code teams:

1. Human drafts or tightens the spec in the ticket.
2. Implementer opens a branch; Cursor handles multi-file template work with visual diffs.
3. Optional: Claude Code runs a bounded terminal batch (rename across tree) when the spec lists exact globs.
4. Implementer runs acceptance commands locally; pastes output or CI link—not paraphrase.
5. Reviewer checks diff against out of scope and regulated copy; merges only on green CI.

Neither tool replaces step five on production paths. See methodology for how PunkSolid gates client delivery.

When specs fail (and how to recover)

Common failures: the spec was vague, acceptance commands were missing from CI, or the agent “fixed” unrelated lint. Recovery is revert or narrow—not an argument in chat.

If you hire PunkSolid for AI code review after a vibe-coded sprint, the first deliverable is often retroactive specs for the slices you still want to keep. That documents intent before the next agent session.

Specs on migrations and SEO work

Website migrations need specs with URL inventory attachment: old path, new path, redirect code, canonical owner. Agents should not invent redirects from sitemap guesses. The website migration SEO checklist lists structural checks that belong in acceptance.

For large content moves, acceptance includes validator output (duplicate keywords, orphan links) not just HTML build green.

Specs for non-engineers

Product and content leads can write the problem and review sections; engineering fills constraints and acceptance. Plain-language problem statements reduce agents hallucinating features you did not request.

Regulated industries: the spec should flag which pages need medical, legal, or financial sign-off. Agents may draft; humans publish.

Anti-patterns we decline

• “Implement what we discussed in Slack” with no written acceptance.
• Specs that grow unbounded mid-session without re-approval.
• Letting the agent update the spec and code in one unreviewed burst.
• Skipping out-of-scope lists on repos with payments or HIPAA-shaped content.

Working with PunkSolid

Website development and Claude Code development engagements start from a spec-shaped statement of work: deliverables, verify commands, and ownership of hosting. If you already use agents internally, we can tighten your AGENTS.md and rules so specs stay short.

Continue with What is agentic AI? for vocabulary, or AI coding agents compared if you are still choosing tooling.