人工智能代理
- 作者仓库星标 0
- 作者仓库 skills-registry
- 领域
- 设计与多媒体
- 作者声明的智能体
- 未找到明确声明;不据此推断已兼容或已测试
- 静态检查
- 88 / 100 · 启发式扫描,不代表运行安全
- 运行环境证据
- 未执行;当前没有隔离运行测试证据
- 作者 / 版本 / 许可证
- @tomevault-io · 未声明许可证
- 上下文用量评级
- 低消耗
- 接入复杂程度
- 需简单配置
- 是否需要外部接口密钥
- 不需要
- 兼容的系统
- 未声明(默认跨平台)
- 运行环境要求
- 未检出明确要求
- 检测到的文件与系统行为
-
- 只读
- 允许写入 / 修改
- 命令执行
- 网络行为
- 仅限本地
- 安装命令数
- 无(仅作为资料)
需要注意: 未声明工具权限范围;实际权限由运行环境决定。
docs/sdd/
└── <product-slug>-sdd.md # the filled SDD
第 1 步:确定模板深度
询问用户:“这是一个新的独立产品(完整版),还是现有产品中的一个功能(MVP)?”
第三步:逐节填写(不要跳过)
该模板强制执行填充顺序。强制用户/代理按顺序回答每个部分: 在完成第 1-5 部分之前,不允许填写第 6 部分(功能要求) 在完成第 8 部分(系统架构)之前,不允许填写第 9 部分(代理工作流程) 在完成第 6-7 部分(FR/NFR)之前,不允许填写第 19 部分(验收标准) 这是因为向前跳过会导致 vivi 编码产品失败。
第 4 步:在编码之前获得签核
SDD 填满后: 向利益相关者(顾问、联合创始人、有 PM 背景的朋友)展示 — 提出 1-2 个关键问题 如果 50% 以上的 FR 含糊不清,则发回进行完善 如果验收标准无法测试,则发回 然后才开始编码。
第 5 步:将 SDD 视为活生生的医生
每个改变行为的 PR 都必须更新它影响的 SDD 部分 在每个阶段结束时 (MVP → V1 → V2),修改版本并添加变更日志条目 如果 SDD 与代码的偏差超过 2 个部分,请安排 30 分钟的同步来协调
# 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.
---
> Source: [Celina-create/X-Studio](https://github.com/Celina-create/X-Studio) — distributed by [TomeVault](https://tomevault.io).
<!-- tomevault:4.0:skill_md:2026-05-23 -->
章节与文件索引
按说明文件中的顺序排列。
何时使用
何时不使用
不容谈判的原则
两个模板
第 1 步:确定模板深度
文件/命令 -> templates/sdd-template-mvp.md · templates/sdd-template-full.md · sdd-template-mvp.md · pm-feature-spec · persona-research · growth-experiment-template · daily-review-update
内容校验值 -> 32f079548cf7
当前原文的自动摘译,尚未人工审校。
何时使用
🚀 启动新的人工智能代理/人工智能驱动的产品(未开发) 🔁 现有人工智能功能正在开发中,范围正在变化 🤝 将人工智能产品移交给新工程师、承包商或联合创始人 📊 向投资者/合作伙伴推销人工智能产品 - 需要单一事实来源 🎯 Vibe 编码会话,您希望代理编写良好的代码,而不是随机代码
何时不使用
调整副本/提示单行(开销太高) 纯基础设施工作,没有 LLM 或代理逻辑(使用常规技术规范) 您将在 1 天内放弃的一次性原型(使用 5 行自述文件)
不容谈判的原则
解决问题之前的问题 — 在编写任何功能需求之前填写第 1-4 部分(问题、目标、成功指标、角色) 目标是可测试的 — 每个目标都有一个指标和目标。 “改善用户体验”不是目标 非目标是明确的 — 您选择不做的事情与您所做的事情一样重要 代理工作流程中没有魔法 — 每个 LLM 调用都有模型、提示位置、预期输入/输出记录
两个模板
模板 · 部分 · 填充时间 · 使用时
templates/sdd-template-mvp.md· 12 ·30 分钟 · 小功能,单一代理,预先存在的基础设施;或者你需要在几个小时内开始编码2小时·新产品,多代理系统,将被移交,将被推介,将被开源默认:从MVP开始。当范围超出 MVP 模板时升级为完整。templates/sdd-template-full.md·23·第 1 步:确定模板深度
询问用户:“这是一个新的独立产品(完整),还是现有产品中的一个功能(MVP)?”