incremental-dev

name	incremental-dev
description	增量开发工作流，用于让代码演进保持小、可理解、模块化、可验证。用户要求下一步计划、小步计划、逐步实现、慢点实现、按计划继续、重构、重写、新项目搭建、架构梳理，或表达项目复杂度失控、想从头重写、希望重新获得掌控感时使用。也触发于中文短语：小步计划、按计划实现、继续实现、慢点实现、复杂度失控、想从头重写、重新获得掌控感；英文短语：next step, step-by-step, small steps, incremental implementation, keep it simple.

增量开发

目标：让项目始终小到用户能够理解、判断和掌控。

同时遵循 karpathy-guidelines：先想清楚再写代码，外科手术式修改，避免推测性抽象，并为每一步定义客观验收方式。

核心规则：

一次只构建一个可理解的小切片。每完成一个切片，用户都应该知道：改了什么、为什么存在、如何验证、下一小步是什么。

硬性约束

• 每轮只实现一个小目标。
• 每步最多引入一个新概念。
• 只修改当前步骤必须修改的文件。
• 优先沿用现有结构、命名和测试风格。
• 当前步骤验证完成后，才能提出下一步。
• 完成用户要求的当前步骤后停住，不自动进入未来步骤。

模式选择

规划

当用户要求计划、下一步、架构思考、复杂度评估，或说“先思考/分析”时使用。

除非用户明确要求实现，否则不要改代码。

回复包含：

• 当前状态：已经有什么，哪些是稳定的。
• 下一阶段目标：一个有用能力，不要太远。
• 下一小步：一个可实施的微步。
• 验收标准：测试、命令或可观察行为。

如果用户要求大计划，可以给简短阶段路线图，但最后必须落到一个下一小步。

实现

当用户说“按计划实现”“继续按计划实现”“开始实现”“实施”等表达时使用。

只实现上一轮确定的下一小步。如果上下文里没有清晰小步，先读取相关文件，选择最小一致步骤，简短说明后再实现。

如果用户同时提出小的命名、目录或测试位置要求，只有在它和当前微步强相关且仍符合微步预算时才一起处理；否则先回答设计问题，把实现拆到后续步骤。

实现后：

• 运行最相关的 focused test。
• 如果代价低，再运行更大范围的相关测试。
• 用普通语言总结改了什么。
• 提出一个下一小步，然后停住。

修复

当测试失败、用户贴出报错，或当前验收没有通过时使用。

只修复当前失败。不要扩展功能、重构邻近代码或推进路线图。

重新定向

当用户说项目太复杂、失控、难以继续，或想从头重写时使用。

暂停功能开发，先重建项目地图：

• 入口在哪里。
• 核心循环是什么。
• 数据如何流动。
• 哪些模块已经稳定。
• 当前最窄的安全前进路径是什么。

优先删除、延后或命名边界，而不是增加抽象。

阶段回顾

当用户问计划是否完成、接下来做什么，或要求阶段回顾时使用。

不要写代码。先总结：

• 已完成的稳定闭环。
• 尚未实现的能力。
• 最有价值的下一阶段。
• 一个下一微步。

微步预算

一个合格的实现步骤通常满足大部分条件：

• 只新增一个行为、概念或澄清。
• 通常只改 1-2 个生产文件。
• 通常只新增或修改 1 个 focused test 文件。
• 新增生产代码大致不超过 80 行有效代码。
• 不创建新文件夹，除非职责已经稳定。
• 不创建 protocol/interface/factory，除非已有真实边界或至少两个实现。
• 不把配置、接口、工厂、文档和业务行为塞进同一步。

如果超过预算，先拆小。如果用户说“还是太大”，承认并继续拆，直到每步只引入一个容易解释的想法。

大计划 + 小计划

当用户要求较大的计划时：

• 大计划：只写阶段和方向，避免文件级细节。
• 小计划：只写下一次可实施的微步。
• 当前不做：明确哪些诱人的工作暂时延后。

这样保留方向感，但不让下一轮实现膨胀。

长对话规则

• 用户问“下一步”时，基于当前代码重新校准，不机械复读旧计划。
• 用户说“按计划实现”时，默认执行上一轮最后给出的下一小步。
• 如果旧计划过期，先说明原因，再选择当前最小安全步。
• 如果用户提出命名、目录或职责边界问题，先把它当设计问题回答，再决定是否写代码。

回复形状

规划回复：

当前状态：...

下一阶段目标：...

下一小步：...

实施计划：
1. ...
2. ...
3. ...

验收标准：...

实现后的最终回复：

已完成：...

验证：...

下一小步可以是：...

保持短。这个技能是为了降低认知负担，不是为了产出漂亮但庞大的计划。

测试

涉及行为变化时，默认先写或先调整一个 focused test，让它表达当前微步的验收标准，再实现代码让测试通过。

可以不先写测试的情况：

• 纯文档、注释或命名整理。
• 机械移动文件或无行为重构。
• 项目暂时没有可用测试框架。
• UI、启动流程或探索性 spike 更适合先用手动验证收窄问题。

即使不先写测试，也必须在写代码前说清楚本步验收标准，并在完成后验证。

复杂度护栏

避免：

• 一次性生成完整架构。
• 主干闭环跑通前创建所有未来模块。
• 同一步混合配置、接口、工厂、文档和业务行为。
• 让 CLI、Web、存储、模型和工具互相知道对方内部细节。
• 只因为“更好看”而大范围重命名。
• 当前步骤完成后顺手进入下一步。

优先：

• 先稳定核心循环，再添加接口层。
• 只在今天能降低耦合时抽取 contracts。
• 先用 fake/file/local 实现，再接外部服务。
• 测试行为，而不是绑定实现细节。
• 当用户目标是理解时，简短解释设计取舍。