Workflow design：为 AI 设计工作方式，而不是期待它自动靠谱
Page card
- Part：Part 2 / Workflow 设计
- 适用角色：开发、QA，也适合产品和设计理解协作边界
- 使用场景：把个人 AI 用法升级成团队级 workflow 和 spec contract
- 输出物：
input → execution → verification → archive的团队工作流
Related jumps
Back to AI Workflow Sharing。相邻主题：AI Harness 101 · Glossary - AI Workflow 术语表 · Agentic execution · Knowledge capture
Summary
重点：AI 输出质量不是只由模型决定，也由 workflow 和 prompt contract 决定。
团队要做的不是期待 AI 自动靠谱，而是为 AI 设计清楚的角色、输入、约束和输出格式。
适用场景
- 团队推广 AI 使用规范
- 复杂任务交给 agent
- 多工具协作
- Spec-driven / AI-native workflow
- 新人学习 AI 工作方式
工作方式
- 给 AI 明确角色：
researcher、reviewer、executor、writer，不要混在一起。 - 给 AI 明确输入：
repo、PR、URL、日志、目标受众、成功标准。 - 给 AI 明确约束：不要扩大 scope、不要重构无关代码、必须引用证据、必须验证。
- 给 AI 明确输出格式：
findings、plan、patch summary、decision log、comment draft。 - 对团队级 workflow，用 spec 或 checklist 作为共享契约，而不是依赖个人 prompt 记忆。
从个人技巧到团队 workflow
AI workflow escalation 解决的是“单个任务怎么分流”;Workflow design 解决的是“团队如何把这套分流方式变成可复用机制”。
- 输入标准：什么信息必须给 AI,例如真实对象、背景、owner boundary、成功标准。
- 角色分工：AI 负责澄清、分析、执行、验证中的哪些环节;人负责哪些判断。
- 升级规则：什么时候轻量处理,什么时候进入 AI workflow escalation,什么时候进入 OpenSpec,什么时候可以交给 executor。
- 验证要求：什么结果才算完成,哪些必须经过人工确认。
- 沉淀位置：经验应该进入 Glossary、
AGENTS.md/CLAUDE.md、GOTCHAS.md、ADR、OpenSpec 还是 Notion。
团队用 AI 不能只靠每个人自己的 prompt 经验。个人 prompt 很难 review,也很难复用;换一个工具、换一个 agent,很多隐含规则就丢了。更稳的是设计 workflow：输入是什么,AI 扮演什么角色,能用什么上下文,有哪些约束,输出格式是什么,怎么验证,最后沉淀到哪里。
前面的 escalation 是任务级判断;这里的 workflow design 是团队级机制。也就是说,我们不只是要知道某次任务怎么做,还要把这套判断方式沉淀成大家都能复用的 source of truth。
Prompt contract 模板
Role:
Input:
Goal:
Constraints:
Output format:
Verification:
Stop condition:
面向开发同事的重点方向
重点案例：用 OpenSpec 把 spec 变成 delivery contract，是开发侧需要重点分享的方向。它的核心不是某个 FE 实现，而是如何把 spec 变成 AI-native development 的协作契约。
可以围绕这条链路展开：
PRD / prototype / design / Linear intent
→ Intake summary
→ OpenSpec change
→ SuperPowers brainstorm / plan / TDD / debug / verify
→ PR implementation + spec link + verification evidence
→ Archive into canonical specs
开发侧要强调的点：
Spec is source of truth, not prompt archive。OpenSpec定义 feature/change delivery contract。SuperPowers负责 agent execution discipline。AGENTS.md/CLAUDE.md负责长期 repo 规则。- ADR 只记录高门槛、可复用、难逆转的技术架构决策；可以用
precedent+reversibility cost判断是否值得写。 - Notion 适合讨论、草稿和协作，不是最终 spec source of truth。
可分享案例
- OpenSpec / SuperPowers /
AGENTS.md/ ADR / Notion 的责任边界。 - ADR via GitHub 的 proposal：为什么长期架构决策应使用 GitHub、Markdown、frontmatter 和 CI guardrails 管理，而不是只放在 Notion。
- PR checklist 先轻量试点，再考虑 CI enforcement。
- 用 acceptance scenarios 映射
Vitest、Playwright、typecheck、i18n check或 manual QA。
可复用规则
Spec 是 source of truth，不是 prompt archive。
- Agent context 要保持 hygiene，只给相关 active change、canonical spec、ADR 和 repo rules。
- Workflow gate 先轻量 pilot，再考虑强制化。
- 私人 workflow 可以作为输入，但团队输出必须是抽象后的可公开规则。
- 复杂任务不要只写 prompt，要设计
input → execution → verification → archive的完整链路。
References
- Spec-driven development with AI: Get started with a new open source toolkit — GitHub 对 Spec Kit 和 spec-driven development 的介绍，适合支撑“spec 让 AI coding 从 vibe coding 走向可预测结果”。
- github/spec-kit — Spec Kit 官方仓库，包含
specify、plan、tasks、implement等流程，适合作为开发侧 workflow 参考。 - Agent instruction standard — coding agents 的开放 instruction 文件格式，适合讨论不同 agent 之间是否需要通用约束标准。
- Model Context Protocol docs — MCP 官方文档，适合解释工具接入层面的行业标准化趋势。
- Agent Skills - Claude API Docs — 官方解释 skills 的按需加载和复用机制，适合回应“skill 真的有必要吗”。
- Spec-Driven Development: From Vibe Coding to Structured Development — 讨论从 vibe coding 走向 structured development 的实践趋势，可作为 spec-as-delivery-contract 的外部背景材料。
- Fission-AI/OpenSpec — OpenSpec 官方仓库，直接对应开发侧重点：用 lightweight spec layer 让团队在写代码前先对齐要构建什么。
- Spec-Driven Development as a Cure for AI Over-Editing — OpenSpec 讨论帖，适合支撑“spec 可以约束 AI 不要过度修改”的观点。
- ADR via GitHub — ADR proposal，适合支撑
ADR、source of truth、GitHub/Markdown、CI guardrails 和 agent accessibility 的责任边界。 - 【必看】Pi作者 - 我受够了所有 AI Agent，自己造了一个（Mario Zechner） — 中文案例：
pi选择极简 system prompt、少量核心 tools、避免功能膨胀，适合讨论 workflow 设计里“少即是约束”的取舍。 - 【必看】PI架构深度解析｜Agent循环、工具调用、TUI与更多 — 中文案例：从
Agent Loop、tools、skills、TUI、extension 和 session 管理拆解 agent workflow，适合开发/QA 进阶部分引用。