ai agent sdd

Design Community

Skill notes

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

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

Problem before solution — fill sections 1-4 (Problem, Goals, Success Metrics, Personas) BEFORE writing any feature requirements Goals are testable — every goal has a metric and a target. "Improve UX" is not a goal Non-goals are explicit — what you're choosing NOT to do is as important as what you are No magic in agent workflow — every LLM call has model, prompt location, expected input/output documented

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.

Step 1: Decide template depth

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

Fluxly profile Runtime and permissions are inferred by Fluxly static checks, not author declarations or runtime test results.
Domain
Design
Author-declared agents
No explicit declaration found; this is not inferred or tested compatibility
Static check
88 / 100 · heuristic scan, not runtime safety proof
Runtime evidence
Not run; no isolated runtime test evidence is currently recorded
Author / version / license
@tomevault-io · no license declared
Token usage
Lean
Setup complexity
Guided setup
External API key
Not required
Operating systems
Unspecified (assume cross-platform)
Runtime requirements
No explicit requirements detected
Detected file/system behavior
  • Read-only
  • Write / modify
  • Shell exec
Network behavior
Local-only
Install commands
None (reference only)

Heads up: Tool permissions are not declared; actual access depends on the runtime.

01
Step 1: Decide template depth

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

02
Step 2: Copy the template

Step 2: Copy the template

03
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: Don't allow Section 6 (Functional Requirements) to be filled until Sections 1-5 are done Don't allow Section 9 (Agent Workflow) to be filled until Section 8 (System Architecture) is done 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.

04
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.

05
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

Discussion

Powered by GitHub Discussions. Sign in with GitHub to comment, react, or subscribe.