Mastra Codeunderstand-issue技能详解八阶段 GitHub Issue 协作调查与根因诊断方法论【免费下载链接】mastraMastra is the modern TypeScript framework for AI-powered applications and agents.项目地址: https://gitcode.com/GitHub_Trending/ma/mastra本文以仓库 .mastracode/skills/understand-issue/SKILL.md 为骨架结合 Mastra 仓库中与之配套的understand-pr、triage-issue、gh-triage、gh-bulk-issues等技能与命令系统拆解如何用 AI Agent 严谨地调查一个 GitHub Issue。读者将掌握一套可落地的八阶段调查流程从识别问题、检索历史、追踪代码路径到形成有证据支撑的根因判断、产出结构化的 UNDERSTANDING 文件并最终决定是否回帖 GitHub——全程遵循不猜测、只追踪、证据驱动、用户主导的原则。一、为什么需要一个专门的理解问题技能Mastra 是一个现代 TypeScript AI 应用与 Agent 框架monorepo 规模庞大仅packages/core就包含数千个源码文件Issue 往往横跨 Agent 执行循环、工作流引擎、消息持久化、流式输出、存储抽象等多个高耦合模块。直接读一眼问题就下结论的排查方式很容易把现象当根因或在 XY 问题上浪费大量时间。因此 Mastra Code仓库的 AI 编码助手体系在 .mastracode 目录下沉淀了一整套技能skill与命令command其中understand-issue专门负责Issue 调查与诊断triage-issue.mastracode/skills/triage-issue/SKILL.md负责首接触分类与路由一旦判定需要技术调查就把任务交给understand-issuegh-triage.mastracode/commands/gh-triage.md是维护者生命周期管理命令在 Review 阶段通过--working-file向understand-issue交接调查上下文understand-pr.mastracode/skills/understand-pr/SKILL.md是与它配套的 PR 审查技能共享同样的先理解后判断方法论gh-debug-issue.mastracode/commands/gh-debug-issue.md与critique-pr.mastracode/commands/critique-pr.md已因把问题理解、复现规划、测试、修复混在一条长流程里而被废弃明确被understand-issue/understand-pr取代——这本身就是该技能设计合理性的注脚。understand-issue的定位一句话即可概括和用户一起调查一个 GitHub Issue 或缺陷——追踪相关代码的历史、理解涉及的架构并共同判断该 Issue 是否成立、真正的原因是什么。目标不是给出一个猜测而是让 Agent 与用户都获得真正的理解。二、设计基调密集、简短、字母选项驱动的协作协议技能开篇就立下三条交互约定全文所有阶段都遵守禁止输出文字墙回复应当短小、密集、信息量大尽量减少废话直截了当。节奏控制Phase 1–3 是纯研究阶段必须主动一口气做完、不中途停下来等用户输入第一次暂停点是 Phase 4诊断此时才把发现与判断呈现给用户做协作校验。Shell 注意事项gh命令输出常含 ANSI 颜色码会破坏管道到jq的解析。要么使用gh内建的--jq参数要么在命令前加NO_COLOR1前缀。这套约定贯穿始终几乎所有交互点都以A/B/C/D字母选项收尾用户只需回复一个字母即可推进或转向。三、Phase 1识别问题Identify the Issue调查的第一步是搞清楚我们在调查什么。输入解析与 working-file从$ARGUMENTS中解析 Issue 输入与可选的--working-file path。若存在--working-file先验证文件存在并读取它把它当作调用方提供的上下文遵循其中的交接handoff指令并在返回调用方之前把发现写回同一个文件。该文件不是最终面向用户的输出如果文件不存在告知用户并结束。绝不未经明确批准就发表评论GitHub 评论是一种对外副作用。用户可能提供三种输入输入形式处理方式GitHub Issue 编号或 URL用gh issue view number --json title,body,labels,comments,assignees,state,author拉取元数据一段缺陷/异常行为描述无 Issue直接按描述调查什么都没有检查当前分支名git branch --show-current若包含疑似 Issue 编号如fix/1234、issue-567、bug/gh-890、feat/add-thing-1234提取后用gh issue view number确认其存在能解析就用解析不了就继续如果连调查对象都不明确直接请用户澄清不要猜测。人员画像People同一份 Issue 由谁提出、谁评论、谁认领直接决定你该用多重的怀疑态度去读它Issue 作者检查其合并 PR 数与 Issue 数。首报新手与核心贡献者的报告解读方式完全不同——贡献者可能熟悉内部实现新用户可能只是在描述另一个根因的症状。gh pr list --author user --state merged --limit 100 --json number --jq length gh issue list --author user --state all --limit 100 --json number --jq length评论者通读 Issue 线程上的所有评论。任何提出原因、变通方案或诊断的人同样核查其合并 PR 数。维护者的我认为这跟 X 有关是值得追踪的强线索用户带着略微不同复现步骤的me too可能暴露更广的模式。认领人Assignees留意谁被指派了任务、是否发表过评论。Issue 摘要与质量门槛内部记录此处不暂停报告的问题是什么、复现步骤如有、预期与实际行为、错误信息/日志/截图以及线程线索——评论者提出的每个可能原因、变通方案、相关代码路径都要记下作为 Phase 3 的调查线索。质量门槛自检三问问题是否清晰到可以调查是否有复现步骤或至少明确的症状描述预期行为是否被陈述若 Issue 过于模糊停下并直说——可以提议继续调查、代拟一条索要更多信息的评论、或者直接停止。四、Phase 2相关 Issue 与既往工作Related Issues Prior Work在钻进代码之前先确认这事以前是否出现过# 搜索相关 Issue含已关闭的——可能是回归 gh issue list --search keywords --json number,title,state,labels --limit 20 gh issue list --search keywords --state closed --json number,title,state,labels --limit 20 # 搜索触及同一区域的 PR gh pr list --search keywords --state all --json number,title,state --limit 20发现结果会与 Phase 3 的结论一并呈现。若出现明确的回归或重复项要显著标注。但不要在此停下——直接进入 Phase 3。这一步的价值在于给后续诊断提供历史先例证据链例如 .mastracode/resources/CRITICAL_PATHS.md 中提及的 deployer 构建管线问题社区 PR 几乎总会破坏生产构建见 #18930正是这类历史经验的固化。五、Phase 3初步调查Initial Investigation从症状出发追踪进代码库。起点是 Issue 描述中的错误信息、函数名、组件名或关键词。追踪三步用 Issue 中的关键词搜索对应代码追踪涉及的代码路径——从入口点顺着执行流走到出问题的地方找出所有可能贡献问题的区域——不止最明显的那一个。要思考共享状态、上游数据、配置、竞态条件、调用方的边界情况。每个区域的三个深挖问题对识别出的每个贡献区域当场建立真正的理解不要推迟到 Phase 4。每个区域都要能回答三个问题1. 这段代码为什么存在它最初要解决什么问题加入之前代码库是什么样git log --oneline -20 -- file # 近期提交历史 git log --oneline --all -20 -- file # 跨分支活动 git blame file # 具体行是谁、何时写的、提交信息说明了什么还要读提交信息里关联的 PR/Issue看 PR 描述与讨论而不只是提交标题理解原始动机。2. 它在架构上如何契合与其他代码的关系如何谁调用它它调用谁追踪调用方与被调用方什么数据流过它、数据来自哪里它依赖或暴露了哪些契约/接口是否有其他特性共享相同的底层原语配置、状态、实例。3. 各区域之间如何关联贡献区域不是孤立的它们是否共享状态、配置对象或实例一个区域的设计是否假设了另一个区域的某种行为一个区域的改动是否打破了另一个区域的假设绘制区域间的依赖/数据流。以 Mastra 为例.mastracode/resources/CRITICAL_PATHS.md 里列出的路径就是这套架构感的浓缩packages/core/src/loop/loop.ts是核心 Agent 执行循环排序、流式、工具调用、恢复行为都汇聚于此packages/core/src/agent/message-list/state/**追踪消息来源与持久化状态出错会重复、丢失或损坏消息packages/core/src/agent/save-queue/**是消息的有序异步持久化竞态会导致数据丢失。调查时带着这种哪个模块改动会引发什么连锁后果的地图能显著加快定位。呈现阶段把找到的贡献区域连同历史、架构与相互关联一起呈现——不是这段代码存在而是这段代码 N 个月前为解决 X 而写最近被 Y 为修复 Z 而改当前设计假设 W并与区域 2 共享同一配置实例。然后直接进入 Phase 4不在此暂停。六、Phase 4诊断Diagnosis——本技能的核心关口这是最关键的阶段。研究已做完现在要形成观点并交给用户做协作校验。目标共同确定两件事这个 Issue 是否像它表现的那样成立真正的原因到底是什么第一步Issue 本身是否成立动手诊断技术原因之前先评估 Issue 的框定是否正确考虑五种可能性可能性含义XY 问题报告者要 X 但其实需要 Y真正的问题完全在别处配置/用户错误行为符合设计用户只是需要换一种配置方式文档缺口行为合理但文档没解释清楚导致困惑按设计工作是报告者没预料到的预期行为真实缺陷代码确实做错了什么明确陈述你的评估。如果认为 Issue 被错误框定要有证据地说出来。第二步原因是什么若因果链清晰唯一明显的原因链直接说明并给出标准化决策模板Based on the investigation, I think this is [genuine bug / config issue / docs gap / XY problem]. Heres whats happening: [concise explanation of the causal chain, grounded in the code and history you traced]. [areas with history context, showing how they connect] Do you agree? A) Yes, that matches what Im seeing B) Im not fully convinced — I think [specific part] might be different C) I dont agree — I think the cause is more in the direction of [X] D) I need to see more evidence before I can form an opinion若存在真正的歧义多个 plausible 原因或你自己也不确定呈现候选方案让用户帮助收窄I see [N] possible explanations for this: 1. **[area/explanation]** — [history architecture context]. This would mean [implication]. 2. **[area/explanation]** — [history architecture context]. This would mean [implication]. Im leaning toward [N] because [reason], but Im not confident. Whats your read? A) I think its [1] — lets dig deeper there B) I think its [2] — lets dig deeper there C) I think its something else — [user explains] D) I need to see more code before I can tell关键原则先形成自己的观点但在断言之前先问用户的观点。我已经有了观点但想先听听你的完全没问题。不要做墙头草——如果用户不同意你的评估而你有证据要有礼貌地坚持。七、Phase 5深度探索交互式循环按需如果 Phase 4 没有解决诊断——存在真正歧义、用户不同意、或需要更多证据——就进入交互式探索。每个区域仔细读代码——它做什么、为什么、边界情况、契约检查相关路径的测试覆盖形成假设并用证据呈现This area was last changed in [commit] to fix [issue]. The current code assumes [X] but the reported bug suggests [Y] is happening instead. A) That sounds like the cause — dig deeper here B) Show me the test coverage for this path C) What changed recently that could have broken this assumption? D) I dont think this is it — lets try a different direction E) I want to look at something specific — let me tell you where选项要针对实际情况裁剪不要用万能选项。若多个区域交互导致问题要明说。循环重复直到原因清晰且双方认可。这与understand-pr.mastracode/skills/understand-pr/SKILL.md的 Phase 3-4 思路完全同构同样是一次一个逻辑区域呈现历史 定制化的跟进选项。八、Phase 6理解质量门槛Understanding Quality Gate收尾之前先确认调查真正产出了理解而不是表层猜测。呈现一份简明总结可能的根因不确定时给出首选候选支撑每个假设的证据仍未知或不确定的部分多个贡献区域时它们如何交互。然后检查A) That matches my understanding — write it up B) Im not convinced about [specific part] — lets revisit C) I think the cause is actually different — let me explain D) I dont have enough understanding yet — keep exploring只有用户确认真正理解了问题才能进入撰写阶段。九、Phase 7理解文件Understanding File调查结论落盘若提供了--working-file把完整调查与交接指令要求的任何输出写回同一文件然后返回调用方由它处理生命周期输出否则在工作区根目录写入.artifacts/understand-issue/UNDERSTANDING.md。文件必须捕获以下内容Issue报告了什么编号、标题、症状贡献区域每个被调查的区域含文件路径与相关历史根因分析可能的原因与证据我们如何走到这一步导致当前状态的历史——什么变了、何时、为什么开放问题任何仍不确定的部分相关 Issue/PRPhase 2 找到的既往相关工作链接。在定稿前把关键发现交互式地呈现给用户。十、Phase 8分享到 GitHub可选若存在--working-file默认跳过此阶段直接返回调用方因为评论/输出的生命周期由调用方管理。否则主动提议把分析发布到 GitHub IssueA) Post a summary of this analysis as an issue comment B) Ill handle it myself C) This issue needs more info first — help me draft a comment asking for clarification若用户选择发布先起草评论并请用户审阅再用gh issue comment number --body comment发布。评论要简洁有用——其他贡献者也会读它聚焦根因分析与证据而不是完整调查叙事。如果 GitHub API 速率限制较低gh api rate_limit --jq .rate用 REST API 回退gh api repos/{owner}/{repo}/issues/{number}/comments -f bodycomment十一、行为规则让调查不沦为猜测的七条铁律技能末尾的行为规则是整套方法论的价值观内核保持怀疑Be skeptical不急于下结论呈现证据让用户评估追踪而非猜测Trace, dont guess沿着真实代码路径与 git 历史走不先假设再找证据允许多因并存Multiple causes are validIssue 常由多个交互区域共同导致证据不支持就不要强凑单一根因简短回复Short responses密集信息 字母选项不灌水假设驱动Hypothesis-driven每个区域探索都以一个用户可确认、可拒绝、可细化的清晰假设收尾用户主导The user drives用户选择探索哪些区域、何时算理解充分不被固定流程推着走先听后说Form your own opinion, but present evidence first先呈现证据、问用户想法再分享结论。十二、在 Mastra 仓库协作生态中的位置understand-issue不是孤立的技能它与仓库里的其他命令/技能形成完整的维护工作流入口分流gh-triage.mastracode/commands/gh-triage.md在 Triage 阶段把 Issue 委托给triage-issue.mastracode/skills/triage-issue/SKILL.md做分类与路由当路由为Investigate issue #n时进入 Review 阶段创建.issue-review/GH_TRIAGE_ISSUE_number.md工作文件并激活Activate skill: understand-issue Arguments: issue number or URL --working-file .issue-review/GH_TRIAGE_ISSUE_number.md调查结束后回到gh-triage更新维护者 Triage NoteReview 状态、1/5–5/5置信度、最终审批人路由。并行批量修复gh-bulk-issues.mastracode/skills/gh-bulk-issues/SKILL.md为每个 Issue 建立独立 git worktree并行孵化 headlessmcmastracode实例首个提示词就是Activate the understand-issue skill for issue NUMBER即把先理解再动手作为每个修复 worker 的强制入口。关键路径守卫调查涉及 Agent 循环、工作流、存储等领域时.mastracode/resources/CRITICAL_PATHS.md 提供现成的敏感模块 → 负责人 → 原因映射例如packages/deployer/**与packages/core/src/loop/loop.ts对外部贡献者自动关闭并要求走 Issue 流程——调查这些区域时历史与所有权上下文一目了然。十三、结语把理解当作可执行的工程流程understand-issue的可贵之处在于它把先理解、再诊断、后行动这种本来依赖个人经验的软技能拆成了可执行、可验证、可交接的八阶段工程流程。Phase 1–3 强制完成信息收集Phase 4 强制形成观点并接受质疑Phase 6 强制用户确认理解Phase 7 强制产出结构化文件Phase 8 把结论以受控方式回流到 GitHub——每一步都有具体的gh/git命令、明确的 JSON 字段与固定的决策模板支撑。对维护者与贡献者而言这套方法论同样适用症状只是入口历史与架构才是证据。当你能说出这段代码三个月前为解决 X 而加、上周 Y 的修复破坏了它对 Z 的假设、它和区域 2 共享同一配置实例时你对这个 Issue 的理解——以及你的修复——才真正站得住脚。【免费下载链接】mastraMastra is the modern TypeScript framework for AI-powered applications and agents.项目地址: https://gitcode.com/GitHub_Trending/ma/mastra创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考 Mastra Code `understand-issue` 技能详解：八阶段 GitHub Issue 协作调查与根因诊断方法论
Mastra Codeunderstand-issue技能详解八阶段 GitHub Issue 协作调查与根因诊断方法论【免费下载链接】mastraMastra is the modern TypeScript framework for AI-powered applications and agents.项目地址: https://gitcode.com/GitHub_Trending/ma/mastra本文以仓库 .mastracode/skills/understand-issue/SKILL.md 为骨架结合 Mastra 仓库中与之配套的understand-pr、triage-issue、gh-triage、gh-bulk-issues等技能与命令系统拆解如何用 AI Agent 严谨地调查一个 GitHub Issue。读者将掌握一套可落地的八阶段调查流程从识别问题、检索历史、追踪代码路径到形成有证据支撑的根因判断、产出结构化的 UNDERSTANDING 文件并最终决定是否回帖 GitHub——全程遵循不猜测、只追踪、证据驱动、用户主导的原则。一、为什么需要一个专门的理解问题技能Mastra 是一个现代 TypeScript AI 应用与 Agent 框架monorepo 规模庞大仅packages/core就包含数千个源码文件Issue 往往横跨 Agent 执行循环、工作流引擎、消息持久化、流式输出、存储抽象等多个高耦合模块。直接读一眼问题就下结论的排查方式很容易把现象当根因或在 XY 问题上浪费大量时间。因此 Mastra Code仓库的 AI 编码助手体系在 .mastracode 目录下沉淀了一整套技能skill与命令command其中understand-issue专门负责Issue 调查与诊断triage-issue.mastracode/skills/triage-issue/SKILL.md负责首接触分类与路由一旦判定需要技术调查就把任务交给understand-issuegh-triage.mastracode/commands/gh-triage.md是维护者生命周期管理命令在 Review 阶段通过--working-file向understand-issue交接调查上下文understand-pr.mastracode/skills/understand-pr/SKILL.md是与它配套的 PR 审查技能共享同样的先理解后判断方法论gh-debug-issue.mastracode/commands/gh-debug-issue.md与critique-pr.mastracode/commands/critique-pr.md已因把问题理解、复现规划、测试、修复混在一条长流程里而被废弃明确被understand-issue/understand-pr取代——这本身就是该技能设计合理性的注脚。understand-issue的定位一句话即可概括和用户一起调查一个 GitHub Issue 或缺陷——追踪相关代码的历史、理解涉及的架构并共同判断该 Issue 是否成立、真正的原因是什么。目标不是给出一个猜测而是让 Agent 与用户都获得真正的理解。二、设计基调密集、简短、字母选项驱动的协作协议技能开篇就立下三条交互约定全文所有阶段都遵守禁止输出文字墙回复应当短小、密集、信息量大尽量减少废话直截了当。节奏控制Phase 1–3 是纯研究阶段必须主动一口气做完、不中途停下来等用户输入第一次暂停点是 Phase 4诊断此时才把发现与判断呈现给用户做协作校验。Shell 注意事项gh命令输出常含 ANSI 颜色码会破坏管道到jq的解析。要么使用gh内建的--jq参数要么在命令前加NO_COLOR1前缀。这套约定贯穿始终几乎所有交互点都以A/B/C/D字母选项收尾用户只需回复一个字母即可推进或转向。三、Phase 1识别问题Identify the Issue调查的第一步是搞清楚我们在调查什么。输入解析与 working-file从$ARGUMENTS中解析 Issue 输入与可选的--working-file path。若存在--working-file先验证文件存在并读取它把它当作调用方提供的上下文遵循其中的交接handoff指令并在返回调用方之前把发现写回同一个文件。该文件不是最终面向用户的输出如果文件不存在告知用户并结束。绝不未经明确批准就发表评论GitHub 评论是一种对外副作用。用户可能提供三种输入输入形式处理方式GitHub Issue 编号或 URL用gh issue view number --json title,body,labels,comments,assignees,state,author拉取元数据一段缺陷/异常行为描述无 Issue直接按描述调查什么都没有检查当前分支名git branch --show-current若包含疑似 Issue 编号如fix/1234、issue-567、bug/gh-890、feat/add-thing-1234提取后用gh issue view number确认其存在能解析就用解析不了就继续如果连调查对象都不明确直接请用户澄清不要猜测。人员画像People同一份 Issue 由谁提出、谁评论、谁认领直接决定你该用多重的怀疑态度去读它Issue 作者检查其合并 PR 数与 Issue 数。首报新手与核心贡献者的报告解读方式完全不同——贡献者可能熟悉内部实现新用户可能只是在描述另一个根因的症状。gh pr list --author user --state merged --limit 100 --json number --jq length gh issue list --author user --state all --limit 100 --json number --jq length评论者通读 Issue 线程上的所有评论。任何提出原因、变通方案或诊断的人同样核查其合并 PR 数。维护者的我认为这跟 X 有关是值得追踪的强线索用户带着略微不同复现步骤的me too可能暴露更广的模式。认领人Assignees留意谁被指派了任务、是否发表过评论。Issue 摘要与质量门槛内部记录此处不暂停报告的问题是什么、复现步骤如有、预期与实际行为、错误信息/日志/截图以及线程线索——评论者提出的每个可能原因、变通方案、相关代码路径都要记下作为 Phase 3 的调查线索。质量门槛自检三问问题是否清晰到可以调查是否有复现步骤或至少明确的症状描述预期行为是否被陈述若 Issue 过于模糊停下并直说——可以提议继续调查、代拟一条索要更多信息的评论、或者直接停止。四、Phase 2相关 Issue 与既往工作Related Issues Prior Work在钻进代码之前先确认这事以前是否出现过# 搜索相关 Issue含已关闭的——可能是回归 gh issue list --search keywords --json number,title,state,labels --limit 20 gh issue list --search keywords --state closed --json number,title,state,labels --limit 20 # 搜索触及同一区域的 PR gh pr list --search keywords --state all --json number,title,state --limit 20发现结果会与 Phase 3 的结论一并呈现。若出现明确的回归或重复项要显著标注。但不要在此停下——直接进入 Phase 3。这一步的价值在于给后续诊断提供历史先例证据链例如 .mastracode/resources/CRITICAL_PATHS.md 中提及的 deployer 构建管线问题社区 PR 几乎总会破坏生产构建见 #18930正是这类历史经验的固化。五、Phase 3初步调查Initial Investigation从症状出发追踪进代码库。起点是 Issue 描述中的错误信息、函数名、组件名或关键词。追踪三步用 Issue 中的关键词搜索对应代码追踪涉及的代码路径——从入口点顺着执行流走到出问题的地方找出所有可能贡献问题的区域——不止最明显的那一个。要思考共享状态、上游数据、配置、竞态条件、调用方的边界情况。每个区域的三个深挖问题对识别出的每个贡献区域当场建立真正的理解不要推迟到 Phase 4。每个区域都要能回答三个问题1. 这段代码为什么存在它最初要解决什么问题加入之前代码库是什么样git log --oneline -20 -- file # 近期提交历史 git log --oneline --all -20 -- file # 跨分支活动 git blame file # 具体行是谁、何时写的、提交信息说明了什么还要读提交信息里关联的 PR/Issue看 PR 描述与讨论而不只是提交标题理解原始动机。2. 它在架构上如何契合与其他代码的关系如何谁调用它它调用谁追踪调用方与被调用方什么数据流过它、数据来自哪里它依赖或暴露了哪些契约/接口是否有其他特性共享相同的底层原语配置、状态、实例。3. 各区域之间如何关联贡献区域不是孤立的它们是否共享状态、配置对象或实例一个区域的设计是否假设了另一个区域的某种行为一个区域的改动是否打破了另一个区域的假设绘制区域间的依赖/数据流。以 Mastra 为例.mastracode/resources/CRITICAL_PATHS.md 里列出的路径就是这套架构感的浓缩packages/core/src/loop/loop.ts是核心 Agent 执行循环排序、流式、工具调用、恢复行为都汇聚于此packages/core/src/agent/message-list/state/**追踪消息来源与持久化状态出错会重复、丢失或损坏消息packages/core/src/agent/save-queue/**是消息的有序异步持久化竞态会导致数据丢失。调查时带着这种哪个模块改动会引发什么连锁后果的地图能显著加快定位。呈现阶段把找到的贡献区域连同历史、架构与相互关联一起呈现——不是这段代码存在而是这段代码 N 个月前为解决 X 而写最近被 Y 为修复 Z 而改当前设计假设 W并与区域 2 共享同一配置实例。然后直接进入 Phase 4不在此暂停。六、Phase 4诊断Diagnosis——本技能的核心关口这是最关键的阶段。研究已做完现在要形成观点并交给用户做协作校验。目标共同确定两件事这个 Issue 是否像它表现的那样成立真正的原因到底是什么第一步Issue 本身是否成立动手诊断技术原因之前先评估 Issue 的框定是否正确考虑五种可能性可能性含义XY 问题报告者要 X 但其实需要 Y真正的问题完全在别处配置/用户错误行为符合设计用户只是需要换一种配置方式文档缺口行为合理但文档没解释清楚导致困惑按设计工作是报告者没预料到的预期行为真实缺陷代码确实做错了什么明确陈述你的评估。如果认为 Issue 被错误框定要有证据地说出来。第二步原因是什么若因果链清晰唯一明显的原因链直接说明并给出标准化决策模板Based on the investigation, I think this is [genuine bug / config issue / docs gap / XY problem]. Heres whats happening: [concise explanation of the causal chain, grounded in the code and history you traced]. [areas with history context, showing how they connect] Do you agree? A) Yes, that matches what Im seeing B) Im not fully convinced — I think [specific part] might be different C) I dont agree — I think the cause is more in the direction of [X] D) I need to see more evidence before I can form an opinion若存在真正的歧义多个 plausible 原因或你自己也不确定呈现候选方案让用户帮助收窄I see [N] possible explanations for this: 1. **[area/explanation]** — [history architecture context]. This would mean [implication]. 2. **[area/explanation]** — [history architecture context]. This would mean [implication]. Im leaning toward [N] because [reason], but Im not confident. Whats your read? A) I think its [1] — lets dig deeper there B) I think its [2] — lets dig deeper there C) I think its something else — [user explains] D) I need to see more code before I can tell关键原则先形成自己的观点但在断言之前先问用户的观点。我已经有了观点但想先听听你的完全没问题。不要做墙头草——如果用户不同意你的评估而你有证据要有礼貌地坚持。七、Phase 5深度探索交互式循环按需如果 Phase 4 没有解决诊断——存在真正歧义、用户不同意、或需要更多证据——就进入交互式探索。每个区域仔细读代码——它做什么、为什么、边界情况、契约检查相关路径的测试覆盖形成假设并用证据呈现This area was last changed in [commit] to fix [issue]. The current code assumes [X] but the reported bug suggests [Y] is happening instead. A) That sounds like the cause — dig deeper here B) Show me the test coverage for this path C) What changed recently that could have broken this assumption? D) I dont think this is it — lets try a different direction E) I want to look at something specific — let me tell you where选项要针对实际情况裁剪不要用万能选项。若多个区域交互导致问题要明说。循环重复直到原因清晰且双方认可。这与understand-pr.mastracode/skills/understand-pr/SKILL.md的 Phase 3-4 思路完全同构同样是一次一个逻辑区域呈现历史 定制化的跟进选项。八、Phase 6理解质量门槛Understanding Quality Gate收尾之前先确认调查真正产出了理解而不是表层猜测。呈现一份简明总结可能的根因不确定时给出首选候选支撑每个假设的证据仍未知或不确定的部分多个贡献区域时它们如何交互。然后检查A) That matches my understanding — write it up B) Im not convinced about [specific part] — lets revisit C) I think the cause is actually different — let me explain D) I dont have enough understanding yet — keep exploring只有用户确认真正理解了问题才能进入撰写阶段。九、Phase 7理解文件Understanding File调查结论落盘若提供了--working-file把完整调查与交接指令要求的任何输出写回同一文件然后返回调用方由它处理生命周期输出否则在工作区根目录写入.artifacts/understand-issue/UNDERSTANDING.md。文件必须捕获以下内容Issue报告了什么编号、标题、症状贡献区域每个被调查的区域含文件路径与相关历史根因分析可能的原因与证据我们如何走到这一步导致当前状态的历史——什么变了、何时、为什么开放问题任何仍不确定的部分相关 Issue/PRPhase 2 找到的既往相关工作链接。在定稿前把关键发现交互式地呈现给用户。十、Phase 8分享到 GitHub可选若存在--working-file默认跳过此阶段直接返回调用方因为评论/输出的生命周期由调用方管理。否则主动提议把分析发布到 GitHub IssueA) Post a summary of this analysis as an issue comment B) Ill handle it myself C) This issue needs more info first — help me draft a comment asking for clarification若用户选择发布先起草评论并请用户审阅再用gh issue comment number --body comment发布。评论要简洁有用——其他贡献者也会读它聚焦根因分析与证据而不是完整调查叙事。如果 GitHub API 速率限制较低gh api rate_limit --jq .rate用 REST API 回退gh api repos/{owner}/{repo}/issues/{number}/comments -f bodycomment十一、行为规则让调查不沦为猜测的七条铁律技能末尾的行为规则是整套方法论的价值观内核保持怀疑Be skeptical不急于下结论呈现证据让用户评估追踪而非猜测Trace, dont guess沿着真实代码路径与 git 历史走不先假设再找证据允许多因并存Multiple causes are validIssue 常由多个交互区域共同导致证据不支持就不要强凑单一根因简短回复Short responses密集信息 字母选项不灌水假设驱动Hypothesis-driven每个区域探索都以一个用户可确认、可拒绝、可细化的清晰假设收尾用户主导The user drives用户选择探索哪些区域、何时算理解充分不被固定流程推着走先听后说Form your own opinion, but present evidence first先呈现证据、问用户想法再分享结论。十二、在 Mastra 仓库协作生态中的位置understand-issue不是孤立的技能它与仓库里的其他命令/技能形成完整的维护工作流入口分流gh-triage.mastracode/commands/gh-triage.md在 Triage 阶段把 Issue 委托给triage-issue.mastracode/skills/triage-issue/SKILL.md做分类与路由当路由为Investigate issue #n时进入 Review 阶段创建.issue-review/GH_TRIAGE_ISSUE_number.md工作文件并激活Activate skill: understand-issue Arguments: issue number or URL --working-file .issue-review/GH_TRIAGE_ISSUE_number.md调查结束后回到gh-triage更新维护者 Triage NoteReview 状态、1/5–5/5置信度、最终审批人路由。并行批量修复gh-bulk-issues.mastracode/skills/gh-bulk-issues/SKILL.md为每个 Issue 建立独立 git worktree并行孵化 headlessmcmastracode实例首个提示词就是Activate the understand-issue skill for issue NUMBER即把先理解再动手作为每个修复 worker 的强制入口。关键路径守卫调查涉及 Agent 循环、工作流、存储等领域时.mastracode/resources/CRITICAL_PATHS.md 提供现成的敏感模块 → 负责人 → 原因映射例如packages/deployer/**与packages/core/src/loop/loop.ts对外部贡献者自动关闭并要求走 Issue 流程——调查这些区域时历史与所有权上下文一目了然。十三、结语把理解当作可执行的工程流程understand-issue的可贵之处在于它把先理解、再诊断、后行动这种本来依赖个人经验的软技能拆成了可执行、可验证、可交接的八阶段工程流程。Phase 1–3 强制完成信息收集Phase 4 强制形成观点并接受质疑Phase 6 强制用户确认理解Phase 7 强制产出结构化文件Phase 8 把结论以受控方式回流到 GitHub——每一步都有具体的gh/git命令、明确的 JSON 字段与固定的决策模板支撑。对维护者与贡献者而言这套方法论同样适用症状只是入口历史与架构才是证据。当你能说出这段代码三个月前为解决 X 而加、上周 Y 的修复破坏了它对 Z 的假设、它和区域 2 共享同一配置实例时你对这个 Issue 的理解——以及你的修复——才真正站得住脚。【免费下载链接】mastraMastra is the modern TypeScript framework for AI-powered applications and agents.项目地址: https://gitcode.com/GitHub_Trending/ma/mastra创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考