oh-my-claudecode ultragoal 实战指南基于 Claude Code/goal的持久化多目标工作流【免费下载链接】oh-my-claudecodeTeams-first Multi-agent orchestration for Claude Code项目地址: https://gitcode.com/GitHub_Trending/oh/oh-my-claudecode导读ultragoal是 oh-my-claudecodeOMC提供的一套仓库原生的持久化多目标工作流它把一段 brief 拆解为有序目标集合以追加式append-only账本记录 start/checkpoint/blocker/failure 事件并通过打印模型可读的交接文本handoff指导当前 Claude agent 在会话内驱动 Claude Code 的/goal斜杠命令。本文将从使用场景、命令全集、工件布局、质量门禁到并行会话约束完整讲解这套工作流并深入对应源码CLI 命令实现、核心工件逻辑、快照对账帮助你在大规模多步骤任务、跨会话续跑和多仓库并行场景下落地使用。为什么需要 ultragoal/goal的会话级局限Claude Code 的/goal是一个会话级session-scopedStop hook它会阻止会话停止直到某个条件成立并在条件满足时自动清除。作为单一会话内的执行原语/goal非常有效但它存在三个天然短板跨会话丢失状态会话重启后/goal状态不保留无最终评审门禁/goal本身不强制最终 review 关卡shell 无法操作它从 shell 无法直接调用或修改 Claude Code 的/goal状态。ultragoal在这之上叠加了持久计划plan、账本ledger和门禁gating层让一个长期多步骤的 initiative 可以在会话重启、全新 worktree、评审迭代之间存活同时仍然借助/goal保持当前 agent 聚焦于目标。正如 SKILL.md 中明确指出的It does not — and cannot — mutate Claude/goalstate from the shell; it persists durable repo state and prints a model-facing handoff that the active agent must act on in-session.何时使用 / 何时不用ultragoal适合以下场景见 SKILL.md 的 Use_When用户需要一个跨多个 Claude 会话或 worktree的、仓库原生的 ultragoal 追踪方式工作量大到值得拆成多个有序 stories每个 story 带尝试次数attempt count与逐 story 证据evidence用户希望最终完成被ai-slop-cleaner verification $code-review门禁强制把关用户希望把活跃的 Claude/goal指令与账本协调使会话重启不丢进度。与之相对不要使用它的情况任务只是单个小改动——应直接委派或使用ralph用户希望助手从 shell 直接调用/goal本身——这不可能omc ultragoal只写工件并打印交接文本用户只想要纯规划工件、没有执行循环——应改用plan。从源码结构看ultragoal在工作流注册表中被明确保留为直接可调用的持久化多目标工作流Retained as the durable multi-goal workflow with its own .omc/ultragoal artifacts并可通过 CLI 入口 的omc ultragoal子命令体系访问。工件布局.omc/ultragoal/下到底存了什么ultragoal的全部持久化状态存放在仓库的.omc/ultragoal/目录下包含三个核心工件常量定义见 artifacts.ts文件作用brief.md原始 brief 文本来自--brief/--brief-file/ stdingoals.json计划本身goal 列表、各自状态、尝试次数、active goal id、aggregate 完成记录ledger.jsonl追加式事件账本每行一个 JSON 事件多计划布局通过--plan-id或--auto-plan-id启用则写入.omc/ultragoal/plans/{planId}/brief.md .omc/ultragoal/plans/{planId}/goals.json .omc/ultragoal/plans/{planId}/ledger.jsonlplanId是稳定字符串自动生成格式为{epochMs}-{slug}其中 slug 取自 brief 首个非空标题实现见 makePlanId。ledger.jsonl支持的事件类型见 UltragoalLedgerEntry包括plan_created、goal_started、goal_resumed、goal_completed、goal_blocked、goal_failed、goal_retried、aggregate_completed、goal_added、final_review_failed、goal_review_blocked。由于是追加式写入appendFile见 appendLedger账本天然不可变、可审计。goal ID 采用G001-{slug}形式slug 由标题派生例如G001-build-the-cli见 normalizeGoalId测试断言见 artifacts.test.ts。完整命令参考omc ultragoal提供以下子命令完整帮助文本见 ULTRAGOAL_HELPomc ultragoal create-goals [--brief text | --brief-file path | --from-stdin] [--goal title::objective] [--claude-goal-mode aggregate|per-story] [--force] [--plan-id id | --auto-plan-id] [--json] omc ultragoal complete-goals [goal-id] [--retry-failed] [--plan-id id] [--json] omc ultragoal add-goal --title title --objective text [--evidence text] [--plan-id id] [--json] omc ultragoal record-review-blockers --goal-id id --title title --objective text --evidence review-findings --claude-goal-json active-json-or-path [--plan-id id] [--json] omc ultragoal checkpoint --goal-id id --status complete|failed|blocked [--evidence text] [--claude-goal-json json-or-path] [--quality-gate-json json-or-path] [--plan-id id] [--json] omc ultragoal status [--claude-goal-json json-or-path] [--plan-id id] [--json] omc ultragoal list-plans [--json]别名create→create-goalscomplete/next/start-next→complete-goals。所有子命令都支持--json输出结构化结果--json输出实现见 printJson。1. 创建计划create-goals从 brief 文件创建omc ultragoal create-goals --brief-file plan.md或显式指定 storiesomc ultragoal create-goals --brief ship the migration \ --goal Schema::Add new columns \ --goal Backfill::Backfill rows in batches \ --goal Cutover::Drop old columns and switch reads--goal的格式是title::objective冒号前是标题、之后是目标文本解析逻辑见 parseGoalArg。若未传任何--goal则会从 brief 自动派生候选目标优先提取列表项-/*/或数字序号开头其次按空行分段取段落见 deriveGoalCandidates。默认模式为aggregate一个 Claude/goal覆盖整次运行传--claude-goal-mode per-story可让每个 story 各自拥有/goal。两个模式之间可通过--force重新创建已有计划——但注意默认会拒绝覆盖已存在的goals.json见 createUltragoalPlan并校验planId只允许a-z、0-9、点、下划线、连字符。多仓库工作区 / 并行会话当同一工作区内有多个 Claude 会话需要并发运行/ultragoal时必须传--plan-id stable-id或--auto-plan-id让计划写入.omc/ultragoal/plans/{planId}/而非共享的单计划路径否则两个会话创建目标会互相覆盖。--auto-plan-id从 brief 标题派生{epochMs}-{slug}。之后该会话内所有后续子命令都要带上同一个--plan-id id需要时用omc ultragoal list-plans枚举可用 planId。2. 开始或恢复下一个 storycomplete-goalsomc ultragoal complete-goals [goal-id]不带 goal id保持默认行为——恢复活跃 story或开始第一个 pending story带 goal id精确定位该具名可执行 story允许乱序开始一个 pending story且绝不回退到其他 story若存在其他活跃 story、id 未知、已完成、review-blocked或失败但未传--retry-failed则拒绝且不产生任何状态变更具名且 in-progress 的 story 会被恢复不改变其 attempt 计数。这些规则在 startNextUltragoal 中有完整实现恢复活跃 story 会写goal_resumed事件开始新 story 会attempt 1、写入goal_started事件失败 story 只有在--retry-failed时才先写goal_retried事件再置回 pending。该命令会打印一条面向模型的交接文本handoff由活跃 Claude agent 阅读并执行。handoff 内容由 buildClaudeGoalInstruction 按模式分发到 buildPerStoryClaudeGoalInstruction 或 buildAggregateClaudeGoalInstruction包含计划与账本路径、目标 id、/goal集成约束、建议的/goalpayload JSON、以及最终 story 才有的强制质量门禁说明。测试对此断言了关键措辞artifacts.test.ts。拿到 handoff 后活跃 Claude agent 需要为本会话设置原生 Claude/goal——在独立 Claude Code 中shell 和 agent 都无法代劳需请用户输入/goal aggregate objective并等待。注意--claude-goal-json只做账本对账不满足PreToolUse/goal守卫——该守卫会阻止工具调用直到它观察到真实的活跃/goal推进该 storystory 完成后若是最后一个 story还需通过完整质量门禁回传活跃/goal状态的快照并调用checkpoint。3. 记录进度checkpointomc ultragoal checkpoint --goal-id G001-... --status complete \ --evidence tests/files/PR evidence \ --claude-goal-json {goal:{objective:...,status:active}}--status仅接受complete | failed | blocked三选一校验见 ultragoal.ts。checkpoint 只允许作用于活跃的 in-progress goalassertActiveInProgressCheckpointcomplete会校验/goal快照见下文快照对账写goal_completed事件并清除 activeGoalIdfailed记录failedAt与failureReason写goal_failed事件blocked用于已完成的历史 Claude goal 阻塞本会话设置新/goal的场景要求传入一个status 为 complete 且 objective 与本计划不同的/goal快照见 checkpointUltragoal 与 buildCompletedLegacyGoalRemediation随后建议在全新 Claude Code 会话中继续本 ultragoal。对于最后一个 story还需传--quality-gate-json包含aiSlopCleaner、verification、codeReview三部分证据全部 clean。4. 最终评审未通过record-review-blockers当最终 review 不干净时不要标记 complete而是记录 blockersomc ultragoal record-review-blockers --goal-id G00X-... \ --title Resolve final code-review blockers \ --objective Fix the listed review findings and rerun final gates \ --evidence the review findings \ --claude-goal-json {goal:{objective:...,status:active}}该命令会把原 goal 置为review_blocked、追加一个新的 blocker story并让 Claude/goal保持 active实现见 recordFinalReviewBlockers。它的前置条件很严格goal 必须处于in_progress且必须是唯一未解决的 storyisFinalRunCompletionCandidate 要求其余 goal 全部为 complete 或 review_blocked。账本会依次写入final_review_failed、goal_added、goal_review_blocked三个事件。5. 随时查看状态status 与 list-plansomc ultragoal status omc ultragoal list-plansstatus输出形如ultragoal: 2/5 complete, 1 pending, 1 in progress, 1 failed, 0 review-blocked并用*标记活跃 goal见 printStatus若传了--claude-goal-json还会附带对账警告。list-plans枚举plans/目录下的全部 planId目录不存在时返回空列表。两种 Claude/goal模式aggregate 与 per-story--claude-goal-mode决定/goal与账本 story 的映射关系模式定义见 UltragoalClaudeGoalModeCLI 归一化见 normalizeClaudeGoalModeaggregate默认一个 Claude/goal覆盖整个 ultragoal 运行OMC 在持久账本里逐个 checkpoint G001/G002 等 story。创建计划时会自动生成 aggregate objective——前缀Complete all ultragoal stories in .omc/ultragoal/goals.json:后接每个 goal 的{id} {title}总长超过 4000 字符时回退到简短引用形式见 aggregateClaudeObjective。中途 story 完成时/goal保持 active直到最后一个 story 才允许清除。per_story每个 story 拥有自己的/goal。--claude-goal-mode同时接受per-story与per_story两种拼写检查点要求每个 story 的/goal快照状态为complete。预期 objective 的推导见 expectedClaudeObjectiveaggregate 模式用计划级claudeObjectiveper-story 模式用该 goal 的objective。status命令的对账也按此选择 expectedObjectiveultragoal.ts。快照对账机制--claude-goal-json 如何工作--claude-goal-json接受内联 JSON 或文件路径两种形式readClaudeGoalSnapshotInput。快照的合法形状包括{ goal: { objective: ..., status: active } } { objective: ..., status: complete }condition被接受为objective的同义词status的合法取值归一化为active | complete | cancelled | failed | unknownnormalizeStatusactive接受active/in_progress/pending/running等写法。对账逻辑reconcileClaudeGoalSnapshot做三件事检查快照是否存在且可解析available校验objective与计划期望文本是否一致做了空白归一化校验status是否在允许集合内requireComplete时还要求状态为complete。重要边界这些快照是模型提供的、关于活跃/goal状态的证据OMC 只验证其文本与计划期望目标、账本事件的一致性无法独立观察Claude/goal的真实状态也不满足PreToolUse/goal守卫——守卫要求真实的活跃/goal宿主编入的快照或用户在本会话设置的原生/goal。如果 Claude/goal斜杠命令被重命名或重构只需调整交接文本措辞对账逻辑与名称无关见 SKILL.md 的 Important_Limitations。最终质量门禁quality-gate-json最后一个 story 的checkpoint --status complete必须携带--quality-gate-json其结构类型定义见 UltragoalQualityGate校验见 validateQualityGate如下{ aiSlopCleaner: { status: passed, evidence: ai-slop-cleaner ran on changed files }, verification: { status: passed, commands: [npm test], evidence: tests passed after cleaner }, codeReview: { recommendation: APPROVE, architectStatus: CLEAR, evidence: $code-review approved with CLEAR architecture } }校验规则源码强制测试示例见 artifacts.test.tsaiSlopCleaner.status必须为passed且带 evidence——即使是无操作也要运行ai-slop-cleanerverification.status必须为passedcommands必须是非空字符串数组codeReview.recommendation必须为APPROVE、architectStatus必须为CLEAR——出现COMMENT/REQUEST CHANGES或WATCH/BLOCK时必须改用record-review-blockers而不是标记完成。只有最后 story 且未显式放宽时才强制校验门禁checkpointUltragoal。另外还有一个特殊路径aggregate 模式下如果快照 objective 与期望不同但为completeOMC 会尝试任务级 aggregate 对账canReconcileCompletedTaskScopedAggregateSnapshot——要求证据中提及.omc/ultragoal/goals.json或ledger.jsonl、点名活跃 OMC goal id、包含实现完成 验证/评审通过语义且快照 objective 能映射到 brief——满足时才允许以aggregate_completed收尾。并行会话与多仓库工作区SKILL.md 专门给出了三条并行会话注意事项Parallel session caveats与 docs/REFERENCE.md 的状态根解析规则一一对应多仓库工作区锚点在父目录放置.omc-workspace标记让跨子仓库的多个会话共享一个.omc/。状态根解析顺序为OMC_STATE_DIR .omc-workspace git cwd详见 REFERENCE.md 状态根解析。.omc-workspace内容可为空 JSONecho {} .omc-workspace仅作标记使用REFERENCE.md 多仓库工作区。OMC_STATE_DIR则将状态集中到$OMC_STATE_DIR/{project-id}/可在 worktree 删除后保留状态REFERENCE.md OMC_STATE_DIR。会话 id 来源CLI 上下文优先取OMC_SESSION_ID环境变量hook 上下文取payload.data.session_idhook payload 的 session_id 已按 Claude Code 会话隔离。计划 id同一工作区两次运行会争用共享计划工件。要么使用互不相同的 session id要么传--plan-id让并行 ultragoal 运行落在独立账本上。并行裁决受支持——每个会话写入各自的会话级状态。多计划解析规则resolveActivePlanId显式--plan-id优先其次是遗留单计划goals.json向后兼容再次是恰好存在一个多计划时自动选中存在多个计划时--plan-id成为必填。--plan-id与--auto-plan-id互斥createUltragoalPlan。相关多仓库行为有专门测试覆盖artifacts.multirepo.test.ts。限制与边界务必牢记shell 无法调用或修改 Claude Code/goal状态。omc ultragoal只持久化工件并打印供活跃 Claude agent 在会话内执行的指令快照是模型自证的OMC 校验文本一致性但不能独立观察/goal状态也不能用快照顶替 PreToolUse/goal守卫/goal命名无关性斜杠命令被重命名或重构时只需改交接文本措辞对账逻辑不受影响单一小任务不要用应直接委派或使用ralph纯规划请用plan。深入阅读指引技能说明skills/ultragoal/SKILL.mdCLI 命令与帮助文本src/cli/commands/ultragoal.ts计划/账本/门禁核心实现src/ultragoal/artifacts.ts/goal快照解析与对账src/goal-workflows/claude-goal-snapshot.ts单元测试单计划/多计划src/ultragoal/tests/artifacts.test.ts、src/ultragoal/tests/artifacts.multirepo.test.ts状态根解析与多仓库锚点docs/REFERENCE.md掌握这套工作流后你可以在一次史诗级任务中把 brief 拆成可追踪、可审计、可跨会话续跑的目标序列让 Claude/goal与 OMC 账本各司其职最终在ai-slop-cleaner verification $code-review全部通过后才真正收尾。【免费下载链接】oh-my-claudecodeTeams-first Multi-agent orchestration for Claude Code项目地址: https://gitcode.com/GitHub_Trending/oh/oh-my-claudecode创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考