oh-my-posh 仓库 Code Changes 技能全解：从 Issue 到交付的六阶段 Agent 编排工作流

oh-my-posh 仓库 Code Changes 技能全解：从 Issue 到交付的六阶段 Agent 编排工作流

【免费下载链接】oh-my-poshThe most customisable and low-latency cross platform/shell prompt renderer项目地址: https://gitcode.com/GitHub_Trending/oh/oh-my-posh

导读

code-changes 技能 是 oh-my-posh 仓库为 AI Agent（如 Claude Code、GitHub Copilot、Codex 等）设计的端到端代码变更编排工作流，覆盖"Issue 分析 → 用户批准 → 规划 → 执行器匹配 → 子代理委派与监督 → 验证 → 交付"的完整链路。它定义了何时分析、何时停下等待用户拍板、如何挑选合适的模型、如何委派并监督子代理、如何在合并态上独立验证，以及如何以约定式提交和结果优先的报告收尾。读完本文，你将掌握一套可复用的 Agent 编排方法论：理解四个角色（Coordinator / Escalation / Implementer / Trivial）的能力分层、六个阶段的产物契约、停止门（Stop Gate）与重试上限（Retry Cap）的执行细节，并能对照仓库内的完整参考文档自行落地。

一、文档定位：仓库内 Agent 技能体系的一员

oh-my-posh 在仓库根目录的.agents/skills/下维护了一套面向 AI 编码代理的技能集，除本文核心的code-changes外，还包括：

• conventional-commit：约定式提交消息生成（feat、fix、docs等类型与BREAKING CHANGE:双标记规范）；
• project-knowledge：沉淀 Shell 集成、终端 / pty 行为、缓存、分段渲染等领域的经验知识库；
• 以及golang、markdown、powershell、ast-grep、segment-create、segment-docs、writing-clearly-and-concisely等专项技能。

code-changes的定位是总编排器：它不替代上述任何一个专项技能，而是规定"任何以代码变更收尾的任务"（Issue 分析、PR 评审、功能实现、缺陷修复、重构、想法落地）必须遵循的分析-规划-委派-监督-验证-交付流程。其核心原则是：先分析、后代码——分析永远在第一位，代码永远在最后一位。

二、角色模型：按能力分层，而非按名称分层

工作流的职责分配基于"模型能力分层"（capability tier），协调者（Coordinator）不是最强模型，而是常驻、默认接管每个阶段、并且清楚自己何时力有不逮的那个模型。

具体到各家厂商的模型映射（Anthropic / OpenAI / Google 四层各对应哪些模型），以及如何在 Claude Code、GitHub Copilot、Codex、IDE 代理中落地这套拆分，见 model-tiers.md。该文件特别指出：模型名称是"快照"，会过时；当名称不再存在时，应按层级而非名称来映射替代品。

一个关键推论：如果当前代理本身就运行在实现者层级，标准工作无需单独的委派步骤——直接规划并执行，但每个阶段仍要完整走一遍。升级（Escalation）只在触发器命中时发生，绝非常态，也不为"协调者自己就能做的常规判断"而触发。

三、六阶段流程总览

整个流程按顺序执行六个阶段，每个阶段的边界都携带一个命名产物（见 artifacts.md），这使得某个阶段可以在之后被重入（例如 Verify 失败、升级问题返回）而不必从头推导上下文：

1. Analyze（分析）——对照代码而非仅凭报告确定根因与范围；
2. Plan（规划）——钉死规格说明（spec）、任务拆分、并行/串行决策、每个任务的工作区；
3. Delegate（委派）——为每个任务匹配正确的执行者，默认是协调者层级；
4. Supervise（监督）——监控、解阻、并以批判性眼光评审实现者输出；
5. Verify（验证）——质量门禁 + 功能实证，在合并后的最终状态上运行，绝不向下委派；同一任务连续第二次失败时升级而非第三次循环；
6. Deliver（交付）——约定式提交 + 结果优先的报告。

Analyze、Supervise、Verify 三个阶段各带一个升级检查点（见 escalate.md），用于把某个具体判断交给最强模型，同时不让出阶段所有权。

停止门（Stop Gate）：分析后必须等用户放行

Phase 1 结束时必须以分析报告向用户汇报并等待放行（go）。只有用户已在请求中明确给出放行（如"do it"、"fix it and commit"、"implement with Sonnet"）时才可跳过。两个重要细节：

• 为分析给出的 go，不等于为实现的 go；
• 首轮通过的 go，不会延续到 Verify 失败后的重新诊断上——重入 Phase 1 会重新武装停止门，即使是一次 Verify 弹回，也不是继续无人值守实现的长期授权。

四、Phase 1 — Analyze：先复现，后归因

analyze.md 规定无论任务从何而来（Issue 链接、PR 编号、口头想法、缺陷报告），都要从这里开始，但有两个更锐利交付物的例外入口（见后文"特殊入口"）。本阶段不写任何代码。

收集完整上下文：用gh issue view <n> --comments/gh pr view <n> --comments获取 Issue/PR 及其全部评论和关联链接；对想法类请求用自己的话复述目标与约束，若有歧义当场解决；用git log -- <path>检查既有助手函数、类似模块与过往提交（prior art）。

先复现，再理论化：尽可能复现问题。一次成功的复现能把分析从"假设"变成"事实"，同时为 Phase 5 白送一个验证用例；当复现不可能（平台、硬件、凭据受限）时，必须在报告中显式说明，并把该修复标记为unverified-by-repro。

在代码里找根因：必须阅读真实实现，绝不只凭 Issue 文本、评审评论或堆栈追踪推断——报告与机器人评审经常是错的。要区分根因与症状：修复"在哪崩溃"不等于修复"为什么崩溃"。报告应说明改动应是什么、触及哪些文件、刻意不碰什么。

何时升级：若根因无法置信地钉死，或修复看起来是架构级、安全敏感或不可逆的，就把这个具体问题交给最强可用模型，而不是靠猜。

本阶段产物：一份给用户的简短分析报告，包含：实际发生了什么及原因（根因 + 文件引用）、建议改动及其范围、刻意排除在外的内容、剩余未决问题。这对应 artifacts.md 中定义的root_cause/proposed_change/out_of_scope/repro_status/open_questions五个字段——无论任务从哪个入口进来，Plan 都以这个固定形状消费它。

五、Phase 2 — Plan：把批准的分析变成可执行计划

plan.md 的质量标尺是：实现者层级的模型必须能不提问地执行每个任务。

钉死规格（Pin the spec）：先写规格再委派，内容包括——已定方案（含已做的决策，避免实现者重新争论）、要改的文件与入口点、约束（风格规则、要遵循的既有模式、性能/兼容性要求）、覆盖本任务文件的语言/框架/格式技能（在写代码前加载并把规则复制进规格，否则验证时发现的违规只是返工）、验证命令、显式非目标（任务不得改什么）。

替换现有代码时的铁律：当改动替换的是可用代码（重写、移植、换引擎、换依赖）时，必须读代码而非读请求来枚举被替换代码当前的行为，并把该清单作为验收标准——快捷键、自动插入、默认值、错误消息全都算数。清单上任何打算丢弃的项，都是需要用户先放行的"移除"，而不是事后报告的"简化"。

样例数据的通用性：示例数据、演示夹具、随附默认值必须通用，绝不把某个真实用户或客户的数据提升为项目默认状态。

任务拆分与工作区：一个任务 = 一个实现者可独立完成并验证的自包含单元；标记独立任务与消费他人输出的任务，独立任务并行、其余串行——拿不准就串行，两个并行子代理的合并冲突成本大于并行省下的时间。文档更新属于改变行为的那个任务，不单列。工作区二选一：主工作树（任务依赖未提交的本地改动，或本会话要评审并提交结果）或隔离 worktree（其他一切情况，并行任务绝不共享工作树）。

合并规划：只要有并行 worktree，就必须在委派前定好集成步骤——分支按何顺序合并、由谁（协调者，在 Phase 4 集成时）执行合并并解决冲突。注意：隔离 worktree 的分支永远看不到另一任务的分支，因此永远无法也不该自行解决跨任务冲突。Verify（Phase 5）只在所有并行任务落地后的合并态上跑一次，绝不按分支跑——单任务的绿色运行不是门禁。

六、Phase 3 — Delegate：让执行者匹配任务，而非相反

delegate.md 的核心是成本与速度的平衡而不失质量，协调者对结果始终负责。

执行者矩阵：琐碎任务（机械编辑、配置微调、错字、文档更新）直接做或批量交给 trivial 层级模型；标准且规格明确的任务由协调者自己做或派给同层子代理以换取并行；命中升级触发器的任务，其那个具体问题交给 escalation 层级子代理——这是有界的一问一答，不是任务分派，也永远不出现在任务清单的executor_tier字段里（该字段只取 trivial、implementer、coordinator-direct）。

每次委派携带的内容：Phase 2 的完整钉死规格 + 必须跑通才能上报完成的验证命令 + "报告你改了什么、验证了什么"的指令 + "遇到规格未覆盖之处就停下报告，而不是即兴扩权"的指令。

永不向下委派的三件事：分析（Phase 1）、最终验证（Phase 5）、提交/历史重写/推送/面向用户的报告（Phase 6）。实现者的绿色运行只是"声称"，不是"结果"；提交等行为关乎问责而非能力，因此也不交给 Escalation 层级。

七、Phase 4 — Supervise：委派不是发了就不管

supervise.md 要求协调者跟踪交付并对结果负责。

先集成再评审：评审任何 diff 之前，合并态必须存在——确认本阶段等待的所有任务已按其依赖上报完成；按 Phase 2 钉死的merge_plan依序把各 worktree 分支合并回来，落在的冲突由协调者解决；只有所有并行任务都合并后，"已评审 diff"才成立，Verify 才在合并态上跑一次。无并行的单任务场景，合并步骤为空操作，待评审的就是该任务自身的改动。

监控与解阻：子代理停滞或打转时，停止它、自己诊断、把答案交给它继续，别让它反复消耗轮次；子代理报告规格缺口时，由协调者决定更新规格或砍掉范围，绝不让子代理自行决定范围。

批判性评审输出：把每个子代理 diff 当作外部 PR 来评审；即使协调者亲自执行（无子代理），也要对自己的 diff 做同等批判性检查。对照规格检查：该做的都做了、规格之外的没做。对错误或过度设计的方案行使覆盖权，偏好删代码而不是加代码——保留子代理的诊断但替换成更简单的修复是正常操作，要在最终报告中记录覆盖及其理由。还要警惕"符合规格但难看"的改动——与周围代码的一致性优先。

批判性评审新增测试：测试套件通过 ≠ 测试有用。子代理被要求加测试时倾向于过度产出，应裁掉三类：断言实现细节而非行为（指针/内存同一性、精确分配计数、内部调用顺序）的测试；钉死大段硬编码快照、只是镜像 diff 中已声明数据的测试（复制 map 的 key 到字面量列表再断言相等，是在重复源码而非独立验证）；以及同一 diff 中更精简测试已覆盖的不变量。保留真正检验改动所要保证的行为/不变量的测试——每个属性一个断言，而不是每个实现选择一个断言。

低置信度时升级、未验证不信任：若 diff 让你无法确定修复是正确还是"貌似正确"，或触及安全、数据迁移等不可逆领域，签字前找最强模型二读（escalate.md）。子代理说的"测试通过"是声称不是结果，Phase 5 会在合并态上独立地全部重验。

八、Phase 5 — Verify：质量门禁 + 功能实证

verify.md 强调：验证绝不向下委派，且在改动的最终合并态上运行，分两半：项目质量门禁与功能实证，默认都是协调者自己的工作。

质量门禁：构建、完整测试套件、格式化器、linter 全部零错误通过；手工对照 Phase 2 钉死的语言/框架技能逐条复查最终 diff，再跑各技能定义的门禁——linter 覆盖不了控制流、测试结构、日志、注释约定，绿色 linter 不等于技能被遵守；平台特定文件改动时要为每个目标平台交叉编译或重新 lint（本地工具链会跳过其他平台的规则）。

功能实证：测试通过是必要条件而非充分条件。要跑真实流程并确认具体输出：渲染提示符、执行命令、访问端点，记录观察到的实际值——最终报告引用这些值作为证据，而不是形容词。用用户实际触达的方式走流程（构建产物而非开发服务器、冷启动而非运行中的进程、用户真正打开的入口点）；涉及 dev server 或文件监视器时先重启再判断行为——陈旧 bundle 会产生"自信的错误验证"。用户说要自己做手工验证时，明确说出该检查什么、预期结果是什么。

高影响结果时升级：门禁与功能实证的运行留在协调者手中；若结果含糊，或改动是高爆炸半径（迁移、安全、不可逆操作），请最强模型评判证据再宣布完成。

失败处理：按"实际坏在哪"选目的地，而非按默认值——门禁失败（构建/测试/lint）或 diff 不符规格 → 回到 Phase 4（通过实现者修复），规格没错，是执行错了；功能实证与陈述的根因矛盾、或修复完全没改变观察到的行为 → 回到 Phase 1，规格建立在错误诊断上。重入 Phase 1 会重新武装其停止门：再次报告修订后的分析并等待放行。永不为了变绿而放宽门禁、跳过 linter 或删除测试。

重试上限（Retry Cap）：跨轮次没有内存，计数必须以文本形式携带，不能靠记忆。每次 Verify 失败，都要在交给下一阶段的报告中显式说明：本任务的尝试次数、坏在哪、目的地。"同一任务"指同一原始用户请求——Phase 1 弹回后的修订诊断仍是同一任务，不重置计数。同一任务连续第二次失败时，在第三次发回之前停止循环，把具体问题（修复为何落不了地、根因为何总抓偏）升级给 Escalation 层级；若升级答案之后的那个周期仍然失败，不再升级、也不第四次发回，彻底停止循环并向用户汇报：前两次尝试、升级的问题与答案、以及最新的失败证据。继续循环意味着工作流本身在此任务上不收敛，这个决定属于用户。

九、阶段间产物契约：没有产物就不算完成

artifacts.md 是全文的"骨架"：每个阶段边界都是一条边，每条边携带一个命名产物，"我搞完了这个阶段"而没有产物，不构成有效交接。

• Analyze → Plan：分析报告（root_cause/proposed_change/out_of_scope/repro_status/open_questions），三个入口必须产出完全相同的形状；
• Plan → Delegate：任务清单（每条含spec/verification_commands/executor_tier/workspace/dependencies/ 多任务 worktree 时的merge_plan）；
• Delegate → Supervise：委派包（规格 + 验证命令原样 + 常驻指令：报告改了什么、验证了什么，遇到规格缺口就停下报告而非即兴扩权）；
• Supervise → Verify：已评审 diff（merged_diff最终集成改动、overrides被替换的子代理方案及原因、tests_kept/tests_cut）；
• Verify → Supervise / Verify → Analyze：失败记录（attempt_number从 1 开始、failure_class门禁失败/规格不符或错误根因、destination、attempt_number到 2 且已咨询 Escalation 后才有escalation_answer）；
• Verify → Deliver：验证证据（gates_run只记 pass/fail、functional_proof真实观察值、retry_count）；
• Escalate：永远携带最小问题对——Question in（具体判断问题 + 相关代码/证据 + 迄今假设 + 不确定的原因），Answer out（决策及理由，控制权归还提问阶段，答案并入该阶段自己的产物）。

文档用一句犀利的话总结其价值：没有产物的阶段不是真的完成——这正是阻止"我看了下"悄悄冒充真实分析报告、并让 Verify 能把任务送回 Phase 1 或 Phase 4 而无须接收方猜测缺什么的关键。

十、特殊入口：Issue 分诊与 PR 评审意见

这两个是 Phase 1 的备选入口，不是独立轨道；每个仍必须产出同一个分析报告产物，Plan 无需知道任务从哪个门进来，后续 Phase 2–6 原样适用。

Issue 分诊（issue-triage.md）：当任务只是"看看 issue #n / 分诊 #n / #n 还有效吗"且未要求修复时使用，分析本身就是产品，实现仅在明确放行后发生。步骤：gh issue view <n> --comments读全报告与每条评论；复现报告行为（环境缺失时说明并从代码推理，标注为未复现）；在代码而非 issue 文本中定位根因（issue 描述的是症状，且常猜错原因）；评估爆炸半径（还有谁受影响、自哪个版本/提交引入、有无规避手段）。交付物：确认或无法复现（带证据）、根因（带文件引用）、建议修复及范围或无需修复的理由（works-as-intended / 重复 / 环境问题）、需要上传达人时的建议回复。同样映射到root_cause等五个字段。

PR 评审意见（pr-review-comments.md）：当任务是"处理 PR #n 上的评审意见"时，用它替换 Phase 1 的 Issue 分析；Phase 2–6 原样适用，包括停止门、合并态 Verify、Deliver 的推送策略。先取全部未解决评论（gh pr view <n> --comments或gh api），动任何东西前对照实际代码逐条验证，分类为有效/无效——自动评审者经常标记非问题，把它们当线索而非裁决。有效评论：按拥有该代码的提交规划修复（Phase 2），以git commit --fixup <sha>落在分支上（fixup 是工作态，还不是交付态），git rebase --autosquash折叠进目标提交，用git diff确认重写后的树与"重写前树 + 预期修复"字节级一致（改了其他任何东西就是进错了提交），在 rebase 后的树上跑完整质量门禁与功能实证。无效评论：不为其改代码，用证据反驳（代码路径、既有测试、验证过的行为）；若评论错了但暴露了真正的困惑点，就加固代码/注释对抗误读并在回复中说明。每个线程都要回复做了什么、如何验证，把解决线程留给人类。推送（含 force-push）遵循 Deliver 的推送策略：仅当用户要求时，重写分支用--force-with-lease。

十一、Phase 6 — Deliver：打包与报告

deliver.md 在验证完成后负责打包。提交必须使用 conventional-commit 技能的规范；一个提交一个逻辑单元，功能与其 lint 善后如果回答不同"为什么"可以分开提交；显式暂存文件，绝不用git add -A；提交前评审已暂存 diff（尤其自动修复工具改写过文件之后）。

推送与 PR 策略：除非用户要求，不推送、不 force-push、不开 PR——"commit" 就是 commit，仅此而已；在重写后的分支上推送时用--force-with-lease。

最终报告：结果优先，然后是证据：改了什么（带可点击文件引用）及为什么，一段话内说完；实现者输出在何处被覆盖及原因；验证证据（跑过的门禁与观察到的具体功能结果）；显式留给用户的尾巴（要删的密钥、手工验证步骤、延后的决策，各附适用的确切命令或检查项）；改动没做、但其标题暗示做了的事——若提交说"drop X"，说明 X 还剩什么、为什么；能力被移除或替换时，要命名为"移除"而非"简化"。绝不把未验证的步骤报成已完成，绝不把失败埋在成功故事中间。

十二、升级（Escalation）：有界的一问一答

escalate.md 强调：协调者默认拥有每个阶段；升级是对最强可用模型的一次有界子代理调用，只针对一个具体判断，不是阶段交接。协调者提出问题、拿到答案、仍是结果的责任人。

真实触发器（不是"任务很难"的模糊感觉）：读代码后根因仍无法置信地钉死；改动是架构级（跨模块边界、动公共 API/接口、引入横切抽象）；代码对安全/认证/加密/支付/数据迁移敏感；操作不可逆或高爆炸半径（schema 迁移、删除、force-push、生产配置）；同一任务的实现者不止一次报告规格缺口或矛盾（跟踪方式同 Verify 重试计数：每次在报告中显式说明）；Verify 连续第二次把同一任务弹回（两次失败意味着诊断不收敛，而非第三次会成功——该触发器每任务只触发一次，升级后的周期再失败就走 verify.md 的终局步骤：停止循环向用户汇报）；评审 diff 后无法确定修复正确还是仅貌似正确；用户明确要求第二意见或对抗性评审。

如何升级：提具体问题，不是整任务。交出回答问题所需的钉死上下文（相关代码、迄今假设、不确定的原因），拿到答案后恢复阶段。升级永远不会成为任务的新主人，也绝不决定范围。

十三、模型分层与多工具落地

model-tiers.md 给出四层模型映射（以文中快照为准，过时按层级替换）：Escalation 层（Anthropic Fable 5 / Opus 4.8，OpenAI Sol / GPT-5 (high)，Google Gemini 2.5 Pro）；Coordinator 层（Anthropic Sonnet 5，OpenAI GPT-5 / GPT-4.1，Google Gemini 2.5 Flash）；Implementer 层（与协调者同档）；Trivial 层（Anthropic Haiku 4.5，OpenAI GPT-4.1 mini，Google Gemini Flash-Lite）。Coordinator 与 Implementer 常是同一模型——区别在于并行与工作区隔离，而非能力。

工具映射（Claude Code / GitHub Copilot / Codex / IDE 代理各自怎么跑）：Claude Code 在 coordinator 层模型上开会话，仅在升级检查点用Agent+model: opus（或fable）限定在那个问题上，并行实现任务用 worktree 隔离，批量琐碎编辑用model: haiku；GitHub Copilot 全程用 coordinator 层模型跑 Copilot Chat，仅在升级触发的问题上切换到最强推理模型再切回，独立且规格明确的任务可指派给 Copilot 编码代理（钉死规格变成 issue 正文）；Codex 在 coordinator 层模型上本地编排，每个独立单元作为一个 Codex 云端任务下发，diff 自己评审，触发器命中才升级前沿模型；Cursor 等 IDE 代理每个任务一个 coordinator 层会话，后台代理跑并行实现，升级检查点在会话内临时切换最强模型。

完全没有子代理支持时：保留阶段、去掉并行——全程用 coordinator 层模型跑整个流程，仅在升级触发器命中的具体问题上把会话模型临时切到最强再切回。这套纪律在委派机制缺失时依然成立。

十四、实践要点总结

• 先分析后代码：一切任务从 Analyze 进入，分析永远是第一步；Phase 1 结束时必须停下等待用户放行，除非请求自带 go。
• 在合并态验证：Verify 只在所有并行任务合并后的最终状态上跑一次，功能实证要记录真实观察值，绝不以单任务绿跑充当门禁。
• 产物即交接：每个阶段边界必须有命名产物，阶段才能被可靠重入；计数（attempt_number、重试次数、规格缺口次数）必须以文本显式携带，因为跨轮次没有内存。
• 升级是例外：升级只在真实触发器命中时发生、只问一个具体问题、只借最强模型之脑、不交出阶段所有权；大多数任务应全程不触发升级。
• 失败要收敛：同一任务连续两次 Verify 失败即升级，升级后仍失败则停止循环向用户汇报——继续循环是用户的决定，不是又一次升级调用。

这套工作流已经固化在 oh-my-posh 仓库的 .agents/skills/code-changes/ 目录下，主文件 SKILL.md 是入口（含角色定义、流程总览、停止门与特殊用例），八个参考文件分别承载各阶段与配套机制的完整细则，可直接作为团队搭建 Agent 编码流水线的蓝本。

【免费下载链接】oh-my-poshThe most customisable and low-latency cross platform/shell prompt renderer项目地址: https://gitcode.com/GitHub_Trending/oh/oh-my-posh