focused-fix

focused-fix skill 概览

focused-fix 适合解决什么问题

focused-fix 是一个面向系统化功能修复的工程类 skill。 当整个功能、模块、路由、工作流或集成链路出现问题，而你需要 agent 在改代码之前先追踪完整边界时，就适合使用 focused-fix。它主要用于 Debugging 场景：例如“修好登录流程”或“让账单导出恢复可用”这类任务，对单个 bug prompt 来说范围太大，但仍然需要一套聚焦的修复计划。

最适合的用户与场景

focused-fix skill 最适合在现有代码库中工作的开发者、技术负责人和 AI coding agents。它适用于端到端修复失败功能、在重构后恢复损坏模块、检查某个工作流的所有依赖，或把一个部分实现的区域整理到可上线状态。它不太适合从零设计新功能、快速修复语法错误，或处理孤立的一行缺陷。

这个工作流有什么不同

它的核心差异在于“先定范围，再做修复”的纪律性。focused-fix 不会让 agent 从表面症状直接跳到补丁，而是推动 agent 先梳理功能边界、检查依赖文件、理解测试和日志，然后把该功能作为一个相互连接的系统来修复。当可见错误只是 UI、API、状态、数据库、配置和测试之间更深层不一致的一个症状时，这一点尤其重要。

安装前需要注意的取舍

如果你希望获得更慢但更完整的修复行为，可以安装 focused-fix。不要把它当作轻量级 Debugging 捷径来安装。上游 skill 主要集中在 SKILL.md 中，看起来并不附带 helper scripts、reference packs 或额外规则文件，因此它的价值主要来自协议本身的质量，而不是外围工具。

如何使用 focused-fix skill

focused-fix 安装与仓库检查

在兼容 Claude Skills 的环境中使用以下命令安装：

npx skills add alirezarezvani/claude-skills --skill focused-fix

安装后，先阅读 engineering/skills/focused-fix/SKILL.md 中的源文件。仓库预览显示这个 skill 基本是自包含的，因此使用前没有大型支持目录需要额外检查。如果你的 skill runner 会展示已安装 skill 的元数据，请确认描述仍然指向功能/模块修复，而不是快速处理单个 bug 的 Debugging。

skill 需要哪些输入才能发挥效果

较弱的 prompt 是：“Fix checkout.” 更适合 focused-fix 的使用方式，是明确功能边界、预期行为、实际故障、相关命令，以及已经知道的文件或日志。

示例：

Use focused-fix for Debugging the checkout flow. Expected: guest users can add an item, enter shipping, pay with Stripe test card, and see an order confirmation. Actual: payment succeeds in Stripe but no order appears in the app. Start with apps/web/src/checkout, apps/api/src/orders, packages/payments, and the failing test checkout.e2e.ts. Do not patch until you have mapped the full flow and identified every dependent file.

这样的输入既给了 skill 足够的范围，避免随机改动，又能把修复边界控制住。

推荐的 focused-fix 工作流

当任务值得深入排查时使用 focused-fix：

1. 说明要修复的功能或模块。
2. 用可观察的方式定义“正常工作”：测试通过、用户路径完成、API 返回预期数据、日志不再出现已知错误。
3. 要求 agent 在编辑前先梳理功能边界。
4. 提供测试命令、复现步骤、近期重构信息，以及已知高风险文件。
5. 要求在代码修改前先给出简短修复计划。
6. 修改后要求提供验证证据：已运行的测试、已检查的日志、已验证的手动路径，或列出剩余缺口。

这个流程与 skill 的目标一致：先完成调查，再决定如何修复。

提升结果质量的 prompt 模板

调用 focused-fix skill 时可以使用这个模板：

Use focused-fix on [feature/module].
Goal: [what must work end-to-end].
Current failure: [symptoms, errors, logs, failing tests].
Scope hints: [directories, services, routes, configs, data models].
Constraints: [do not change public API, preserve backward compatibility, avoid migrations, etc.].
Validation: [commands or manual checks that prove the feature works].
Before editing: map the boundary and explain likely dependency points.

其中 constraint 和 validation 两行尤其重要。它们可以防止 agent 通过改变你实际上需要保留的行为来“修好”表面症状。

focused-fix skill 常见问题

focused-fix 只适合 Debugging 吗？

它主要是一个用于 Debugging 和修复的 focused-fix skill，但目标范围比单个 stack trace 更宽。适合在某个功能区域损坏、需要追踪依赖关系时使用。如果你已经知道确切出错行，并且改法很明显，普通 coding prompt 或更小型的系统化 Debugging skill 可能更快。

focused-fix 和普通 prompt 有什么不同？

普通 prompt 往往会优化成快速打补丁。focused-fix skill 会让 agent 更偏向按顺序调查：定义范围、检查相关文件、理解依赖，然后修复。这能降低“眼前测试通过了，但功能的其他部分仍然坏着”的局部修复风险。

focused-fix 对新手友好吗？

友好，前提是你能描述损坏的功能并运行验证命令。新手可能会受益于它的结构化方式，因为它会要求 agent 在改代码前解释功能边界。不过你仍然需要认真审查改动，尤其是涉及 authentication、payments、data migration、permissions 或 production configuration 的区域。

什么时候不该使用 focused-fix？

不要把 focused-fix 用于很小的缺陷、格式修复、依赖升级、大范围架构重设计，或“improve the app”这类模糊请求。当你无法提供可复现故障、预期行为，或无法让 agent 访问足够的仓库上下文时，它的效果也会变差。这个 skill 最擅长的问题，是范围明确但内部依赖相互连接的修复任务。

如何改进 focused-fix skill 的使用效果

首次运行前先改进 focused-fix 输入

改进 focused-fix 结果的最佳方式，是提供更清晰、更丰富的边界信息。根据需要包含用户旅程步骤、API endpoints、background jobs、database tables、feature flags、environment variables 和 test names。如果你知道某次近期 merge 或 refactor 很可能导致了问题，也要明确说明。这样 agent 会检查正确的依赖图，而不是扫描整个仓库。

留意常见失败模式

常见失败模式包括范围蔓延、过早修改、过度适配某一个 failing test，以及忽略配置、seed data、permissions、queues 或 client/server type mismatches 等隐藏依赖。如果 agent 在完成范围梳理前就开始打补丁，及时打断并重申：“Complete the scope map first; no fixes until the full path is understood.”

第一次修复后继续迭代

第一次输出后，不要止步于“tests pass”。要求 agent 给出简洁的变更摘要、涉及文件、已执行的验证和剩余风险。然后运行你自己的检查，并把任何新错误按实际观察结果反馈回去。focused-fix 最适合作为一个循环来使用：界定范围、修复、验证、收紧范围；只有证据表明仍有故障时，才再次修复。

补充项目专属指导

如果会反复使用，可以把 focused-fix 和本地仓库说明配合起来。加入偏好的 test commands、code ownership boundaries、logging conventions、forbidden shortcuts 和 release-risk areas 等说明。例如：“Do not bypass permission checks to make the admin panel pass,” 或 “Use existing service methods rather than direct database writes.” 这样可以把通用的 focused-fix 指南，变成更适合你代码库、也更安全的修复工作流。