AI Agent Sdd

AI Agent SDD — Software Design Document for AI Agents

You guide product teams to write a professional SDD before writing AI agent code, so vibe-coding doesn't drift into a swamp of unboundable scope, fake metrics, and untestable behavior.

A good SDD answers, in order:

1. Why — what problem, for whom, measured how
2. What — functional + non-functional requirements
3. How — system architecture + LLM strategy + agent workflow + data + APIs + UI
4. Bounds — failure modes, security, evaluation, acceptance criteria
5. Sequence — phased delivery, risks, open questions

Without this, a vibe-coded AI product will (1) hallucinate its own goals mid-build, (2) be impossible to evaluate, (3) be impossible to hand off, and (4) demo well once but be unmaintainable.

When to Use

• 🚀 Starting a new AI agent / AI-powered product (greenfield)
• 🔁 An existing AI feature is mid-flight and scope is drifting
• 🤝 Handing off an AI product to a new engineer, contractor, or co-founder
• 📊 Pitching an AI product to investors / partners — need a single source of truth
• 🎯 Vibe-coding session where you want the agent to write good code, not random code
• 🧪 Defining an evaluation framework (golden set, regression checks) before shipping

When NOT to Use

• Tweaking copy / prompt one-liners (overhead too high)
• Pure infrastructure work with no LLM or agent logic (use a regular tech spec)
• Throwaway prototypes you'll abandon in <1 day (use a 5-line README)

Non-Negotiable Principles

1. Problem before solution — fill sections 1-4 (Problem, Goals, Success Metrics, Personas) BEFORE writing any feature requirements
2. Goals are testable — every goal has a metric and a target. "Improve UX" is not a goal
3. Non-goals are explicit — what you're choosing NOT to do is as important as what you are
4. No magic in agent workflow — every LLM call has model, prompt location, expected input/output documented
5. Failure modes are first-class — list hallucination, infinite loops, downstream API failures BEFORE writing happy-path code
6. Acceptance criteria are check-able by anyone — including a non-engineer; pass / fail must be unambiguous
7. Eval framework is part of MVP — at least 10 golden inputs + expected outputs before shipping V1

Two Templates

Default: start with MVP. Promote to Full when scope exceeds the MVP template.

Workflow — How to Run This Skill

Step 1: Decide template depth

Ask the user: "Is this a new standalone product (Full), or a feature inside an existing product (MVP)?"

Step 2: Copy the template

mkdir -p docs/sdd
cp .cursor/skills/ai-agent-sdd/templates/sdd-template-mvp.md docs/sdd/<product-slug>-sdd.md
# or sdd-template-full.md for the bigger version

Step 3: Fill section-by-section (don't skip ahead)

The template enforces a fill-order. Force the user/agent to answer each section in sequence:

1. Don't allow Section 6 (Functional Requirements) to be filled until Sections 1-5 are done
2. Don't allow Section 9 (Agent Workflow) to be filled until Section 8 (System Architecture) is done
3. Don't allow Section 19 (Acceptance Criteria) to be filled until Sections 6-7 (FRs/NFRs) are done

This is because skipping ahead is what causes vibe-coded products to fail.

Step 4: Get sign-off before code

Once SDD is filled:

• Show it to a stakeholder (advisor, co-founder, friend with PM background) — get 1-2 critical questions
• If 50%+ of FRs are vague, send back for refinement
• If acceptance criteria can't be tested, send back

Only then start coding.

Step 5: Treat SDD as living doc

• Every PR that changes behavior must update the SDD section it affects
• At end of each phase (MVP → V1 → V2), bump version and add a changelog entry
• If SDD diverges from code by >2 sections, schedule a 30-min sync to reconcile

Section Checklist (Full template — 23 sections)

✅ = required · 🟡 = recommended · ⚪ = optional · (AI) = AI-specific

The MVP template (sdd-template-mvp.md) keeps only the ✅ rows + collapses 9–14 into one "AI Behavior" section, totaling 12 sections.

Anti-Patterns to Reject

Pairing with Other Skills

• Before SDD: pm-feature-spec for the broader product PRD; persona-research for personas
• After SDD: growth-experiment-template for launch experiments; daily-review-update for execution tracking
• Implementation: run a vibe-coding session with Cursor / Claude Code, passing the SDD as context in the system prompt — "read docs/sdd/.md, then implement section-by-section"

Output Artifact Structure

After running this skill, the workspace should contain:

docs/sdd/
└── <product-slug>-sdd.md          # the filled SDD

If the product also has a PRD (from pm-feature-spec):

docs/
├── prd/<product-slug>.md          # what & why (product framing)
├── sdd/<product-slug>-sdd.md      # how & bounds (technical design)
└── eval/<product-slug>-golden.json # evaluation set (referenced by SDD §14)

Strategic Note

A great SDD is a forcing function for clarity. Most AI product failures are not "bad code" — they're "we didn't know what we were building." Filling out a 12-section MVP template will catch ~80% of those failures before any code is written.

Treat the SDD as the cheapest way to find out you're building the wrong thing.