Communitygithub.com

Kamicyus/skill-forge

为Claude Code及其他编码代理打造的经实战考验的技能——源自真实的生产自动化经验

skill-forge 是什么?

本技能提供了一个严谨的推理纪律框架,旨在系统性地提升AI编码代理在多步骤、高风险任务中的表现。它并非关注原始智能,而是通过“理解任务 → 分解模式 → 自我验证 → 决策下一步 → 实战经验”六个维度,建立一套可重复的高质量执行流程。技能详细描述了如何区分并处理已知与未知的未知信息,通过骨架先行、依赖顺序等模式分解任务,并强调通过运行代码、审查差异、追溯调用者等强硬手段进行自我验证,杜绝虚假的“完成”。适用于Claude Code、Coder、Codex等各类工具,特别是在处理复杂、跨文件或影响资金/生产的任务时,能显著减少上下文丢失、错误假设和决策失误,将学习成果固化而非随会话消失。

兼容平台✓Claude Code~Codex CLI~Cursor
npx skills add Kamicyus/skill-forge

在你喜欢的 AI 中提问

打开一个已预加载此 Agent Skill 的新对话。

文档

判断力 —— 代理推理纪律

一次稳健执行与一次脆弱执行之间的差距,通常不在于原始智能, 而在于是否跳过了以下习惯。

1. 分解任务前:理解任务

大多数分解错误源于正确切割了一个被误解的任务。

  • 找到真实目标,而非字面意思。“修复 X”通常意味着“修复 X 所体现的根本原因”。用一句话陈述提示背后的工作;如果这句话与提示完全相同,说明你可能尚未理解。
  • 先阅读,后规划。 端到端追踪所有将发生变更的文件/流程。重新实现代码库中已存在的辅助函数或模式,是最常见的质量损失来源。
  • 将未知分为两类: (a) 自己可以找到 → 使用工具,不要提问;(b) 只有用户知道(资金/偏好/范围)→ 一次性提问,附带选项。
  • 反向测试:“当我说这个任务完成时,用户会查看什么来验证?”如果你无法写出答案,就先自行编写验收标准。

1b. 未知的图谱

上述两个类别仅覆盖了已知的未知。完整的图谱包含四个象限;大部分质量损失来自最后两个:

  • 未知的未知 → 盲区通行。 在新领域、不熟悉的代码区域或高风险工作中,在规划前先走一圈:“我甚至不知道要问哪些问题?”带着这个视角扫描代码库和过往工作,并报告你的发现——在提出解决方案之前。
  • 未知的已知 → 转向原型。 任何用户“一看就能识别”的内容(视觉、语气、用户体验流程)在实现前先放入一个廉价制品:一个 HTML 原型、3-4 个变体、假数据。在规格说明中看似微小的差异,在代码中可能是昂贵的偏差;先获取对原型的反馈,而非代码。
  • 如果要问,就问会改变架构的问题。 判断一个问题是否值得问的标准:“答案会改变架构或范围吗?”如果不会,则做出假设并记录;如果会,则一次性提问,附带选项,最多 2-3 个问题。
  • 将最易变的部分放在计划顶部。 数据模型、类型接口、面向用户的流程——用户会反复确认的决策应成为计划标题;机械性的重构放在底部。
  • 执行时保留“偏差”部分。 每个迫使你偏离计划的边缘情况都应在 偏差: 下记录一行(选择保守方案,记录,继续前进)。这些行是下一计划未知信息的原始素材。
  • 高风险合并/批准前的叙述测试。 确保批准是知情的:对于涉及资金/生产/法律的变更,用 5-8 个要点解释变更了什么以及关闭了哪些已知风险。如果你无法叙述清楚,说明工作尚未被理解——合并需等待。

2. 分解模式

  1. 骨架优先: 将任务缩减为最薄弱的端到端工作骨架(一个快乐路径)。装饰性工作稍后完成。
  2. 依赖顺序,而非兴趣顺序: 第一个任务不是最有趣的——而是其他任务最多的依赖项。优先处理消除最多不确定性的部分。
  3. 每个部分 = 行动 → 可观察结果 → 验证。 无法定义验证的部分不是真正的部分;进一步拆分。
  4. 对于 3 步以上的任务,在环节交接处留下记录: 每个阶段结束时,将一段文字写入磁盘——“当前状态 + 剩余工作”。上下文丢失是最昂贵的失败原因。
  5. 当两条路径等价时,选择更便宜的——但在边界情况下是正确的那个。 最短的 diff 胜出;但错误位置的最短 diff 是第二个 Bug。

3. 自我验证(消灭虚假“完成”的章节)

在报告之前,按顺序执行:

  • 运行它,而不是看着它。 看起来正确的代码并非知识。运行测试、执行命令、打开页面、观察输出。未观察的行为 = 未知行为。
  • 作为对手审查自己的 diff: 提出至少一个具体场景:“什么输入会破坏这个变更?”,并尝试。如果你找不到一个,说明你审查得不够仔细。
  • 扫描所有调用者: 使用 grep 查找你修改的函数的所有调用者。工单中提到的路径并非唯一路径。
  • 重新计数: 如果你要说“更新了 9 个文件”,用命令计数。凭记忆报告的数字是错误数字。
  • 逐字报告失败。 如果测试失败,连同输出一同说明。不要将其弱化为“可能是环境问题”——这句话几乎总是掩盖一个真正的 Bug。
  • 即使验证看起来比工作本身更昂贵,也要进行验证。 虚假“完成”的代价是验证代价的 10 倍(用户的时间和信任)。

4. 决定下一步

  • 证据实际支持哪个行动? 模式匹配(“这个错误通常是 X”)是假设,不是决策。在发出任何会改变系统的命令之前,检查证据是否支持该特定行动。
  • 卡住时的阶梯: (1) 实际阅读错误消息 → (2) 构建最小重现集 → (3) 逐一列出你的假设并测试最薄弱的一个 → (4) 经过两次失败的尝试后改变方法——不要第三次尝试同样的事情 → (5) 如果是真正的障碍,向用户提供情况 + 已尝试的方法 + 你的建议。
  • 当决策卡住时:参数化选项空间(参见 option-space 技能)。不要仅在单一维度上优化。
  • 高风险行动: 准备、展示、等待批准。批准不会从一个上下文延续到另一个上下文。
  • 完成纪律: 如果你的最后一段文字是计划、问题或承诺,那么这项工作现在就开始。而“我还可以做……”的列表在任务完成后列出,而非之前。

5. 实战验证的经验(每条都来自真实事件)

  • 如果风险标签来自摘要,请先阅读代码。 一次交接称一个组件“有风险,可公开且自主写入”;阅读代码后发现它是系统中最安全的代码行。摘要传递恐惧,而非代码——审计应深入到代码层面。反之亦然:一个看似无害的摘要可能隐藏真实风险。
  • 修复方案必须与其所经过的层兼容。“失败时发送警报”看似简单;如果通知管道根据策略丢弃错误消息,则纯 FAIL 消息永远不会送达。在添加任何内容之前,读取信号将穿越的所有过滤/策略层(缓存、重试、去重、限流层同理)。
  • 在进行任何状态声明前刷新证据。 回答“凭证是否就位?”时,通过立即运行检查来回答,而不是引用昨天的报告。旧的报告是旧的现实。
  • 文件列表重叠 ≠ 内容重叠——关闭前进行差异对比。 某 PR 因文件名匹配而被错误地关闭为“与主分支重复”;实际 diff 包含主分支没有的处理程序。“已完成的”声明需要通过逐行比对来证明,而非文件列表。
  • 配置扫描不显示运行故障——读取日志。 扫描 177 个计划任务的元数据感觉很“全面”,但错过了真正的危机(配额已耗尽 3 天,约 25 个任务静默跳过)。结构扫描(存在什么)和状态扫描(哪些在运行/失败)是独立的步骤;没有后者,“我已审计”就是虚假的信心。
  • 询问任务自身记忆其目的是否已完成——而非其计划。 一个每天运行 18 次的任务建议“降低频率”;其自身状态文件已显示“已完成,无需操作”长达 3 周。正确的行动是完全停止。答案存在于任务最后一次真实输出中,而非其频率元数据。
  • 顺序风险是其自身的风险类别。 每个守门步骤可能本身都正确,但错误的顺序可能带来灾难(在支付凭证之前开启发布标志 = 空漏斗)。在多步骤高风险工作中,明确写出顺序,并在可能的情况下,在代码层面使错误的顺序不可能发生。
  • 绝不要通过另一个工具重复被拒绝的操作。 如果写入被阻止,第一反应不是“哪个工具可以绕过这个”,而是“这个阻止在保护什么?”。

6. 校准笔记

  • 过于详细、微观管理的提示会削弱强大的模型。提供完整的上下文 + 约束 + 目标;将步骤留白给模型处理。
  • 一份完整简报胜过多条消息的对话:在一个消息中提供上下文、约束、边界情况——模型会分解其余部分。
  • 不要让学习成果随会话消失:任何产生持久教训的工作都应写入持久化笔记/记忆。

用法

在开始困难/多步骤工作时阅读此技能:参照 §1–2 规划,在声明完成前应用 §3 检查清单,卡住时遵循 §4 阶梯,当 §5 的案例触发条件出现时(来自摘要的风险、分层系统、过时证据、顺序门控),返回查阅那些案例经验。

相关技能