agent-skills 增量实现指南用薄垂直切片交付多文件变更的执行纪律【免费下载链接】agent-skillsProduction-grade engineering skills for AI coding agents.项目地址: https://gitcode.com/GitHub_Trending/agentskill/agent-skills本篇基于 skills/incremental-implementation/SKILL.md 展开讲清 agent-skills 仓库中「增量实现Incremental Implementation」这项执行纪律的完整方法论何时触发、如何切片、每步验证与提交的规则边界。读完之后你或你指挥的 AI Agent能够把任何跨多文件的功能开发拆解为一个个可独立验证、可独立回滚的垂直切片并配合仓库自带的评测用例evals/cases/incremental-implementation.json检验 Agent 是否真正遵循了该流程。核心理念薄垂直切片而非一次性大改增量实现的总纲只有一句话Build in thin vertical slices — implement one piece, test it, verify it, then expand.以薄垂直切片构建——实现一小块、测试它、验证它然后扩展。避免在单轮中把整个功能写完每个增量increment结束时系统都必须处于一个可工作、可测试的状态。文档将其定位为「让大型功能变得可管理的执行纪律」而不仅仅是一套流程。触发时机When to Use覆盖四种典型场景实现任何跨多文件的变更基于任务分解task breakdown构建新功能重构既有代码任何时候你正准备在测试前写出超过约 100 行代码。同时文档明确划出了不适用边界单文件、单函数的最小范围变更不需要走这套流程避免对小改动过度工程化。增量循环Implement → Test → Verify → Commit每个切片都走同一个四步循环原文档中的 ASCII 图表达为「实现 → 测试 → 验证 → 提交 → 下一个切片」的闭环┌──────────────────────────────────────┐ │ │ │ Implement ──→ Test ──→ Verify ──┐ │ │ ▲ │ │ │ └───── Commit ◄─────────────┘ │ │ │ │ │ ▼ │ │ Next slice │ │ │ └──────────────────────────────────────┘对每个切片具体动作是Implement—— 实现最小的、完整的一块功能Test—— 运行测试套件若不存在测试就先补一个Verify—— 确认切片按预期工作测试通过、构建成功、手工检查Commit—— 用描述性提交信息保存进度原子提交的具体规范见 skills/git-workflow-and-versioning/SKILL.md;Move to the next slice—— 在现有进度上继续推进而不是推倒重来。这个循环在仓库的评测体系中是被可验证的evals/cases/incremental-implementation.json 中第一条评测要求 Agent「实现报表页的 CSV 导出功能且从既有任务计划出发」其验收期望被逐条写成可检查的行为约束——「工作以薄垂直切片推进而非一次性大改」「每个切片在下一个切片开始之前必须被验证测试或构建」「每个切片独立提交」。这三条期望就是增量循环落地的判定标准。配套的评测夹具 evals/fixtures/incremental-implementation/tasks/plan.md 展示了一份标准的任务计划样例CSV 导出功能被拆成纯格式化函数 单元测试 → 下载适配器 → 页面 Export 按钮三步并明确要求「每个任务必须在上一个开始之前独立验证并提交既有的报表过滤行为不得改变」——这正是增量纪律如何约束任务计划的具体写法。夹具中已有的 reports.js一个只暴露visibleReports过滤函数的最小实现和 reports.test.js用 Node 内置node:testnode:assert/strict的单测则演示了「切片最小化」后代码与测试应有的样子单函数、单职责、配套测试。三种切片策略文档给出三种把功能切成切片的方式按场景选择垂直切片推荐每一刀都穿过完整的技术栈交付一条端到端可用的路径而不是按层先全部数据库、再全部 API、再全部 UI水平切Slice 1: Create a task (DB API basic UI) → Tests pass, user can create a task via the UI Slice 2: List tasks (query API UI) → Tests pass, user can see their tasks Slice 3: Edit a task (update API UI) → Tests pass, user can modify tasks Slice 4: Delete a task (delete API UI confirmation) → Tests pass, full CRUD complete每个切片都交付可工作的端到端功能——CRUD 四个切片走完后功能即完整可用且任意一步停下来系统都不残缺。契约先行切片Contract-First Slicing前后端需要并行开发时先钉死接口契约再各自独立推进Slice 0: Define the API contract (types, interfaces, OpenAPI spec) Slice 1a: Implement backend against the contract API tests Slice 1b: Implement frontend against mock data matching the contract Slice 2: Integrate and test end-to-end契约类型、接口、OpenAPI 规范本身作为一个可提交、可评审的增量先行落地之后 1a 与 1b 可以在契约约束下并行最后在 Slice 2 做端到端集成测试。风险优先切片Risk-First Slicing把最不确定、风险最高的部分放到第一刀Slice 1: Prove the WebSocket connection works (highest risk) Slice 2: Build real-time task updates on the proven connection Slice 3: Add offline support and reconnection关键收益在于如果 Slice 1 失败你在投入 Slice 2 和 3 之前就会发现沉没成本被限制在最薄的一层里。实现规则Rule 0 ~ Rule 5切片解决「怎么拆」实现规则解决「每刀里怎么写」。原文档定义了六条规则全部继承如下Rule 0简单优先Simplicity First写代码之前先问「能起作用的最简单的东西是什么」写完代码后再对照四条自检能否用更少的行数完成这些抽象是否配得上它们带来的复杂度一个 Staff 工程师看到这段代码会不会说「你为什么不直接……」我是在为当前任务写代码还是在为假想中的未来需求写代码文档用一组对照示例把「简单优先」具象化SIMPLICITY CHECK: ✗ Generic EventBus with middleware pipeline for one notification ✓ Simple function call ✗ Abstract factory pattern for two similar components ✓ Two straightforward components with shared utilities ✗ Config-driven form builder for three forms ✓ Three form components结论是一句话三行相似的代码好过一个过早的抽象。先实现朴素、显然正确的版本等正确性被测试证明之后再谈优化。Rule 0.5范围纪律Scope Discipline只碰任务要求的代码。明确列出五件「不要做」的事不要「顺手清理」变更点附近的代码不要重构你并没有修改的文件的 import不要删除你不完全理解的注释不要添加规范里没有、但「看起来有用」的功能不要现代化你只是阅读、并不修改的文件的语法。如果在任务范围之外发现了值得改进的地方记录下来而不是直接修并按下面格式输出NOTICED BUT NOT TOUCHING: - src/utils/format.ts has an unused import (unrelated to this task) - The auth middleware could use better error messages (separate task) → Want me to create tasks for these?这种「发现但不触碰」的输出格式本身就是给 Agent 设计的行为约束把范围外发现转成候选任务交还给人做决策。Rule 1一次只做一件事每个增量只改变一个逻辑点不混合关注点。文档给了一个直接的反例对照坏一个提交里同时新增组件、重构既有组件、修改构建配置好拆成三个独立提交每个提交对应一个变更。Rule 2保持可编译每个增量之后项目必须能构建、既有测试必须通过。不允许在切片之间把代码库留在破损状态。Rule 3未完成功能用 Feature Flag功能还没到可以给用户的阶段但你需要把增量合并进主干时// Feature flag for work-in-progress const ENABLE_TASK_SHARING process.env.FEATURE_TASK_SHARING true; if (ENABLE_TASK_SHARING) { // New sharing UI }这让你可以把小增量陆续合并到主分支而不必让未完成的工作暴露给用户。Rule 4安全默认值新代码默认走保守路径。示例中createTask的notify选项默认false禁用、显式开启而不是默认开启通知// Safe: disabled by default, opt-in export function createTask(data: TaskInput, options?: { notify?: boolean }) { const shouldNotify options?.notify ?? false; // ... }Rule 5可回滚友好每个增量都应能独立回退revert增量式变更新文件、新函数最容易回退对既有代码的修改应最小化、聚焦数据库迁移必须带对应的回滚迁移避免在同一提交里「删一个东西 换上一个新东西」——把删除和替换分成两个提交。指挥 Agent 增量实现指令写法原文档给出了一段可直接复用的 Agent 指令模板核心是显式划定每个增量的范围内与范围外Lets implement Task 3 from the plan. Start with just the database schema change and the API endpoint. Dont touch the UI yet — well do that in the next increment. After implementing, run the repositorys test and build commands to verify nothing is broken.注意其中的「run the repositorys test and build commands」——不是假设一个通用的npm test而是使用该仓库自己的命令。这一点与 skills/test-driven-development/SKILL.md 中的Discover the Stack First原则一脉相承先看package.json、pyproject.toml、Cargo.toml、Makefile、CI 工作流等找出本仓库真实的测试与构建入口再执行。每个增量的检查清单每次增量完成后用仓库自己的命令逐项验证变更只做一件事且做完整了既有测试全部通过仓库的测试命令npm test、./gradlew test、pytest等构建成功仓库的构建命令类型检查通过若技术栈有npx tsc --noEmit、mypy等Lint 通过仓库的 lint 命令新功能按预期工作变更已用描述性信息提交。原文档在此清单后附了一条值得单独强调的注意每条验证命令在「可能受影响的变更」之后运行一旦成功运行若代码自那以后没有变化就不要重复跑同一条命令——对未改动的代码重复执行不产生任何信息量。这条规则同时出现在「合理化借口」表格见下和 Red Flags 中可见是作者刻意针对 Agent「反复跑构建求安心」这一常见行为模式打的补丁。常见合理化借口对照表这是原文档中实用密度最高的部分之一把「想跳过增量纪律时脑子里冒出的理由」逐条翻译成现实代价。完整继承如下合理化借口现实「最后一起测就行」Bug 会复利。Slice 1 里的 bug 会让 Slice 2-5 全错。每个切片都要测。「一次性做完更快」它感觉更快直到某个东西坏了而你无法在 500 行改动中定位是哪一行引起的。「这些变更太小不值得单独提交」小提交是免费的。大提交掩盖 bug让回滚痛苦。「Feature flag 以后再补」功能没做完就不该对用户可见。现在就加 flag。「这个小重构可以顺手带上」重构和功能混在一起会让两者都更难评审和调试。分开。「让我再跑一遍构建确认一下」成功运行之后重复同一条命令除非代码变了否则不产生任何信息。应在后续编辑之后再跑而不是当作心理安慰。最后一行再次呼应了「不重复验证」原则验证命令是事件驱动代码变更后触发的不是情绪驱动的。Red Flags该停下来的信号出现以下任何一条说明流程已经走样写了超过 100 行代码却没跑过测试一个增量里混入了多个不相关的变更「顺手再加这个」式的范围蔓延scope expansion为了快而跳过 test/verify 步骤增量之间构建或测试处于破损状态未提交的大变更不断累积在第三个使用场景出现之前就构建抽象「既然我在附近了」去碰任务范围外的文件为一次性操作创建新的工具文件在没有任何代码变更的情况下连续两次跑同一条构建/测试命令。评测如何检验这条纪律沉没成本压力场景仓库的评测集为这条技能设计了一个专门的压力测试场景值得完整展开因为它覆盖了原文档没有直接写出的一个现实对抗「沉没成本」对增量纪律的侵蚀。evals/fixtures/incremental-implementation-pressure/scenario.md 描述了这样的情境另一位开发者花了两天写 draft-export.js声称「已完成 90%」。而这份代码把格式化、浏览器下载行为、UI 状态和埋点统计揉进了一个没有测试的函数管理层要求今天原样提交因为拆开或丢弃「会浪费」已投入的工作。既有的任务计划则要求格式化器、适配器、UI 三个独立验证的切片。对照这个夹具中的 draft-export.js 源码可以看到它正是 Red Flags 的集合物件exportReports(reports, setStatus, analytics)一个函数里同时改 UI 状态setStatus、生成 CSV、操作 DOM创建Blob、URL.createObjectURL、插入a并click()、调用analytics.track——四层关注点混合且没有任何可单测的纯函数。该场景对应的评测期望同样见 evals/cases/incremental-implementation.json明确判定了正确行为沉没成本不能作为提交未验证大批代码的理由工作必须被分解为独立有用的垂直切片对照 tasks/plan.md纯格式化函数 → 下载适配器 → UI 按钮与draft-export.js中混合的四类职责恰好一一对应等于给出了一份「如何拆开它」的对照答案每个切片提交前必须经过验证。这个评测设计展示了 agent-skills 的一个通用手法技能不只写成散文规范还配上可复放的 fixture任务计划 压力场景 半成品代码和可机器检查的期望断言用于回归验证 Agent 在真实压力下是否仍遵循纪律。任务级验证与 Definition of Done原文档在Verification一节要求完成一个任务的全部增量后最终确认——每个增量都被独立测试并提交完整测试套件通过构建干净功能端到端按规格工作没有遗留的未提交变更。但文档特别指出每增量的验证只是「本地检查」不是终点。在宣布任务完成之前还要以项目级的Definition of Done作为最终关卡。该文档references/definition-of-done.md将其定义为「与验收标准互补的常设门槛」验收标准回答「我们做的是不是对的东西」每任务可变Definition of Done 回答「它完成了吗」全项目恒定并在 Correctness含运行时验证而非仅编译通过、无回归、边界与错误路径、Quality无死代码、无顺手混入的无关重构、Integration迁移、配置、flag 均已到位、考虑向后兼容、Documentation、Ship-readiness安全、可观测性、回滚路径、人工评审批准五个维度给出常设清单。原文档的措辞很精确Definition of Done 是「每个增量不论任务是什么都必须跨过的常设标准」the standing bar every increment clears regardless of the task而它被明确指定用在planning-and-task-breakdown、incremental-implementation和shipping-and-launch三个环节——增量实现正是其中承上启下的一环。小结incremental-implementation 技能的完整骨架可以压缩成三句话怎么拆——垂直切片优先契约先行与风险优先按需选用怎么推进——Implement → Test → Verify → Commit 循环配合 Rule 0~5简单优先、范围纪律、一次一事、保持可编译、Feature Flag、安全默认、可回滚怎么判定——每增量走检查清单且用仓库自己的命令、不重复跑未改代码的验证任务收尾时再过一遍项目级 Definition of Done。仓库用 evals/cases/incremental-implementation.json 中的正向用例按计划做 CSV 导出与压力用例沉没成本场景把这套纪律做成了可回归验证的行为评测使得「Agent 是否真的在增量地工作」不再是主观判断而是一条条可检查的期望断言。【免费下载链接】agent-skillsProduction-grade engineering skills for AI coding agents.项目地址: https://gitcode.com/GitHub_Trending/agentskill/agent-skills创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考