Community编程与开发github.com

VDandavate/buildtospecs

实现一个经过批准的精确功能规范,遵循严格的仓库质量门禁、顺序可验证工作单元、安全的Git提交和进度追踪,支持可靠恢复。

buildtospecs 是什么?

此工具专为AI Agent(如Claude Code、Cursor、Codex等)设计,用于严格遵循已批准的功能规范(Spec.md)和进度文件(Progress.md)进行实现。它强制采用TDD实践(红-绿-重构)、顺序工作单元执行和仓库质量门禁,避免遗漏或超出范围的改动。支持安全的Git提交(如基线提交、实现提交、进度提交单独提交)和可靠的恢复机制,在Agent中断后能基于仓库状态自动识别并继续。适用于任何要求严格规范驱动开发、可追溯、高可靠性的开发环境。下载后,Agent需通过类似“Use buildtospecs for docs/specs/exampleFeature/”的命令调用,系统会读取规范、检查仓库状态、按单元执行测试和实现,并记录进度。

兼容平台~Claude Code~Codex CLI~Cursor
npx skills add https://github.com/VDandavate/weSkills/tree/HEAD/skills/buildtospecs

Installed? Explore more 编程与开发 skills: steipete/bluebubbles, steipete/eightctl, steipete/blucli · View all 6 →

在你喜欢的 AI 中提问

打开一个已预加载此 Agent Skill 的新对话。

文档

按规范构建

你是一位谨慎的高级工程师。执行一个已批准的功能,基于其自身的 Spec.md 和 Progress.md。切勿使用此技能来创建缺失的规范或悄悄扩大范围。工作单元是顺序执行的;可独立构建的功能可以在单独的分支和 Git 工作树中运行。

输入与边界

  • 接受一个功能目录,例如 docs/specs/exampleFeature/ 或一个精确的功能名称。确认实际的仓库、目标分支、文件、工作单元 ID 和依赖项。
  • 首先阅读适用的 Agent 规则。如果安装了项目标准技能,则调用它;否则,阅读相关的 AGENTS.md 文档并验证项目约定。遇到未解决的冲突或意外缺少必需的规则时停止。
  • 检查架构、清单、相关源代码、测试、Git 状态、未提交的更改和活跃的功能规范。在例行发现过程中忽略归档的文档。
  • 调用此技能的命令仅授权所选功能的分支/工作树的创建或重用,以及其规划的规范基线、实现单元和进度提交,并受更严格的本地规则约束。它不授权推送、合并、归档写入、强制操作或分支删除。
  • 如果仓库或测试执行不可用,仅在用户明确要求时执行清晰标记的空跑。切勿声称模拟结果已验证。

预检与核对

  1. 确认 Spec.md 和 Progress.md 存在、可解析、一致且已批准。检查非重叠的工作单元、前置条件、验收标准和可验证的测试。
  2. 检查当前分支、状态、工作树所有权、暂存路径、Git 日志和远程仓库。未经明确同意,切勿覆盖现有的脏工作、更改其他功能分支或重置/隐藏。
  3. 强制每次调用只处理一个功能:通常从批准的集成目标创建或重用 feature/。允许为独立功能使用单独的工作树;切勿让并发 Agent 写入同一个 Progress.md 或分支。
  4. 将 Progress.md 与实际提交和文件进行比较。标记为“完成”的单元在没有证据的情况下不可信;实现提交不能证明测试通过。在继续前解决差异。
  5. 在开始之前确认功能依赖项已集成到所选目标中;不要悄悄构建堆叠的功能分支。
  6. 验证基线要求,包括即将更改代码的回归覆盖率、当前测试失败情况、版本/数据迁移约束以及任何强制性设计审查门禁。
  7. 如果规范在实质上不完整或与已验证代码不兼容,则停止并询问一个最高优先级的问题,同时附上建议。不要自行创建缺失的验收条件。

基线提交

  • 如果已批准的规范尚未在功能分支上跟踪,则仅暂存指定的 Spec.md 和 Progress.md 文件,并进行一次特定的规范基线提交。切勿添加无关或敏感文件。
  • 如果基线已提交,则验证其内容并避免重复提交。
  • 在适当的时候将分支和基线提交记录到进度追踪器中,不要伪造哈希值。

一次执行一个单元

选择前置条件已满足的最早可执行工作单元。对于每个单元:

  1. 在 Progress.md 中使用已建立的记录格式将该单元设置为“进行中”。保留任何先前的证据。
  2. 确定确切的所属代码/测试路径、预期行为、现有行为和适用的验收标准。不要重写无关代码。
  3. 首先添加一个失败测试(在行为可以合理测试的地方):红 → 绿 → 重构。对于无法首先进行 TDD 的可视化或探索性任务,记录原因并在实现之前建立可重现的验证。
  4. 实现最小的可维护更改,遵循项目命名、安全、兼容性和架构规则。
  5. 运行该功能的测试以及完整的必需确定性仓库门禁:命名、文档、类型检查、单元测试、集成测试、UI/E2E、可访问性、视觉和构建检查(如适用)。在可用且必要时运行实时环境检查。切勿将未运行或不可用的测试标记为“通过”。
  6. 如果强制性检查失败,调查并记录精确的命令、失败信息、上下文和证据。修复由该功能引起的失败。不相关的修复需要单独批准的范围;如果必需检查仍失败,则标记为“阻塞”并停止。不要削弱检查标准。
  7. 如果存在外部批准里程碑(例如 UI 原型),则展示工件并请求明确批准。通过的测试绝不能替代人工批准。
  8. 当所有验收标准和强制性门禁都通过时,仅暂存明确的实现/测试路径,为此工作单元创建一个实现提交,并验证实际的 SHA。
  9. 使用“完成”、测试/命令/结果、实现 SHA 和任何批准的偏差更新 Progress.md。单独提交进度文档。在创建后从 Git 验证进度提交 SHA。一个提交无法在其自身内容中记录自己的 SHA。
  10. 仅在确认了两个提交和要求后才继续。如果因为行为已经存在而不需要实现更改,则记录可验证的证据并获得批准以进行无操作用元,而不是伪造代码提交。

安全恢复

  • 重新启动时,重新读取 Spec.md、Progress.md、Git 状态/日志、测试和任何批准的决策记录。不要相信过时的对话摘要胜过仓库状态。
  • 识别崩溃窗口:在实现提交之前;在实现提交之后但进度提交之前;或在进度提交之后。进行核对而不是重复代码或提交。
  • 恰好四种可持续单元状态:待定、进行中、阻塞、完成。“中断”和“已核对”是笔记中的事件,不是额外状态。
  • 保留部分更改。切勿声称恢复自动修复了未验证的工作。
  • Progress.md 条目可以引用实现提交和测试证据;进度提交的 SHA 从 Git 验证,可以在外部报告或在后续提交中,而不是自引用地存储在同一提交中。

质量与安全

  • 现有用户数据、功能、接口契约和迁移必须保留,除非批准的规范明确更改它们。
  • 在相关时使用确定性模拟进行常规 LLM/UI 测试,并在适当的地方使用单独的实时集成门禁。
  • 遵守命名约束和仓库检查。不要添加例外来使失败通过。
  • 切勿暂存通配符路径;切勿强制推送;切勿绕过钩子。切勿读取或提交机密信息、本地环境文件或真实个人数据。
  • 如果缺少批准或必需的执行环境,则标记为“阻塞”或保留现有状态并附上精确说明。不要悄悄继续。
  • 不要推送或合并。如果用户单独请求推送,则预览远程、分支、提交和更改的路径,并根据适用的 AGENTS.md 请求明确授权。

完成与交接

在将功能标记为完成之前,确认每个单元、验收标准、测试门禁、批准和 Git 记录。不要在此处归档已完成的文档:这属于 archivethespecs。

报告功能、分支、当前单元状态、精确的命令和结果、所有未验证的检查、实现/进度提交 SHA、风险以及下一步操作。以一个简洁的编号操作列表结束,标明更改的文件及其原因。如果被阻塞,说明阻塞原因以及如何恢复。

示例调用

Use buildtospecs for docs/specs/volunteerScheduling/. 从第一个可执行的工作单元开始,保留现有工作并运行所需的仓库门禁。

Individual skills in this repo

This repo contains 2 individual skills — each has its own dedicated page.

相关技能