writing-plans 技能——为毫无代码库背景的工程师编写完整计划
writing-plans 技能如何将实施计划组织成小份的 TDD 任务,包含确切的文件路径、完整代码和预期命令输出——让没有先前背景的工程师无需猜测即可执行。
一份写着“添加适当的错误处理”或“为上述内容编写测试”的实施计划并不是计划——它是一份将决策推迟给执行者的清单。writing-plans 技能定义了计划必须如何编写:每一步都有完整代码、确切的文件路径、带预期输出的确切命令,且没有占位符。
根据此技能编写的计划,其目标读者是一位技术娴熟的开发者,但对特定代码库或问题领域几乎一无所知。计划承载了他们所需的一切,包括测试设计,因为这一假设同样不能成立。
任务之前先定结构
在任何任务列表之前,计划会先规划文件结构:将创建或修改哪些文件,以及每个文件负责什么。分解决策正是在此确定。每个文件应有一个明确的职责。一起变更的文件应放在一起——拆分按职责进行,而非按技术层。在现有代码库中,计划遵循既有模式,而不是单方面重构它们。
如果规格涵盖多个独立子系统,且在头脑风暴期间未被拆分,该技能会标记这一点并建议拆分为单独的计划。每个计划都应能独立产出可运行、可测试的软件。
小份的任务粒度
任务中的每一步都是一个动作,时长控制在两到五分钟:“编写失败的测试”、“运行它以确保失败”、“实现最小代码使测试通过”、“运行测试”、“提交”。TDD 红绿循环不是用散文描述的——而是以带预期输出的具体命令展示。乱序阅读任务的工程师必须仅从该任务中获得所需的一切,因此重复上下文不是问题:而是要求。
每个计划都以固定标题开头:功能名称、一句话目标、两到三句话的架构,以及技术栈。智能体工作者在该标题中会收到明确指示,使用 subagent-driven-development 或 executing-plans 技能来执行。
自审与交接
编写完完整计划后,该技能要求进行一轮自审,包含三项检查:规格覆盖(每个需求都能指向某个任务吗?)、占位符扫描(查找任何被禁止的模式),以及类型一致性(后续任务中的方法签名是否与先前任务定义的一致?)。发现的任何缺口都会就地修复——对于少于五个任务的短计划,不另行派发审查。
Datarim 管理项目的计划保存到 datarim/plans/<TASK-ID>-plan.md。对于其他项目,路径遵循项目约定,或在编写前提出并确认。保存后,该技能提供执行选择:子代理驱动(每个任务使用新代理,任务之间进行审查)或带检查点的内联执行。
阅读什么是 Datarim 了解更广泛的背景,或查看写作技能了解散文内容如何遵循并行流水线。