ruflo code-goal-planner：用 SPARC-GOAP 把软件开发目标拆解为可验证的里程碑

ruflo（Claude Flow）仓库中的 code-goal-planner 技能定义了一种"代码中心的 GOAP（Goal-Oriented Action Planning）规划者"，它通过 SPARC 五阶段方法论把模糊的开发需求转化为带前置条件、交付物与可度量成功标准的里程碑计划。读完本文，你将掌握：如何用当前状态/目标状态建模一次开发目标、如何为每个里程碑指定 SPARC 阶段与成功判据，以及如何在 ruflo 的技能体系（.agents/ 目录）与 SPARC 命令链路（MCP 工具、npx claude-flow sparc CLI）中实际调用这一规划能力。

一、技能定位：.agents/skills/ 中的技能体系

ruflo 仓库把面向编码代理的技能统一放在 .agents/skills/ 下，每个技能是一个目录，内含一份 SKILL.md 指令文件（以及可选的 scripts/、docs/）。.agents/README.md 说明了这套结构：技能通过 $skill-name 语法调用，每个技能带有 YAML frontmatter 元数据、触发与跳过条件、命令与示例。

code-goal-planner 的 frontmatter 声明了它的双重身份：外层包装名为 agent-code-goal-planner（以 $agent-code-goal-planner 调用），内层角色为"代码中心的 GOAP 专家"，专注于软件开发目标，核心能力是把复杂编码任务拆分为"带有明确成功标准、可实现的里程碑"。文档给出的两个典型触发场景：

• 复杂功能实现：例如"给 API 加 OAuth2 认证"，规划者会拆出 provider 配置、token 管理、安全考量等可测试里程碑；
• 性能优化：例如"数据库查询太慢"，规划者会制定带可度量目标（profiling、索引策略、缓存）的优化计划。

与通用规划技能（如 agent-goal-planner）不同，code-goal-planner 的规划动作全部围绕代码状态展开：测试覆盖率、技术债小时数、未关闭缺陷数、已完成功能列表。

技能是否被加载由 .agents/config.toml 控制：其中 [[skills.config]] 列表按路径逐项启用技能（仓库当前默认启用了 swarm-orchestration、memory-management、sparc-methodology、security-audit 四个技能），并配套了模型选择（model）、审批策略（approval_policy）、沙箱模式（sandbox_mode）与并发上限（[performance] max_agents = 8）等运行参数。这意味着在 Codex CLI 环境下，规划类技能是"配置即开关"的组件——把 path = ".agents/skills/agent-code-goal-planner" 加入 [[skills.config]] 即可让它参与任务路由。

二、SPARC-GOAP 融合：五个规划阶段

技能的核心主张是：GOAP 负责"从当前状态搜索到目标状态的动作序列"，而 SPARC（Specification、Pseudocode、Architecture、Refinement、Completion）为每个里程碑提供结构化执行框架。五阶段各自承担明确职责：

1. Specification（定义目标状态）：分析需求与约束、定义成功判据与验收测试、映射当前状态到期望状态、识别前置条件与依赖；
2. Pseudocode（规划动作）：设计算法与逻辑流、生成动作序列、定义状态转移、勾勒测试场景；
3. Architecture（组织方案）：设计系统组件、规划集成点、定义接口与契约、建立数据流模式；
4. Refinement（迭代改进）：TDD 实现循环、性能优化、代码评审与重构、边界情况处理；
5. Completion（达成目标状态）：集成与部署、最终测试验证、文档与交接、成功指标核验。

这套阶段定义与 ruflo 仓库中两个相邻实现相互印证：sparc-methodology 技能给出了同样的五阶段及"何时触发/何时跳过"边界（新功能、架构变更、需求不清时触发；简单 bug 修复、文档更新时跳过）；plugin/commands/sparc.md 则把五阶段落成命令模式（spec-pseudocode、architect、tdd、integration 等 15 个 SPARC 模式）。

三、GOAP 方法论在代码上的三步落地

3.1 代码状态分析（Code State Analysis）

规划的第一步是把"现状"和"目标"写成两个可对比的状态对象。技能中的示例：

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
}

这种状态对象是 GOAP 搜索的输入：每个动作（code change）会声明它"需要哪些前置条件、产生哪些效果"，规划器据此在状态空间里寻找从 current_state 到 goal_state 的可行路径。

3.2 动作分解（Action Decomposition）

每个代码变更必须映射为"前置条件 + 效果"二元组，并进一步：

• 计算工作量估计与风险因子；
• 识别依赖关系与可并行机会。

3.3 里程碑规划（Milestone Planning）

里程碑被规范为一个 TypeScript 接口，是后续所有 YAML 计划的骨架：

interface CodeMilestone {
  id: string;
  description: string;
  preconditions: string[];   // 前置条件
  deliverables: string[];     // 交付物
  success_criteria: Metric[]; // 可度量的成功判据
  estimated_hours: number;    // 工时估计
  dependencies: string[];     // 依赖的其他里程碑
}

该接口保证每个里程碑天然可验证：success_criteria 必须是 Metric[]（度量），而不是主观描述。技能结尾的"完成定义清单"与之呼应——每个 SPARC 增强的代码目标都必须有：清晰的"完成"定义、可度量的成功标准、可测试的交付物、现实的工时估计、已识别的依赖、风险缓解策略。

四、SPARC 命令集成：从规划到执行

技能给出的 SPARC 命令集成示例（对应 ruflo 的 CLI 层，命令语义与 plugin/commands/sparc.md 中"NPX CLI（Fallback）"一节一致）：

# Execute SPARC phases for goal achievement
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"

# Batch processing for complex goals
npx claude-flow sparc batch spec,arch,refine "user management system"
npx claude-flow sparc concurrent tdd tasks.json

在仓库的 SPARC 命令体系中，sparc run <mode> 执行单个模式（spec-pseudocode、architect、tdd、integration 等），sparc modes --verbose 可列出全部模式；若 MCP 工具可用（Claude Code 场景），优先调用 mcp__claude-flow__sparc_mode { mode, task_description }，CLI 是不依赖 MCP 的回退路径。.agents/skills/sparc-methodology/SKILL.md 还展示了另一条等价链路：npx @claude-flow/cli hooks route --task "specification: [requirements]"，通过 hooks 路由把各阶段任务分发出去，并可用 npx @claude-flow/cli agent spawn --type sparc-coord --name sparc-lead 启动 SPARC 协调者代理。

五、完整计划示例：SPARC-GOAP 功能实现计划

技能中最具代表性的一份计划是"带 SPARC 阶段的支付处理实现"。它以 YAML 组织，分为 sparc_phases（每个 SPARC 阶段的命令、交付物、成功标准）与 goap_milestones（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]

这份计划体现了 SPARC-GOAP 融合的两个关键设计：

• 双向挂靠：sparc_phases 是纵向的阶段流水线（每阶段一条命令、一组交付物、一组判据），goap_milestones 是横向的动作图（每个动作有 preconditions 与 success_criteria），而每个动作用 sparc_phase 字段指明它属于哪个阶段——这正是文档"每个 GOAP 动作映射到一个 SPARC 阶段"论断的落地形式；
• 判据可执行化：如 can_create_test_charge（能创建测试扣款）、idempotent_processing（幂等处理）这类判据，都是可以被测试或人工核验的断言，而非"完成支付功能"式模糊表述。

六、两类专项计划模板：性能优化与测试策略

技能还提供了两份可直接套用的 YAML 模板。

6.1 性能优化计划（目标：降低 50% API 延迟）

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%

注意"先分析后优化"的顺序：analysis 段要求先用 profiler/APM/EXPLAIN 采集 p50、p99 与吞吐基线，optimizations 段的每项都带 expected_improvement 预估（30% + 25% + 15% ≈ 目标 50%），使优化路径本身可被核验——这正是 GOAP"效果预测"思想在性能场景的应用。

6.2 测试策略计划（目标：80% 覆盖率）

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]

测试金字塔各层目标（60/25/15）与关注点一一对应：单元测试覆盖业务逻辑、工具函数与校验器；集成测试覆盖 API 端点、数据库操作与外部服务；E2E 只覆盖关键用户旅程（支付流、认证等）。这与技能"Core Competencies"中"定义覆盖率目标与测试金字塔方法"的规划能力直接对应。

七、开发工作流集成

规划结果最终要落进日常工程流程，技能给出三个集成点：

1. Git 工作流规划——按里程碑粒度切功能分支：

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

2. Sprint 规划集成——把里程碑映射到 sprint 目标、为每个动作估算故事点、定义验收标准、建立自动化跟踪。

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

八、成功度量框架

技能把"目标达成"拆成三组量化指标，规划时按需引用：

维度	指标	目标值
代码质量	圈复杂度	< 10
代码质量	重复代码率	< 3%
代码质量	测试覆盖率	> 80%
代码质量	技术债比率	< 5%
性能	响应时间	p99 < 200ms
性能	吞吐	> 1000 req/s
性能	错误率	< 0.1%
性能	可用性	> 99.9%
交付	前置时间（Lead Time）	< 1 天
交付	部署频率	> 1 次/天
交付	MTTR	< 1 小时
交付	变更失败率	< 5%

这些数值是规划模板中的"默认判据库"，实际项目应结合 current_state 基线调整——这呼应了技能"状态分析"部分：先度量，再定目标。

九、SPARC 模式与目标规划的对应

技能按目标类型推荐不同的 SPARC 执行模式（模式名与 plugin/commands/sparc.md 中列出的 /sparc-architect、/sparc-tdd 等模式一一对应）：

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

一个完整功能的 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);
}

在命令行上，同样的五步展开为：

# 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"

从源码结构看，仓库中 SPARC 各模式均有对应的命令定义文件（如 spec-pseudocode 模式、architect 模式 位于 plugin/commands/sparc/），技能文档中的阶段命令与这些模式定义保持了同名对应关系。

十、MCP 工具集成：多代理执行规划

当规划目标足够大（如 OAuth 系统），技能建议把执行交给 ruflo 的 swarm/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(successual_plan)
}

（末段键值按原文为 JSON.stringify(successful_plan)。）这条链路里两个要点值得关注：一是分层拓扑（topology: "hierarchical"）与 config.toml 中 max_agents = 8 的并发约束相配合；二是记忆回写——成功计划以命名空间 code-patterns 存入记忆系统，使下次同类目标（如"另一个 OAuth 集成"）可以直接复用既有规划模式，这正是技能"Best Practices"中"完成后存储成功模式"的 MCP 化表达。sparc-methodology 技能 的最佳实践清单也包含同一要求：开始先查记忆、协调用分层拓扑、完成存模式、记录新学习。

十一、风险评估与 SPARC-GOAP 协同

11.1 四维风险评估

每个代码目标都要在规划期评估四类风险：

1. 技术风险：复杂度、未知项、依赖；
2. 时间线风险：估算准确性、资源可用性；
3. 质量风险：测试缺口、回归隐患；
4. 安全风险：漏洞引入、数据暴露。

风险结论应写回里程碑的 preconditions（例如"安全评审通过"作为部署里程碑的前置条件）或独立的风险缓解策略中。

11.2 协同机制与规划器参考实现

SPARC 对 GOAP 的增强体现为五点：结构化里程碑（每个 GOAP 动作对应一个 SPARC 阶段）、系统化验证（SPARC 的 TDD 保证目标达成）、清晰交付物（每个阶段产出具体工件）、迭代改进（Refinement 阶段允许目标调整）、完整集成（Completion 阶段核验目标状态）。技能给出的规划器参考类：

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);
  }
}

achieveGoal 把五阶段串成流水线，findOptimalPath 则展示了底层搜索：以 SPARC 阶段产出的动作集为动作空间，对状态图做 A* 搜索——规划（搜索最优动作序列）与执行（沿 SPARC 阶段实现）在此形成闭环。

十二、持续改进闭环

技能最后定义了规划系统自身的改进循环，这决定了 code-goal-planner 是"越用越准"的组件：

• 跟踪计划工时与实际执行工时的偏差；
• 度量各 SPARC 阶段的目标达成率；
• 收集开发团队反馈；
• 依据 SPARC 结果更新规划启发式；
• 跨项目共享成功的 SPARC 模式（对应第十节的 memory_usage store 回写）。

小结

code-goal-planner 的价值在于给出了一条可复制的"目标 → 状态 → 里程碑 → 命令"转化链：先用 current_state/goal_state 建模差距，再用 CodeMilestone 接口（前置条件 + 交付物 + 度量判据 + 工时 + 依赖）固化每个动作，然后把每个动作挂到 SPARC 五阶段之一，最后经 npx claude-flow sparc CLI 或 MCP 工具执行、并以三组量化指标（代码质量/性能/交付）验收。在 ruflo 仓库中，它与 .agents/config.toml 的技能配置、sparc-methodology 技能 的触发边界、SPARC 命令集 的模式定义共同构成一个"规划技能 + 执行框架"的配套体系：规划侧负责产出可验证的计划，执行侧负责按计划逐阶段落地。