oh-my-posh 代码变更工作流之 Analyze 阶段：从 issue 到根因分析报告的方法论与实践

oh-my-posh 代码变更工作流之 Analyze 阶段从 issue 到根因分析报告的方法论与实践【免费下载链接】oh-my-poshThe most customisable and low-latency cross platform/shell prompt renderer项目地址: https://gitcode.com/GitHub_Trending/oh/oh-my-posh本篇技术指南以 oh-my-posh 仓库内置的code-changes技能.agents/skills/code-changes为蓝本系统讲解其中Phase 1 — Analyze分析阶段的完整方法论如何判定任务入口、收集上下文、复现问题、在源码中定位根因、判定是否需要升级以及产出被后续阶段直接消费的分析报告工件。读完本篇你将掌握一套可复用于任何代码变更任务bug 修复、feature 实现、重构、issue 分析的先分析、后编码工作纪律并能对照 oh-my-posh 的实际源码与测试结构落地执行。Analyze 在六阶段工作流中的定位code-changes工作流把从 issue / PR / 想法到落地代码的整个过程切分为六个有序阶段见 SKILL.mdAnalyzereferences/analyze.md— 根因与范围必须对照代码验证绝不对照报告本身。Planreferences/plan.md— 固化 spec、拆分任务、决定并行与串行、确定每个任务的工作区。Delegatereferences/delegate.md— 把每个任务匹配给合适的执行者。Supervisereferences/supervise.md— 监控、解阻、批判性评审执行者产出。Verifyreferences/verify.md— 在合并后的最终状态上跑质量门禁加功能证明绝不向下委托。Deliverreferences/deliver.md— 规范化提交与结果优先的报告。其中最重要的一条铁律写在 SKILL.md 第 12 行Analysis always comes first; code comes last分析永远先行代码最后落地。Analyze 阶段是这条铁律的第一道闸门而且本阶段不写、不改任何代码analyze.md 第 8–9 行明确 No code gets written or edited during this phase。工作流中还定义了四类角色Coordinator驻留的中等能力模型默认拥有所有阶段、Escalation最强推理模型仅在特定触发点被调用、Implementer执行单个固定 spec 的任务、Trivial处理机械性、无歧义的小编辑。具体到各厂商模型的映射可参考 references/model-tiers.md。Analyze 阶段由 Coordinator 拥有且分析、最终验证、交付三类工作永不向下委托给 Implementer。入口判定一条主路径与两条特例analyze.md 开篇references/analyze.md#L3-L9给出的核心论断是无论任务如何到达issue 链接、PR 编号、口头想法、bug 报告一律从 Analyze 开始只有两种例外会切换到更锋利的交付物入口适用请求说明references/analyze.md请求已隐含修复意图如 fix issue #n、issue #n: users cant log in分析与放行go同时存在直接走本文件不要走 issue-triagereferences/issue-triage.md纯 look at / triage issue #n未要求实现交付物只有分析本身实现必须等待显式 goreferences/pr-review-comments.mdhandle the review comments on PR #n用每条评论的有效/无效分类替代完整分析报告关键点是issue-triage 和 pr-review-comments 是替代性的 Phase 1 入口而非独立轨道——它们最终都必须产出与 analyze.md 完全一致的分析报告工件见下文本阶段输出这样 Plan 阶段永远不需要知道任务是从哪扇门进来的SKILL.md 第 71–77 行。收集完整上下文不要基于残缺信息开工分析的第一步是穷尽式收集上下文analyze.md 第 11–18 行给出了三类来源Issue 与 PR使用gh issue view n --comments或gh pr view n --comments读取完整报告、每条评论以及关联的 issue同时要顺藤摸瓜查看链接的 issues、被引用的 discussions以及报告所指向的任何代码。口头想法与模糊请求用自己的话复述目标与约束。如果请求有歧义在此时消除歧义而不是在实现进行到一半时才暴露。先例检查prior art查找已有的辅助函数、相似的 segment/模块以及历史上改动过同一区域的提交——对应命令是git log -- path。在 oh-my-posh 这个具体仓库里prior art的检索有非常现实的落点src/segments/下存放着 100 个 segment 实现如git.go、golang.go、python.go、kubectl.go每个实现都配套了*_test.go测试文件公共能力沉淀在src/generics/泛型工具、src/regex/、src/template/、src/runtime/、src/color/等包中。接到一个新增某工具链 segment或修复某 segment 显示异常的任务时先在这些目录里找同类实现与既有测试往往能直接复用或至少对齐既有模式避免从零发明。先复现再理论化analyze.md 第 20–24 行把复现放在理论化之前理由非常具体复现把分析从假设变成事实——一条只能停留在纸面上的推理远不如一次可重复的失败有价值。复现免费送给 Phase 5Verify一个验证用例——修复完成后用同一复现步骤检验即可直接证明行为改变。当复现确实不可能时平台、硬件、凭据缺失等客观限制必须在报告中明确声明并把修复标记为unverified-by-repro未经复现验证而不是假装验证过。对应到 oh-my-posh 的工程实践e2e/harness/目录提供了session.go、shells.go、script.go、binary.go等测试装备src/segments/下每个 segment 的单元测试与e2e/的端到端测试见 e2e/features_test.go都是现成的复现载体。对于 prompt 渲染类问题甚至可以直接运行二进制渲染当前配置来复现。在代码中定位根因症状 ≠ 根因这是 Analyze 阶段最核心的认知纪律analyze.md 第 26–32 行提出三条硬性要求读实际实现绝不只凭报告推理。Never reason from the issue text, a review comment, or a stack trace alone——报告与机器人评审经常是错的该文件原文reports and bot reviewers are frequently wrong。issue 文本描述的是症状且常常猜错原因只有实现代码是唯一可信的证据。区分根因与症状。Fixing where it crashes is not the same as fixing why it crashes——修崩溃发生的位置不等于修崩溃发生的原因。一个只把崩溃点兜住的补丁往往在另一个调用路径上再次崩掉。明确陈述变更内容、涉及文件、以及刻意不动的部分——即该改什么、改哪些文件、故意留下什么。以 oh-my-posh 的实际代码组织为例如果某个 segment 在特定 shell 下输出异常需要顺着src/segments/name.go→ 其依赖的src/runtime/terminal*.go分平台实现→src/color/或src/template/的渲染链路逐层核对若是平台相关问题还要注意terminal_unix.go、terminal_windows.go、terminal_js.go这类按 build tag 拆分的文件——本地工具链通常会跳过其他平台的文件分析时要有意识补齐。何时升级Escalate有明确触发条件不是默认路径analyze.md 第 34–39 行给出升级策略当无法高置信锁定根因或修复看起来架构性、安全敏感、不可逆时把那一个具体问题交给当前可用的最强模型而不是瞎猜——详见 references/escalate.md。escalate.md 定义了完整的触发条件清单包括但不限于读完代码后仍无法高置信锁定根因注意不是再读一遍报告之后。变更是架构性的跨越模块边界、触及公共 API/接口、引入横切抽象。代码涉及安全、认证、加密、支付或数据迁移敏感面。操作不可逆或高爆炸半径schema 迁移、删除、force-push、生产配置。同一任务上执行者不止一次报告 spec 缺口或矛盾。Verify 连续第二次把同一任务打回。评审 diff 后无法确定修复是正确的还是仅仅貌似合理的。关键的纪律是升级只是阶段内的一次有界 QA 调用绝不转移阶段所有权。Coordinator 负责提问具体判断、相关代码/证据、当前假设、为什么不确定拿到答案后把结论折回本阶段的工件例如升级答案成为root_cause的一部分并继续拥有整个阶段references/artifacts.md 第 80–89 行。本阶段输出一份按契约定型的分析报告Analyze 阶段结束时必须交付一份简短的分析报告给用户analyze.md 第 41–52 行规定了四块内容而 references/artifacts.md 第 8–18 行进一步把这四块定型为五个具名字段构成 Analyze → Plan 边界上的工件契约字段含义root_cause实际发生了什么、为什么附文件引用proposed_change建议的变更及其范围详细到足以据此拆任务out_of_scope刻意不做/不碰的部分repro_statusreproduced-with-evidence带证据复现或unverified-by-repro未复现附原因open_questions仍悬而未决的问题停止门放行后应为空artifacts.md 的核心理念是每个阶段边界都携带一个命名工件一个阶段没有产出其工件就不算真正完成——这正是阻止我查过了I looked into it冒充真实分析报告的机制artifacts.md 第 91–96 行。由于三个入口analyze / issue-triage / pr-review-comments都输出这一精确形状Plan 阶段无论任务来自哪扇门都能直接消费无需判断入口。停止门Stop gate报告之后必须等 goanalyze.md 第 54–60 行规定了整个工作流中最容易被忽略的纪律——停止门分析完成后先向用户报告分析结果等待 go 之后才进入实现。这条规则每次进入本阶段都适用包括从 Verify 失败返回的回头路见 references/verify.md 第 54–57 行而不仅仅是第一次。只有请求本身已经携带 go如 do it、fix it and commit、implement with Sonnet时才可跳过此门。go 的粒度不能混淆为分析给的 go 不等于为实现给的 go第一轮给的 go 也不会延续到 Verify 失败后的重新诊断。一次 Verify 反弹不是继续无人值守实现的长期授权——重新进入 Analyze 会重新武装停止门需要再次报告修订后的分析并等待新的 go。停止门与 verify.md 的重试上限配合形成闭环Verify 连续两次失败后不再循环第三次而是升级具体问题为什么修复迟迟落不了地若升级后的那一轮仍然失败则彻底停止循环并向用户报告前两次尝试、升级问题与答案、以及最新失败证据——继续循环意味着工作流本身在此任务上不收敛该决定属于用户而不是另一次升级调用references/verify.md 第 61–78 行。从 Analyze 到 Deliver 的完整闭环理解 Analyze 的价值需要看到它在下游链条中的作用Plan 基于分析报告固化 spec含验证命令与显式 non-goalsDelegate 把每个任务匹配到 Trivial / Implementer / Coordinator-direct 三档执行者之一Supervise 在并行任务全部合并后才产生被评审的 diff绝不按分支评审Verify 只在合并后的最终状态跑一次质量门禁与功能证明Deliver 遵循 conventional-commit 规范并在最终报告中先讲结果、再给证据references/deliver.md。在这条链条中Analyze 的输出质量直接决定后续所有阶段的收敛速度根因抓错Plan 的 spec 就建立在错误诊断上Verify 的功能证明必然打回 Phase 1verify.md 的 wrong-root-cause 分支范围没写清Implementer 就会在 spec 空白处自行发挥。因此在 oh-my-posh 这类大型 Go 仓库src/下数十个包、100 segment、多平台文件拆分上做任何代码变更先在 Analyze 阶段把上下文收集完整、把问题复现出来、把根因钉死在实现代码上、把范围边界划清楚、把停止门走完是成本最低、收益最确定的第一步。【免费下载链接】oh-my-poshThe most customisable and low-latency cross platform/shell prompt renderer项目地址: https://gitcode.com/GitHub_Trending/oh/oh-my-posh创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考