关于 implement
用于按小步实现计划变更的编码技能,面向开发者和编码 Agent。它围绕验收标准组织测试、验证与提交,并将每次差异限制在对应切片内。
主要功能
- 01按行为切片规划工作
- 02先写测试再写生产代码
- 03提交前验证每个切片
- 04限制差异并清理死代码
- 05将错误和未决决策升级处理
适用场景
- 01逐项实现规格验收标准
- 02为小型变更编写回归测试
- 03将切片任务委派给子 Agent
- 04提交前检查变更
安装
复制下面的命令,在终端中运行。
$
npx skills add https:/ / github.com/ pwguler/ skills --skill implement安装后在 Claude Code 中输入/implement确认已加载。
包含的文件
除 SKILL.md 外,安装时一起下载的参考资料和脚本。
references/blast-radius.mdboundary-discipline.mdbuild-the-lever.mdfoundational-thinking.mdlaziness-protocol.mdmake-operations-idempotent.mdmigrate-callers-then-delete-legacy-apis.mdminimize-reader-load.mdmodel-the-domain.mdnever-block-on-the-human.mdoutcome-oriented-execution.mdseparate-before-serializing-shared-state.mdsequence-verifiable-units.mdshape-first.mdsubtract-before-you-add.mdtest-behavior-not-implementation.mdtype-system-discipline.md详细介绍
按细小切片推进计划,每次处理一个切片。切片是对可观察行为所做的最小更改。如果 docs/specs/<slug>.md 中存在规范,则按其验收标准制定计划。逐项完成验收标准。差异不得更改规范非目标所排除的任何内容。如果规范仍包含 ## Open decisions 部分,则它还是草案。将其退回给 drill。没有规范且计划尚未敲定的请求,先交给 drill。其快速路径会给出一句话计划。
- 在首次测试前创建任务列表。存在规范时,为每项验收标准添加一个条目。不存在规范时,为每个切片添加一个条目。然后添加
verify;如果工作涉及 UI、公共接口、名称或文档,再添加rubric。列表不得少于三项。每项工作提交后,将对应条目标记为已完成。跳过某项时,将其标记为已完成,并在条目文本中添加skip: <reason>。切勿跳过验收标准。将其保持为未完成。 - 选择最小的未完成切片,并在本次会话中对其执行步骤 3 至 7。如果用户要求将切片交给工作者,则启动一个运行
implement技能的子 Agent。它会对一个切片执行步骤 3 至 5。阅读其差异,然后在此处执行步骤 6 和 7。 - 编写一个针对该切片且会失败的测试。通过接口进行测试,绝不针对实现细节。如果无法编写失败的测试,则说明被测接口有误。修正计划,而不是测试。
- 编写能使测试通过的最少代码。
- 仅在测试通过时重构。遵循周边代码的风格。
- 如果差异删除或重命名了其他代码所使用的符号,则在关卡前按照 blast-radius.md 执行检查。若差异更改了其他模块、存储数据或外部调用方所依赖的契约,也要执行该检查。
- 阅读
verify技能,并对该切片运行其关卡。根据其证据记录提交。 - 返回步骤 2,直到没有剩余切片。
规则:
- 如果当前位于基准分支,请在首次测试前建议创建新分支,并询问用户。基准分支是远程 HEAD 指向的分支。新分支使用规格说明的 slug,或使用单句计划的简短 slug。只有用户明确要求时,才在基准分支上工作。绝不自行假定。已经位于功能分支的会话应继续留在该分支。
- 一次只做一个实现。不得自行决定把未完成的工作留给新任务。提供选项:完成并合并、部分合并,或保留在当前分支以便日后继续。由用户选择。只有
land才会结束工作。 - 在失败测试编写完成前,不得编写生产代码。唯一例外是接线代码,其唯一作用发生在测试无法驱动的宿主内部。例如插件入口或框架注册。必须通过
verify进行端到端运行来证明其有效,绝不能用正则表达式或对源代码的字符串匹配来证明。 - 在首次添加模块或导出类型的切片之前,先按照 先确定形状 敲定其形状。草图应是一个仅包含
not implemented存根的提交,不带任何行为。这些存根要先于用于补全它们的失败测试。 - 在切片的首次测试前,列出该切片可能失败的方式。测试最可能发生和代价最高的情况:数据丢失、金钱损失、访问问题或调用方契约遭破坏。在提交消息中写明其他可能情况。测试规模应与改动相称。一行修复只需一个回归测试,不要新建测试基础设施。
- 在切片内,只运行覆盖该切片的测试,绝不运行整个测试套件。切片的门禁要等到第 7 步才执行,
verify决定其规模。在规格说明声明的阶段内,门禁遵循以结果为导向的执行。一系列相似编辑遵循按序列划分可验证单元。 - 用两种假想改动检查每个测试。行为遭破坏时,测试必须失败;只有内部实现改变时,测试仍须通过。如果断言检查的是模拟对象、调用或错误消息,请阅读测试行为,而非实现。如果断言没有明确地将被测对象的输出与字面值比较,也请阅读该文档。对源代码进行 grep 或字符串检查无法证明行为。只有当切片的测试在被测行为遭破坏时失败,切片才算完成。
- 每个差异都必须属于当前切片。每一处改动要么属于该切片,要么是在该切片改动的文件中删除死代码。
- 添加任何内容之前,按顺序提出四个问题:它是否有存在的必要?标准库或平台能否实现?现有依赖能否实现?能否用一行代码实现?添加文件、层、依赖或参数之前,请阅读简化原则和先删减,再添加。只有通过尽量减轻读者负担中的检验,才添加封装、层或状态。测试代码也要问这四个问题。作为切片的一部分,应先扩展现有的伪对象、夹具或辅助函数,再编写新的。
- 为机械性工作构建工具,并让工具执行工作。机械性工作包括一系列编辑、迁移、生成文件或数据分析。手动进行首次编辑前,请阅读构建杠杆。
- 如果切片的逻辑需要保存状态或按某种形状分支,先定义数据形状。如果切片创建的类型会被后续切片共享,也要这样做。编写这类逻辑前,请阅读对领域建模和基础思维。
- 保持代码类型安全:不得使用类型转换或其他绕过类型检查器的方式。设计类型或签名时,请阅读类型系统规范。
- 在 I/O 边界验证数据,并在内部信任这些数据。配置属于输入。应在构建配置的代码处验证,并在那里拒绝无效值,而不是等到首次使用时才处理。编写验证、错误处理、适配器或配置代码时,请阅读边界规范。不得使用会掩盖失败的静默回退。
- 每次网络调用都必须设置超时。每个调用方可能重试的写入操作都必须使用幂等键。对于会写入状态且可能运行两次的命令、启动步骤、调度器或循环,请阅读使操作具备幂等性。
- 当两个操作访问相同数据时,应依次运行。或者,在
await之前先声明对数据的占用:将其标记为处理中。然后在await之后,再次检查之前读取的每个条件。仅仅再次检查,仍可能导致扣款或发送操作运行两次。当两个执行方可能写入同一个文件、键或数据时,请阅读在序列化共享状态前进行拆分。 - 组件状态只能通过组件自身的操作来修改。绝不能向调用方提供能让其修改状态的引用。也绝不能向调用方提供其持有期间可能发生变化的状态引用。在公开组件状态之前,请阅读尽量减轻读者负担。
- 删除因改动而变得无用的内容。编写新 API 以替代仍有调用方使用的旧 API 之前,请阅读先迁移调用方,再删除旧 API。在切片改动的文件中,也应先删除死代码再添加内容。死代码包括没有调用方使用的函数、导入和参数,以及没有调用方能到达的分支。它还包括过时的标志、重复边界已执行检查的验证器,以及重复描述代码或为变通方案辩解的注释。非目标范围之外的死代码应予以保留。其他文件中的死代码应标记出来,但不得删除。
- 不要写重复描述代码或解释变通方案的注释。应从根源修复变通方案,或用类型、lint 规则或测试来约束相关条件。只有代码无法表达的内容才保留注释。例如,项目无法控制的行为:浏览器特性、供应商缺陷或协议要求。
- 如果切片会构建 UI,且项目存在
DESIGN.md,则应使用其中规定的字体排印、颜色和间距。 - 每个切片的提交消息都应符合仓库的单行约定。阅读近期的
git log以了解约定。如果没有约定,则使用小写祈使句。根据准则的实际内容命名,绝不能用其规格 ID 命名。说明原因,而不只是描述改动。只暂存具体文件,绝不能使用git add .。 - 将切片中的错误或意外失败交给
debug技能处理。不要用补丁掩盖症状。 - 绝不能替用户猜测切片中的决策。应停下来指出该决策,并让用户回答。凡是会改变验收标准、非目标或公共接口的决策,都应由用户作出。需要用户授权或无法撤销的决策,也应由用户作出。对于可通过运行来确定的其他决策,应按不要因等待人工而阻塞所述,通过运行来解决。
- 同一切片连续失败三次后,停止循环。向用户报告相关准则、尝试过的做法以及最后一次错误。
- 最后一个切片提交后,阅读
verify技能并按其要求执行。必须在宣布工作完成前执行。对于 UI、公共接口、名称或文档,还要阅读rubric技能并按其要求执行。实现者不得自行评判自己的品味。
评论
支持 Markdown