分阶段开发 visheshgubrani/clean-dev

Clean Dev

一个精简的智能体技能，按已批准的阶段开发应用，代码可读，重要选择有清晰记录。

写计划，征求意见，实现一个阶段，验证，更新记录。代码和文档保持足够小，让人能审得过来。

安装

用 Vercel 的 Skills 命令行安装：

npx skills add visheshgubrani/clean-dev --skill clean-dev -g

命令行会让你选择编码智能体。省略 -g 就只装到当前项目里。

技能使用标准的 SKILL.md 格式，与你的框架、语言、托管服务商无关。直接读完整技能或记录模板。

使用

通过智能体的技能选择器调用 clean-dev，或者直接让它用这个技能。以 Codex 为例：

Use $clean-dev to develop this application. Prepare the roadmap and first
phase with TODOs and acceptance checks. Ask for my input before coding.

已有项目：

Use $clean-dev. Read the project instructions and current phase, inspect
what is already implemented, and propose the next reviewable phase.

工作流

1. 检查： 读相关代码、项目说明和已有记录。保留无关的工作。
2. 规划： 写阶段文件，包含目标、范围、排除项、TODO、验收检查和需要你拍板的选择。
3. 批准： 把计划摆出来，等对方明确批准指定的阶段。检查和规划可以提前做；搭应用骨架、装依赖、写实现都要等。
4. 实现： 在这个阶段范围内干活。复用辅助函数和组件，更新已完成的 TODO，记录重要决策。如果实质性改动会超出已批准的范围或设计，再问一次。
5. 验证并收尾： 跑相关检查，复查改动，记录实际结果，把阶段标记为完成。除非下一个阶段已经批准，否则就此打住。

用户可以一次批准多个已写好的阶段。已批准范围内的常规实现细节，不用反复问。

项目记录

技能会在被开发的应用里创建或更新这些记录。已有等价文档时直接复用。

| 文件 | 记录什么 |
| AGENTS.md | 稳定规则、验证过的命令、链接。目标：50 行以内。 |
| docs/PLAN.md | 目标、阶段顺序、当前阶段、状态、链接。 |
| docs/ARCHITECTURE.md | 组件职责、数据流、边界、约束。提议的设计和已实现的设计分开标注。 |
| docs/DECISIONS.md | 重要选择、理由、备选方案、后果、批准状态。 |
| docs/phases/NN-short-name.md | 某个阶段的范围、批准、TODO、验收检查、验证证据、结果。 |
阶段状态：proposed → approved → in_progress → done。没做完或无法验证的工作保持 blocked，并写下下一步动作。后续阶段可以先留简要提纲，等准备规划时再补全。

代码与缺陷修复

职责要清晰，命名要能说明用途；当提取辅助函数能消除明显重复、或让代码更好懂时，就提取出来。抽象和依赖只在有当前且说得清的需求时才加。注释写短一点，只讲那些不明显的理由或约束。

遇到缺陷，先复现报告，对比预期行为和实际行为，找出原因，拿到批准后再改。改完代码，重新跑一遍最初的复现步骤，并检查相邻行为。条件允许就补一个回归测试。如果复现卡住了，把缺失的证据记下来，然后去要。

凡是影响行为、结构、依赖、数据、接口，或涉及有意义取舍的选择，都要记录。纯机械改动和命名琐事不用写进决策日志。

保持精简

核心指令 792 词。模板只在创建记录时加载。恢复工作时，技能只读当前阶段和相关决策，不加载整个项目历史。小修复用一个短阶段就够。

这些是给智能体的指令，能不能遵守取决于智能体自己。检查和记录下来的证据仍然需要人工复核。

贡献

提 issue 或 pull request，附上具体例子，说明工作流在哪里卡住、或哪里增加了不必要的开销。改动保持简洁，并拿一个真实任务验证。

许可证

MIT。Copyright 2026 Vishesh Gubrani。