# AI Agent Sdd

> AI Agent SDD — Software Design Document for AI Agents

- Skill: `celina-create/ai-agent-sdd` (Agent Skill, multi-file: 5 files)
- Install (CLI): `npx skillmds@latest add celina-create/ai-agent-sdd`
- Raw SKILL.md: https://api.skillmd.com/api/skills/celina-create/ai-agent-sdd/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: AI & ML
- Author: Celina-create (https://skillmd.com/u/celina-create)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/celina-create/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

| Template | Sections | Fill time | Use when |
|---|---|---|---|
| `templates/sdd-template-mvp.md` | **12** | ~30 min | Small feature, single agent, pre-existing infra; or you need to start coding within hours |
| `templates/sdd-template-full.md` | **23** | ~2 hours | New product, multi-agent system, will be handed off, will be pitched, will be open-sourced |

**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
```bash
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)

| # | Section | Required? | What it answers |
|---|---|---|---|
| 0 | Doc Metadata | ✅ | version, owner, status, last_updated, reviewers |
| 1 | TL;DR | ✅ | 3-sentence elevator pitch |
| 2 | Problem & Goals | ✅ | what's broken, what we want to achieve, what we won't try |
| 3 | Success Metrics | ✅ | primary metric + guardrails + targets |
| 4 | Personas | ✅ | primary + secondary user roles |
| 5 | User Journeys | ✅ | 2-3 narrative flows |
| 6 | Functional Requirements | ✅ | FR-1, FR-2 ... with ID, priority, acceptance |
| 7 | Non-Functional Requirements | 🟡 | latency, throughput, accuracy, cost ceiling |
| 8 | System Architecture | ✅ | high-level diagram + component list |
| 9 | LLM Strategy | ✅ (AI) | model selection, fallback chain, prompt files location |
| 10 | Agent Workflow | ✅ (AI) | state machine / DAG of steps |
| 11 | Tools / Function Calls | ✅ (AI) | list of tools agent can invoke |
| 12 | Memory Strategy | 🟡 (AI) | none / short-term / long-term |
| 13 | Human-in-the-Loop | 🟡 (AI) | where humans intervene |
| 14 | Evaluation Framework | ✅ (AI) | golden set, eval cadence, regression checks |
| 15 | Data Model | ✅ | entities, relationships, schema sketch |
| 16 | API Design | ✅ | endpoint table |
| 17 | UI / Page Structure | 🟡 | wireframe sketch, route map |
| 18 | Tech Stack & Rationale | 🟡 | why each choice |
| 19 | Deployment Topology | 🟡 | where each component runs |
| 20 | Observability | 🟡 | metrics, logs, traces, alerts |
| 21 | Cost Model | 🟡 | LLM tokens, infra, third-party APIs |
| 22 | Security & Privacy | ✅ | authn/authz, data handling, secrets |
| 23 | Failure Modes | ✅ | hallucination, infinite loop, downstream failure |
| 24 | Acceptance Criteria | ✅ | testable, verifiable |
| 25 | Phased Delivery | 🟡 | MVP → V1 → V2 |
| 26 | Open Questions & Risks | 🟡 | what's unresolved |
| 27 | Glossary | ⚪ | domain terms |
| 28 | Changelog | ⚪ | v0.1, v0.2 ... |

✅ = 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

| Anti-pattern | Why it kills the SDD |
|---|---|
| "We'll add metrics later" | If you can't measure success, you can't ship |
| "The agent will figure it out" | LLM behavior must be specified, not hoped for |
| "Acceptance criteria: works as expected" | Untestable = won't be tested = silent failure in prod |
| "We'll handle errors gracefully" | List actual failure modes; "gracefully" is meaningless |
| Copying every section header but leaving content blank | A blank section is worse than no section |
| Writing SDD AFTER code is built | The doc loses its point — it's now just documentation, not design |

---

## 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/<product>.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.