用途
SPARC Workflow 提供一套系统化的软件开发方法论，通过规格化、结构化的阶段推进，产出文档完善、测试充分的代码。每个阶段都建立在前一阶段之上，适用于功能开发、测试驱动开发（TDD）、重构以及 API 或 UI 开发等需要明确规格的任务。
五个阶段
流程顺序为：Specification → Pseudocode → Architecture → Refinement → Completion。
-
Specification（规范）：定义要构建什么，产出需求文档。过程包括从用户提示中收集需求、识别验收标准、定义范围（范围内与范围外）、记录约束与假设。输出模板包含概述、功能性需求（FR）、非功能性需求（NFR，如性能、安全、可用性）、范围、验收标准、约束与假设。检查项包括：需求清晰无歧义、每条需求可测试、范围明确、约束已记录、用户故事符合“As a… I want… So that…”格式。
-
Pseudocode（伪代码）：在设计实现前设计算法与逻辑。过程包括将需求拆解为逻辑步骤、编写与语言无关的伪代码、识别边界情况、设计错误处理。指南包括显式呈现所有决策点、包含错误处理、标注复杂度（O(n)、O(n²) 等）、识别数据结构、展示边界情况（空输入、单条、最大规模）。输出模板含主算法、辅助函数、错误处理、边界情况表与复杂度分析。
-
Architecture（架构）：设计功能如何融入系统架构。过程包括识别受影响的组件、设计接口与契约、规划数据流、考虑依赖。考虑点包括新组件与修改组件、接口设计（如 Protocol 类）、数据流图、内部与外部依赖、文件结构。
-
Refinement（精炼，TDD）：以测试驱动开发方式实现功能。TDD 循环为 RED（写失败测试）→ GREEN（写最小代码通过）→ REFACTOR（改进代码质量）→ 重复。过程为：先写测试、运行测试（应失败）、写最小实现、运行测试（应通过）、重构。测试类别包括单元测试、集成测试、性能测试。
-
Completion（完成）：为生产环境收尾，包括文档、清理与验证。检查清单涵盖代码质量（所有测试通过、覆盖率≥80%、无 lint 错误、类型提示完整、docstring 完整）、文档（README、API 文档、用法示例、变更日志）、安全（输入验证、错误信息安全、无硬编码密钥、依赖审计）、性能（基准测试、内存检查、无 N+1 查询、按需缓存）、部署（配置文档、迁移脚本、回滚计划、监控）。
使用方式
文档给出的使用要点包括：运行完整的 SPARC 开发周期、运行以 TDD 为中心的工作流、列出可用的 SPARC 模式。可用模式有 dev（完整开发周期）、api（API 开发）、ui（UI 开发）、test（测试聚焦）、refactor（代码改进）。文件存放于 .agent-os/ 目录，specs/feature-name/ 下包含 spec.md、tasks.md 以及 sub-specs/（pseudocode.md、architecture.md、tests.md、api-spec.md），product/decisions.md 记录决策日志。文档还提及与 Claude Flow、Agent OS 的集成，以及 create-spec、execute-tasks 工作流。执行清单包含从需求文档到部署的完整步骤。
适用场景
- 从零实现新功能
- 编码前需要结构化分析的复杂问题
- 构建带完整测试的生产级代码
- 系统性重构既有代码
- 需要明确规格的 API 或 UI 开发
限制与前提
使用前需：理解 TDD（测试驱动开发）、项目具备 .agent-os/ 目录结构、可访问测试框架（pytest、jest 等）。成功指标包括：新代码测试覆盖率≥80%、零 lint 错误且类型提示完整、公共 API 100% 文档化、满足已定义的非功能性需求基准、测试先于实现。文档也列出了各阶段的常见问题与处理方式，例如需求不清时先提出澄清问题、范围蔓延时明确记录范围外项、测试过复杂时拆分为更小单元、测试不稳定时用 mock 隔离外部依赖等。