从 Issue 到合并Remix 仓库的 fix-issue 技能与全流程 Bug 修复实践【免费下载链接】remixThe fully-stacked web framework项目地址: https://gitcode.com/GitHub_Trending/re/remix导读本文围绕 Remix 仓库AGENTS.md 中描述的 pnpm monorepo 项目产品代码主要位于packages/中用于修复 GitHub Issue 的 fix-issue 技能文档展开完整讲解其背后的工程化工作流从读取 Issue、验证复现、定位源码、编写失败测试到实现修复、创建 change 文件、提交 PR再到合并后更新 tracking issue 清单的九步闭环。读完本文你将掌握在 Remix 这类大型 monorepo 中「以 Issue 驱动、以测试为先」的规范修复流程以及仓库配套的测试、变更记录与 PR 编写技能的使用方式。一、技能定位它解决什么问题fix-issue是 Remix 仓库.agents/skills/目录下的一组维护类技能之一见 AGENTS.md 的 Repo Skills 清单其 SKILL.md 明确了适用场景当用户提供一个 GitHub Issue 链接并要求修复 Bug、调查问题、复现问题或完成某个 tracking issue 的一部分时Agent 应调用该技能走完「获取 Issue → 查找复现 → 编写失败测试 → 实现修复 → 在 tracking issue 清单上记录合并进度」的完整流程。技能元信息中带有disable-model-invocation: true意味着它不会被模型自动触发而是由使用者在需要修复 Issue 时显式引用。该技能与其姊妹技能write-tests、make-changes、make-pr、make-tracking-issue、review-pr、update-pr等共同构成 Remix 仓库的 Agent 协作规范本文聚焦其中的 Bug 修复主线。二、分支策略从干净的 main 开始技能规定所有 Bug 修复都必须从一个干净的工作树开始。如果当前工作区存在未提交的改动应提示用户先解决这些改动再继续后续流程。分支命名遵循{author}/{semantic-branch-name}的格式其中author是提交者开发者的 GitHub 用户名semantic-branch-name是几个有意义的、以连字符分隔的描述性单词。该约定同样体现在仓库根目录 AGENTS.md 的 GitHub 规范中示例mjackson/fix-flaky-bun-test以及技能中给出的示例brophdawg11/fix-route-pattern对应仓库中的packages/route-pattern包。git fetch origin main git branch {author}/{semantic-branch-name} origin/main git checkout {author}/{semantic-branch-name}修复基于main而不是任何功能分支目的是让每个 PR 保持最小、独立、易于评审。这与仓库make-pr技能中「优先单个干净提交」的原则一脉相承。三、工作流第一步获取并理解 Issue3.1 读取 Issue 的两种途径技能要求优先使用gh issue view number --repo remix-run/remix读取完整 Issue当gh不可用或不便时可用WebFetch读取。需要从 Issue 中提取的信息包括Bug 描述、期望行为与实际行为Remix 版本以及涉及的包如remix/router、remix/route-pattern、remix/cliIssue 中的代码片段复现链接StackBlitz、CodeSandbox、GitHub 仓库等实施计划复选框以及已勾选项上关联的已合并 PR。3.2 区分普通 Issue 与 Tracking Issue如果 Issue 包含实施计划复选框implementation-plan checkboxes它就是一个tracking issue其清单是持久的进度记录。处理时有三个铁律不要重做已勾选的工作。当 PR 状态重要时用gh pr view number --repo remix-run/remix --json state,mergedAt,url确认关联 PR 的状态为当前 PR 选择一组连贯的未勾选项。不要为了完成整个 Issue 而盲目扩大 PR——长计划可能需要多个 PR 才能完成明确说明当前 PR 打算完成哪些清单项、哪些留给后续。四、工作流第二步验证复现按复现素材的形态分三种处理路径在线沙箱StackBlitz / CodeSandbox用WebFetch读取沙箱 URL 并提取相关代码识别触发 Bug 的精确事件序列。GitHub 仓库链接用WebFetch从 raw GitHub URL 读取关键文件package.json、相关源文件识别复现的架构——routes、router、middleware、controllers、components 等。没有复现链接先用gh issue view number --repo remix-run/remix --comments检索 Issue 评论寻找评论中的代码片段如果仍然没有则向用户提问「没有提供复现。你能分享一个最小复现或粘贴相关代码吗」复现验证是修复质量的基石——无法稳定复现的 Bug 无法被测试约束也就无法确认修复是否真正生效。五、工作流第三步定位受影响代码技能明确了 Remix 仓库的源码组织方式这与根目录 AGENTS.md 的 Repo Shape 完全一致Remix 是 pnpm monorepo大多数产品代码位于packages/name/src/每个包的exports条目都映射到一个顶层src/*.ts文件例如 route-pattern 包的 package.json 中./href、./match、./join、./specificity分别对应src/href.ts、src/match.ts等实现代码位于src/lib/子目录中使用Grep、Glob和 LSP 工具追踪相关代码路径并定位所属包。例如packages/route-pattern/src/下就是顶层入口href.ts、join.ts、match.ts、route-pattern.ts、specificity.ts加lib/实现目录的结构。跨包修复原则如果 Bug 跨越多个包优先在「所属包」owning package中修复避免在另一个包中重新导出该修复。这与 AGENTS.md 的跨包边界规范不从其他包重新导出 API 或类型直接从所属包导入互为印证。六、工作流第四步编写失败测试TDD 核心6.1 测试的组织与运行方式测试与源码同目录共存遵循src/**/name.test.ts的命名模式并且直接从源码运行、无需构建步骤见 AGENTS.md 与 write-tests 技能。写入测试前应先观察邻近测试文件的写法并遵循 write-tests 技能中的约定。运行单个测试文件在所属包内cd packages/package pnpm test src/**/filename.test.ts或使用 changed-workspace 运行器默认与origin/main做 diff且当 head-ref 为HEAD时包含未提交的工作树改动pnpm run test:changed从 scripts/run-changed-workspaces.ts 的源码可以看到getChangedFiles同时收集三部分改动baseRef...headRef之间的 diff、HEAD上的未提交改动git diff HEAD、以及未跟踪的新文件git ls-files --others --exclude-standard。这也解释了技能中「包含未提交改动」的表述。此外该脚本还会检测共享根文件的变更如果根级共享文件变化会触发全仓运行run-changed-workspaces.ts。6.2 测试风格根据 write-tests 技能与根 package.json 的测试脚本pnpm --recursive --workspace-concurrency4 --stream run test仓库默认采用describe/it风格包级测试默认使用remix-run/test与remix-run/assert例如 packages/remix/package.json 的test: remix test只有作为remix-run/test依赖的包才回退到node:test与node:assert/strict。6.3 失败测试的标准技能强调写出的测试必须精确复现 Bug且必须在修复前失败。写完先运行并确认其失败这是 TDD 的红灯阶段也是后续验证修复有效性的基准。七、工作流第五步实现修复7.1 最小改动原则只做修复 Bug 所需的最小改动不重构无关代码确认修复针对根因而非症状遵循平台立场优先使用 Web API 与标准对齐的基元而非 Node 特定 API与 AGENTS.md 的 Platform stance 一致不在src/lib中添加跨包重新导出或 barrel 文件。7.2 修复后的验证先重跑失败测试确认通过再做本地验证pnpm run lint pnpm run typecheck:changed pnpm run test:changed对于广泛的跨工作区改动、共享根配置改动或任何可能影响整个仓库的改动需要跑全量验证pnpm test pnpm run typecheck仓库根 package.json 提供了这些命令的定义test为全仓递归测试test:changed与typecheck:changed走 changed-workspace 运行器lint使用 oxlint--max-warnings0。八、工作流第六步创建 change 文件如果修复影响用户user-facing需在packages/package/.changes/下按需创建目录并添加 change 文件。技能明确指示使用 make-changes 技能来生成不要在这里重新推导命名、bump 规则或内容规则。change 文件的关键规则源自 make-changesBump 规则0.x包的 Bug 修复是patch1.x包遵循标准 semver。例如 route-pattern 包的 package.json 版本为0.24.0其 Bug 修复对应patch命名packages/package/.changes/[major|minor|patch].short-description.mdRemix 导出变更对于remix包的导出变更直接原地更新packages/remix/.changes/minor.remix.update-exports.md内容描述用户可见行为、公开 API 变化、导出、迁移或升级工作Bug 修复要描述用户可见的症状或失败场景而非仅描述实现层面的改动。变更记录可验证方式运行pnpm changes:preview检查渲染后的 changelog 输出。九、工作流第七步汇报结果修复完成后汇报应覆盖Bug 是什么、为什么会发生改了什么代码、为什么这样改测试现在已通过注意到的任何边界情况或相关问题对于 tracking issue本次 PR 完成了哪些清单项、哪些仍留待后续。随后请用户评审改动并根据反馈迭代。十、工作流第八步提交并打开 PR在用户批准修复后提交改动并向main打开 PR使用 make-pr 技能生成 PR 正文与命令并在 GitHub 的 Development 侧边栏关联 Issue。PR 描述中的关联关键字有严格要求普通 Issue在描述中包含Closes #NNNNTracking issue使用Part of #NNNN代替只要还有任何实施计划复选框未勾选就绝不使用关闭关键字。从 make-pr 可以看到实际的创建命令形态gh pr create --base main --head branch --title title --body-file file以及 PR 正文模板1-2 段简短引言 关键行为/API 变化要点 功能变更的用法示例新功能给用法片段替代方案给 before/after 示例并省略Validation、Testing等冗余章节。十一、工作流第九步记录已合并的 Tracking-Issue 进度这是整个工作流中最严谨的一环核心原则是只在对应 PR 合并之后才更新 tracking issue。用gh pr view number --repo remix-run/remix --json number,url,state,mergedAt确认 PR 的mergedAt非空编辑前立即重新获取 Issue 正文以保留并发进度对 PR 完全完成的每个清单项保留原措辞把[ ]改为[x]并追加指向已合并 PR 的 Markdown 链接例如(#1234)如果已合并的 PR 只是推进了某项但未完成追加 PR 链接但保持未勾选只有陈述的结果完全达成时才勾选并纳入所有记录该完成工作的已合并 PR用gh issue edit number --repo remix-run/remix --body-file file编辑 Issue再用gh issue view读回验证清单、链接与 Issue 状态。关闭 tracking issue 的边界条件同样严格仍有未勾选项时保持 Issue 打开并报告剩余项供其他 Agent 接续关闭前再次获取正文扫描未勾选任务项若全部勾选还要验证每项都链接到完成它的已合并 PR然后才用gh issue close显式关闭。绝不关闭带未勾选实施计划框的 tracking issue。如果工作流在 PR 合并前结束保持其复选框未勾选并报告合并后更新 tracking issue 仍属必需不得将 open、draft 或已关闭但未合并的 PR 当作已完成工作引用。十二、配套技能生态与仓库证据fix-issue 是 Remix 仓库 Agent 协作体系的一环。整理其依赖的配套技能与仓库证据如下环节配套技能仓库证据仓库结构约定—AGENTS.md测试编写write-tests测试与源码同目录、从源码运行变更记录make-changespackages/package/.changes/*.mdPR 创建make-prgh pr create body-file跟踪清单维护make-tracking-issue勾选[x] 合并 PR 链接变更运行器—scripts/run-changed-workspaces.ts根级命令—package.json这种「问题驱动、测试约束、最小修复、变更可追溯、进度可持续」的工作流保证了在数百个包构成的 monorepo 中每个 Issue 的修复都能被独立评审、独立发布、独立记录也保证了多个 Agent 可以接力处理同一个大型 tracking issue 而不会相互覆盖进度。结语fix-issue技能文档为 Remix 仓库定义了一条从 Issue 到合并的完整、可复现的修复路径。它的价值不仅在于具体的gh命令更在于其工程纪律干净的基线分支、可验证的失败测试、根因级的最小修复、面向用户的 change 文件、严格的 PR 关联关键字以及合并后才更新的进度清单。这些约定与仓库的 AGENTS.md、package.json、write-tests、make-changes、make-pr 等仓库文档相互印证构成了 Remix 开源协作的完整图景。对于任何希望在大型 monorepo 中建立规范 Issue 修复流程的团队这套工作流都提供了可借鉴的范本。【免费下载链接】remixThe fully-stacked web framework项目地址: https://gitcode.com/GitHub_Trending/re/remix创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
