ruflo 代码目标规划 Agent：以 SPARC 驱动的 GOAP 方法落地软件开发智能计划

代码需求往往以模糊的一句话开始（"给 API 加 OAuth2""把数据库查询优化一下"），而 code-goal-planner 正是为解决这种"从模糊到可执行"的断层而设计的专用规划 Agent。它把游戏 AI 中的 Goal-Oriented Action Planning（GOAP，目标导向行为规划）思想引入软件开发，并与 SPARC 方法论的五个阶段（Specification→Pseudocode→Architecture→Refinement→Completion）深度融合，将特性开发、缺陷修复、性能调优、技术债清理等目标分解为带前置条件、可交付物与成功指标的里程碑。读完本文，你将掌握该 Agent 的完整规划模型、SPARC 命令编排方式、配套 YAML/TypeScript 规划模板，以及它如何与 ruflo 仓库中的 swarm 与 memory MCP 工具协同工作，从而在自己的工程中复刻"目标可验证、步骤可追踪"的智能开发规划。

一、认识 code-goal-planner：一份"代码中心"的规划 Agent 定义

在 ruflo 仓库中，code-goal-planner 是一份标准的 Claude Code Subagent 定义文件，采用 YAML frontmatter + 系统提示词的结构：

• 源位置：.claude/agents/goal/code-goal-planner.md
• 插件分发版本：plugin/agents/goal/code-goal-planner.md（经核对两处内容完全一致，保证本地与插件安装场景行为统一）

frontmatter 中的 name: code-goal-planner 与 description 决定了该 Agent 何时被路由调用。其 description 内嵌了两组示例触发场景，可作为"何时选用此 Agent"的判据：

• 复杂功能实现：用户提出"为我们的 API 添加 OAuth2 认证"，期望产出包含 provider 配置、token 管理与安全考量的可测试里程碑计划；
• 性能优化：用户提出"应用变慢了，需要优化数据库查询"，期望产出包含 profiling、索引策略与缓存实现的带量化目标计划。

同一目录下还存在着与之互补的两份规划 Agent，阅读时建议对照：

• goal-planner.md：面向任意复杂目标的通用 GOAP 规划器，强调 A* 状态空间搜索、OODA 闭环重规划与混合执行策略；
• plugin/agents/goal/agent.md：名为 sublinear-goal-planner 的亚线性优化版本，以矩阵运算、PageRank 优先级排序与时间优势预测做规划。

三者的分工可以概括为：通用 GOAP 负责"找路"，亚线性规划器负责"在大状态空间里高效找路"，而本文的主角 code-goal-planner 负责"把路切成带验收标准的代码里程碑"。

二、SPARC-GOAP 融合框架：方法论如何被装进规划器

code-goal-planner 的定位语开宗明义：它是一名 Code-Centric GOAP 专家，专注软件研发目标，使用 SPARC 方法论（Specification、Pseudocode、Architecture、Refinement、Completion）把含糊的需求转成具体里程碑。SPARC 为每个 GOAP 动作提供了结构化框架，二者一一映射：

SPARC 阶段	在目标规划中的职责	对应 GOAP 要素
1. Specification（定义目标态）	分析需求与约束；定义成功标准与验收测试；映射当前态→目标态；识别前置条件与依赖	Goal State 定义
2. Pseudocode（规划动作）	设计算法与逻辑流；创建动作序列；定义状态迁移；勾勒测试场景	Action Sequence
3. Architecture（结构化方案）	设计系统组件；规划集成点；定义接口与契约；确立数据流模式	Solution Structure
4. Refinement（迭代改进）	TDD 实现循环；性能优化；代码评审与重构；边界情况处理	Iterative Refinement
5. Completion（达成目标态）	集成与部署；最终测试与验证；文档与交接；成功指标核验	Goal State 验证

把 SPARC 阶段当作 GOAP 的"动作类型"是这套融合的核心设计：每执行一个 SPARC 阶段，就等价于让世界状态前进一段，而"完成态校验"天然地落在最后一个阶段。

核心能力清单

文档把软件研发中的规划场景归纳为八大类，这是判断 Agent 适用范围的操作清单：

• 功能实现：把特性拆成原子化、可测试的组件；
• 缺陷修复：制定系统化的调试与修复策略；
• 重构计划：设计"功能保持不退化"的增量重构；
• 性能目标：设定可测量的性能指标与优化路径；
• 测试策略：定义覆盖率目标与测试金字塔方法；
• API 开发：规划端点设计、版本化与文档；
• 数据库演进：零停机 schema 迁移策略；
• CI/CD 增强：流水线优化与部署自动化目标。

三、面向代码的 GOAP 方法论：从状态分析到里程碑建模

3.1 代码状态分析（State Analysis）

GOAP 的起点是把"目标"翻译成可比较的状态快照。文档给出的范式是分别建立 current_state 与 goal_state 两个对象，让差距本身成为规划输入：

current_state = {
  test_coverage: 45,
  performance_score: 'C',
  tech_debt_hours: 120,
  features_complete: ['auth', 'user-mgmt'],
  bugs_open: 23
}

goal_state = {
  test_coverage: 80,
  performance_score: 'A',
  tech_debt_hours: 40,
  features_complete: [...current, 'payments', 'notifications'],
  bugs_open: 5
}

这种表达方式的工程价值在于可度量：覆盖率从 45 提到 80、技术债从 120 小时压到 40、缺陷从 23 收敛到 5，任何一项都可以在 Refinement/Completion 阶段被 TDD 测试与指标仪表盘客观核验。

3.2 动作分解（Action Decomposition）

有了状态差，下一步是把它展开为动作集合。文档要求每次代码变更都要显式回答三件事：

• 把每次代码变更映射到前置条件（preconditions）与效果（effects）；
• 估算工作量与风险因子；
• 识别依赖与可并行机会（这是多 Agent swarm 并行执行的基础）。

3.3 里程碑规划（Milestone Planning）

里程碑是 GOAP 计划在代码世界的"落地单元"，文档用 TypeScript 接口给出了稳定的数据结构：

interface CodeMilestone {
  id: string;
  description: string;
  preconditions: string[];
  deliverables: string[];
  success_criteria: Metric[];
  estimated_hours: number;
  dependencies: string[];
}

字段语义可以直接落地为工程实践：preconditions 对应"必须已就绪的上游交付"，success_criteria 使用前文定义的 Metric 类型做量化验收，dependencies 则供调度器识别可并行分支。仓库配套的 SPARC 子 Agent 文件（specification.md、pseudocode.md、architecture.md、refinement.md，同名副本位于 plugin/agents/sparc/）说明这套方法论并非一次性提示词，而是一个被拆分成独立可组合角色的完整体系。

四、SPARC 命令集成：把计划变成可执行管线

计划只有能驱动真实工具才具备生产力。文档给出的 SPARC 命令行编排方式，与仓库 plugin/commands/sparc/ 下的命令定义一一对应（例如 spec-pseudocode.md 中即规定了"无 MCP 时回退到 npx claude-flow sparc run spec-pseudocode ..."的调用约定）：

# 按 SPARC 阶段执行以达成目标
npx claude-flow sparc run spec-pseudocode "OAuth2 authentication system"
npx claude-flow sparc run architect "microservices communication layer"
npx claude-flow sparc tdd "payment processing feature"
npx claude-flow sparc pipeline "complete feature implementation"

# 复杂目标的批处理
npx claude-flow sparc batch spec,arch,refine "user management system"
npx claude-flow sparc concurrent tdd tasks.json

命令矩阵可总结如下：

命令形态	作用	典型场景
sparc run spec-pseudocode "<目标>"	规格与伪代码阶段	需求澄清、算法设计、测试场景勾勒
sparc run architect "<目标>"	架构阶段	组件设计、接口契约、数据流
sparc tdd "<目标>"	Refinement 阶段的 TDD 循环	特性实现、覆盖率达标
sparc run integration "<目标>"	Completion 阶段集成	部署、联调、监控搭建
sparc batch spec,arch,refine "<目标>"	连续批处理多个阶段	用户管理系统等大型目标
sparc concurrent tdd tasks.json	并发执行可并行任务	由 dependencies 识别出的并行分支
sparc verify "<目标>"	最终目标态核验	交付前门禁

4.1 完整特性实现计划模板（YAML）

文档提供了一个可直接套用的"支付处理特性"端到端模板，其结构可以视为 CodeMilestone 接口的上层编排表达——每个阶段都带 command、deliverables 与 success_criteria，GOAP 里程碑再按 SPARC 阶段挂载：

goal: implement_payment_processing_with_sparc
sparc_phases:
  specification:
    command: "npx claude-flow sparc run spec-pseudocode 'payment processing'"
    deliverables:
      - requirements_doc
      - acceptance_criteria
      - test_scenarios
    success_criteria:
      - all_payment_types_defined
      - security_requirements_clear
      - compliance_standards_identified

  pseudocode:
    command: "npx claude-flow sparc run pseudocode 'payment flow algorithms'"
    deliverables:
      - payment_flow_logic
      - error_handling_patterns
      - state_machine_design
    success_criteria:
      - algorithms_validated
      - edge_cases_covered

  architecture:
    command: "npx claude-flow sparc run architect 'payment system design'"
    deliverables:
      - system_components
      - api_contracts
      - database_schema
    success_criteria:
      - scalability_addressed
      - security_layers_defined

  refinement:
    command: "npx claude-flow sparc tdd 'payment feature'"
    deliverables:
      - unit_tests
      - integration_tests
      - implemented_features
    success_criteria:
      - test_coverage_80_percent
      - all_tests_passing

  completion:
    command: "npx claude-flow sparc run integration 'deploy payment system'"
    deliverables:
      - deployed_system
      - documentation
      - monitoring_setup
    success_criteria:
      - production_ready
      - metrics_tracked
      - team_trained

goap_milestones:
  - setup_payment_provider:
      sparc_phase: specification
      preconditions: [api_keys_configured]
      deliverables: [provider_client, test_environment]
      success_criteria: [can_create_test_charge]

  - implement_checkout_flow:
      sparc_phase: refinement
      preconditions: [payment_provider_ready, ui_framework_setup]
      deliverables: [checkout_component, payment_form]
      success_criteria: [form_validation_works, ui_responsive]

  - add_webhook_handling:
      sparc_phase: completion
      preconditions: [server_endpoints_available]
      deliverables: [webhook_endpoint, event_processor]
      success_criteria: [handles_all_event_types, idempotent_processing]

值得注意的建模细节：goap_milestones 里的 sparc_phase 字段把"里程碑"与"SPARC 阶段"做了双向索引——setup_payment_provider 属于 specification，add_webhook_handling 挂在 completion，说明规划器可以按依赖把不同里程碑分配到不同阶段去执行，而不是机械地按阶段顺序串行。

4.2 性能优化计划模板（YAML）

当目标是量化指标时，模板进一步拆分出"分析（analysis）"与"优化动作（optimizations）"两层，每条优化动作都标注预期改善幅度，便于 Refinement 阶段做 A/B 验证：

goal: reduce_api_latency_50_percent
analysis:
  - profile_current_performance:
      tools: [profiler, APM, database_explain]
      metrics: [p50_latency, p99_latency, throughput]

optimizations:
  - database_query_optimization:
      actions: [add_indexes, optimize_joins, implement_pagination]
      expected_improvement: 30%

  - implement_caching_layer:
      actions: [redis_setup, cache_warming, invalidation_strategy]
      expected_improvement: 25%

  - code_optimization:
      actions: [algorithm_improvements, parallel_processing, batch_operations]
      expected_improvement: 15%

4.3 测试策略计划模板（YAML）

测试目标遵循测试金字塔拆解，每一层的 focus 字段帮助 TDD Agent 精确分配精力：

goal: achieve_80_percent_coverage
current_coverage: 45%
test_pyramid:
  unit_tests:
    target: 60%
    focus: [business_logic, utilities, validators]

  integration_tests:
    target: 25%
    focus: [api_endpoints, database_operations, external_services]

  e2e_tests:
    target: 15%
    focus: [critical_user_journeys, payment_flow, authentication]

五、与开发流程的整合：Git、Sprint 与持续交付

规划不能悬空，文档给出了三条落到流程的整合路径：

5.1 Git 工作流规划

每个里程碑天然对应一个特性分支，分支拆分本身即是计划粒度的检验：

# Feature branch strategy
main -> feature/oauth-implementation
     -> feature/oauth-providers
     -> feature/oauth-ui
     -> feature/oauth-tests

这种拆分与 CodeMilestone 一一映射：preconditions 相当于"上游分支已合入"，deliverables 相当于"本分支产出"，验收后逐级合回主干。

5.2 Sprint 规划整合

• 把里程碑映射到 Sprint 目标；
• 为每个动作估算 Story Points；
• 定义验收标准（即 success_criteria）；
• 搭建自动化追踪（状态快照中的指标天然可上报到看板）。

5.3 持续交付目标

pipeline_goals:
  - automated_testing:
      target: all_commits_tested
      metrics: [test_execution_time < 10min]

  - deployment_automation:
      target: one_click_deploy
      environments: [dev, staging, prod]
      rollback_time: < 1min

六、成功指标框架：让"完成"有客观定义

规划器要求每个目标都能回答"What does done look like"。文档给出了三维指标基线，任何功能、重构或性能目标的 success_criteria 都应从下列维度抽取：

代码质量指标

指标	阈值
圈复杂度	< 10
代码重复率	< 3%
测试覆盖率	> 80%
技术债比率	< 5%

性能指标

指标	阈值
响应时间（p99）	< 200ms
吞吐量	> 1000 req/s
错误率	< 0.1%
可用性	> 99.9%

交付指标

指标	阈值
交付周期（Lead Time）	< 1 天
部署频率	> 1 次/天
平均恢复时间（MTTR）	< 1 小时
变更失败率	< 5%

七、SPARC 模式化目标规划与端到端工作流

7.1 五种 SPARC 模式

规划器按目标类型选择执行模式，仓库的 sparc-modes.md 命令目录可佐证模式生态的完整性：

1. Development Mode（sparc run dev）：全栈特性开发、组件创建、服务实现；
2. API Mode（sparc run api）：RESTful 端点设计、GraphQL schema 开发、API 文档生成；
3. UI Mode（sparc run ui）：组件库搭建、界面实现、响应式设计模式；
4. Test Mode（sparc run test）：测试套件开发、覆盖率提升、E2E 场景创建；
5. Refactor Mode（sparc run refactor）：代码质量改进、架构优化、技术债削减。

7.2 完整工作流（TypeScript 视角）

从实现视角看，整个 SPARC-GOAP 流程可以被抽象成一次串行编排的异步管线：

// Complete SPARC-GOAP workflow for a feature
async function implementFeatureWithSPARC(feature: string) {
  // Phase 1: Specification
  const spec = await executeSPARC('spec-pseudocode', feature);

  // Phase 2: Architecture
  const architecture = await executeSPARC('architect', feature);

  // Phase 3: TDD Implementation
  const implementation = await executeSPARC('tdd', feature);

  // Phase 4: Integration
  const integration = await executeSPARC('integration', feature);

  // Phase 5: Validation
  return validateGoalAchievement(spec, implementation);
}

注意 Phase 5 的 validateGoalAchievement(spec, implementation)——验收不是事后补丁，而是把 Specification 阶段的 success_criteria 与实现产物做结构化比对。

八、MCP 工具集成：接入 swarm 与记忆系统

单 Agent 规划能力有限，code-goal-planner 通过与 Claude Code MCP 工具协作获得 swarm 执行与模式记忆能力。文档给出的调用范式如下，工具前缀 mcp__claude-flow__* 对应仓库 v3 生态中的 claude-flow MCP 服务：

// Initialize SPARC-enhanced development swarm
mcp__claude-flow__swarm_init {
  topology: "hierarchical",
  maxAgents: 5
}

// Spawn SPARC-specific agents
mcp__claude-flow__agent_spawn {
  type: "sparc-coder",
  capabilities: ["specification", "pseudocode", "architecture", "refinement", "completion"]
}

// Spawn specialized agents
mcp__claude-flow__agent_spawn {
  type: "coder",
  capabilities: ["refactoring", "optimization"]
}

// Orchestrate development tasks
mcp__claude-flow__task_orchestrate {
  task: "implement_oauth_system",
  strategy: "adaptive",
  priority: "high"
}

// Store successful patterns
mcp__claude-flow__memory_usage {
  action: "store",
  namespace: "code-patterns",
  key: "oauth_implementation_plan",
  value: JSON.stringify(successful_plan)
}

其协作逻辑可以概括为三点：

• swarm_init 决定拓扑：hierarchical 拓扑适合 SPARC 这种"规格→编码"的瀑布型任务流；
• agent_spawn 决定角色：sparc-coder 携带全部五个 SPARC 能力，而普通 coder 只挂重构与优化能力，避免重复劳动；
• memory_usage 沉淀经验：把成功计划写入 code-patterns 命名空间，后续相似目标可直接检索复用——这与仓库中 swarm 编排与记忆相关的插件体系（可参考 plugin/agents/swarm/ 与 plugin/agents/hive-mind/ 的角色划分）在理念上一脉相承。

九、风险评估与 SPARC-GOAP 协同

9.1 四维风险评估

每个代码目标在规划阶段都应过一遍风险清单：

1. 技术风险：复杂度、未知领域、依赖强度；
2. 工期风险：估算精度、资源可得性；
3. 质量风险：测试缺口、回归隐患；
4. 安全风险：漏洞引入、数据暴露面。

9.2 SPARC 如何增强 GOAP

文档把二者的协同总结为五点，可作为团队评审规划质量的自查标准：

1. 结构化里程碑：每个 GOAP 动作都能映射到一个 SPARC 阶段；
2. 系统性验证：SPARC 的 TDD 环节保证目标确实达成；
3. 清晰交付物：每个 SPARC 阶段都产生具体的、可评审的工件；
4. 迭代式精化：Refinement 阶段允许按执行反馈修正目标；
5. 完整收尾：Completion 阶段对"目标态"做最终校验。

9.3 目标达成模式（Goal Achievement Pattern）

文档给出了一个将 SPARC 五阶段封装为统一接口的规划器类，并用 A* 搜索串联各阶段动作：

class SPARCGoalPlanner {
  async achieveGoal(goal) {
    // 1. SPECIFICATION: Define goal state
    const goalSpec = await this.specifyGoal(goal);

    // 2. PSEUDOCODE: Plan action sequence
    const actionPlan = await this.planActions(goalSpec);

    // 3. ARCHITECTURE: Structure solution
    const architecture = await this.designArchitecture(actionPlan);

    // 4. REFINEMENT: Iterate with TDD
    const implementation = await this.refineWithTDD(architecture);

    // 5. COMPLETION: Validate and deploy
    return await this.completeGoal(implementation, goalSpec);
  }

  // GOAP A* search with SPARC phases
  async findOptimalPath(currentState, goalState) {
    const actions = this.getAvailableSPARCActions();
    return this.aStarSearch(currentState, goalState, actions);
  }
}

这一模式揭示了一个实现要点：SPARC 阶段被抽象为"GOAP 动作空间"，A* 的代价函数天然适合承载 estimated_hours、风险系数等量化字段，从而在多个候选计划中选出代价最优者。

十、端到端落地示例与持续改进

10.1 完整功能实现命令行序列

把前述所有模板落到终端，一次"用户认证特性"的完整周期如下：

# 1. Initialize SPARC-GOAP planning
npx claude-flow sparc run spec-pseudocode "user authentication feature"

# 2. Execute architecture phase
npx claude-flow sparc run architect "authentication system design"

# 3. TDD implementation with goal tracking
npx claude-flow sparc tdd "authentication feature" --track-goals

# 4. Complete integration with goal validation
npx claude-flow sparc run integration "deploy authentication" --validate-goals

# 5. Verify goal achievement
npx claude-flow sparc verify "authentication feature complete"

其中 --track-goals 与 --validate-goals 两个开关值得专门说明：前者让 TDD 实现过程实时对照里程碑目标，后者在集成阶段强制触发 success_criteria 核验，二者共同把"目标追踪"嵌入了执行而非停留在计划文档里。

10.2 持续改进回路

文档最后给出的改进机制，本质上是一个面向规划器自身的 OODA 循环：

• 记录计划耗时 vs 实际耗时的偏差，校准估算模型；
• 按 SPARC 阶段统计目标达成率，找出薄弱环节（例如"架构总超时"暗示 spec 阶段不充分）；
• 收集开发团队对计划的反馈；
• 依据 SPARC 执行结果更新规划启发式；
• 在项目间共享成功的 SPARC 规划模式（写入 code-patterns 类命名空间）。

10.3 落地自查清单

文档以一段强约束收尾，可以作为任何"目标规划请求"的最终门禁——每个 SPARC 增强的代码目标都必须具备：

• 对"完成"的清晰定义；
• 可测量的成功标准；
• 可测试的交付物；
• 现实的工期估算；
• 已识别的依赖关系；
• 风险缓解策略。

结语

code-goal-planner 的价值不在于"更聪明地写代码"，而在于把编码目标变成可分解、可编排、可验收的状态转换过程。它以 SPARC 五阶段为骨架、以 GOAP 状态机为大脑、以 CodeMilestone 与 YAML 模板为数据结构，再通过 claude-flow sparc 命令与 swarm/memory MCP 工具接入真实执行环境。在 ruflo 仓库中，你既可以在 .claude/agents/goal/ 找到它的本地定义，也可以在 plugin/agents/goal/ 获取随插件分发的副本，并结合 plugin/agents/sparc/ 的各阶段子 Agent 与 plugin/commands/sparc/ 的命令规范将其组合进自己的工作流——对于任何想要把"AI 写代码"升级为"AI 有计划地交付代码"的团队，它都是一份可直接参照的规划范式。