Community研究与数据分析github.com

pax-k/build-right

将模糊的应用想法转化为基于证据的AI执行的Agent无关技能。

build-right 是什么?

该技能是一套Agent无关的技能,旨在将模糊的应用想法转化为基于证据的可靠AI执行。它提供了一个结构化的执行流程,从预执行工作(产品真相、MVP范围、操作规则和可执行任务队列)开始。核心规则强调“一次只做一件事,证明当前状态,窄范围变更,用正确证据验证,更新追踪器,然后进入下一个任务”。技能内置了状态解析器和执行助手等工具,用于确定任务是否就绪、检查门控条件,并确保执行与项目真相保持一致。它支持多种平台(如Claude Code、Cursor、Codex),并帮助开发者避免范围蔓延、证据不足和门控阻塞等常见陷阱,最终通过状态徽章报告清晰的执行状态。

兼容平台~Claude Code~Codex CLI~Cursor
npx skills add pax-k/build-right

Installed? Explore more 研究与数据分析 skills: affaan-m/uspto-database, affaan-m/scholar-evaluation, affaan-m/literature-review · View all 6 →

在你喜欢的 AI 中提问

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

文档

Build Right Execution

在预执行工作已产出产品真相、MVP范围、操作规则和可执行任务队列后使用此技能。

核心规则:

一次只做一件事。
证明当前状态。
窄范围变更。
用正确证据验证。
更新追踪器。
然后进入下一个任务。

必读内容

  • 在执行前始终阅读 references/workflow.md。
  • 在任务选择前、任务接收后以及推进到另一个任务前,阅读 references/gates.md。
  • 仅在触发审查、子代理审查有用,或涉及广泛证据/追踪器更改时,阅读 references/review-and-delegation.md。
  • 在完成或更新任务前,阅读 references/evidence-contract.md。
  • 在实施或审查时,若任务触及架构边界、公开 API、包所有权、提供者适配器、生成代码、错误语义、测试、可观测性、安全或可执行策略,阅读 ../build-right-engineering-principles/references/principles.md。
  • 创建缺失任务或拆分过大任务时,使用 assets/templates/task-template.md。
  • 仅通过下方展示的完整 Bun 命令形式使用捆绑的辅助脚本。不要依赖 PATH 别名或调用简短名称(如 continue-check)作为 shell 命令。
  • 在选择任务或推进队列前,使用状态解析器。报告并协调其决策,然后再继续。
  • 使用执行助手获得确定性的任务、契约和门控信号。将脚本输出视为判断的输入,而非权威。

操作模式

  1. 如果可用,运行只读状态解析器:

    bun <skill-path>/scripts/continue-check.ts --cwd <project> --format markdown --strict
    
  2. 在选择工作前,报告解析器发现:

    解析器决策: <决策>
    置信度: <置信度>
    下一步操作: <下一步操作>
    下一个任务: <任务或无>
    阻塞门控: <门控或无>
    外部跟进: <跟进或无>
    
  3. 在选择工作前,遵循解析器决策:

    • ask-founder:询问或报告创始人拥有的门控;不要继续。
    • wait-external:报告外部状态门控;不要继续。
    • create-blocker:创建或提出最小的AI拥有的阻塞项。
    • no-ready-task:停止并报告没有AI拥有的任务就绪。
    • invalid-state:停止并协调矛盾的追踪器/门控状态。
    • continue-active-task 或 execute-task:精确选择该任务。
  4. 如果可用,运行只读执行助手:

    bun <skill-path>/scripts/execution-check.ts --cwd <project> --mode next-task --format markdown
    
  5. 阅读任务、冲刺/里程碑追踪器、权威文档和本地代理指令。

  6. 打印任务接收信息:

    当前任务: <任务ID或路径>
    完成标准: <可观测的完成标准>
    非目标: <明确排除项>
    假设基础: <创始人声明 | AI推断 | 原型假设 | 仓库证据支持 | 公开证据支持 | 客户证据支持>
    可逆性: <简单 | 中等 | 困难>
    学习钩: <此任务将如何产生证据>
    测试来源: <仓库本地路径 | 安装路径 | GitHub 源 | 发布标签 | 不适用>
    基线证据: <工件或命令>
    验证阶梯: <聚焦 -> 更广泛检查>
    证据目标: <任务文件或证据文件>
    
  7. 当任务路径存在时,以 task-contract 或 all 模式运行执行助手,然后编辑前协调任何缺失字段。

  8. 在编辑前检查当前工作区状态。

  9. 捕获基线证据。

  10. 实现满足任务的最小变更。

  11. 分层验证。

  12. 当所需审查触发条件满足且子代理工具可用时,运行子代理审查。如果不可用或被禁止,记录跳过的审查并在关闭前替换验证。

  13. 在标记任务完成前记录证据。

  14. 仅更新相关追踪器/文档。

  15. 在选择另一个任务前,使用完整的 Bun 状态解析器命令,并以 stop-gates 模式运行执行助手。

  16. 在决定是否安全选择另一个任务前,再次报告解析器发现。

  17. 在以下门控处停止:创始人、外部状态、验证失败、任务过时、来源不匹配、开放冲突、非AI所有者或发布声明。在门控解决或明确转换为就绪的AI拥有的任务之前,不要推进到下一个任务。

  18. 根据项目工作流提交或交接。

未就绪规则

如果缺少权威文档、MVP 范围、执行规则或任务文件,不要假装执行已就绪。将用户引导至 /build-right-preflight,或创建建立缺失执行面的最小 Sprint 0 阻塞项。

原型任务仅在可逆性、学习钩以及在产品真相前需要验证时,才能从 prototype-assumption 运行。

对于技能发布/手动试验,记录测试的确切来源。如果安装或调用的技能与仓库本地技能来源不同,则将试验标记为 partial-needs-rerun 并且不要将发布门控推进到就绪。

范围规则

不要静默扩大范围。如果任务揭示了无关工作,创建一个跟进问题,并仅在选择的任务边界内继续。

停止/询问门控

在每个任务后,检查下一步是否真正由AI拥有且就绪。当下一步需要以下条件时停止并询问或报告阻塞项:

  • 创始人拥有的产品、定位、买方/用户或 MVP 决策
  • 就绪或活跃的任务所有权不是AI
  • docs/conflicts.md 中的开放冲突
  • 外部发现、搜索索引、发布、密钥、付费服务或生产访问
  • 验证失败、任务状态过时、来源不匹配或证据模糊
  • 跳过了必需的子代理审查且没有等效替代

只有在每个下一个任务就绪、由AI拥有、有证据支持且未被这些门控之一阻塞时,才允许通过准备好的队列继续。

用户可见状态徽章

每个最终响应以确切的一个状态徽章块结束:

✅ [完成] 状态: 完成
决策: <决策/结果>
下一步操作: <下一步操作或无>
需要用户输入: <无 | 简明询问>
被阻塞: <无 | 阻塞项>

使用此状态映射:

  • ✅ [完成] 状态: 完成 用于已完成且带有证据、验证和追踪器更新的任务。
  • 🟢 [绿色] 状态: 全部正常 用于在实施开始前的 execute-task 或 continue-active-task。
  • 🟡 [黄色] 状态: 需要输入 用于 ask-founder。
  • 🟠 [橙色] 状态: 需要工作 用于AI拥有的后续工作但尚未成为就绪执行任务。
  • 🔵 [蓝色] 状态: 等待外部 用于 wait-external、发布、索引、凭证、付费服务、生产访问或第三方状态。
  • 🔴 [红色] 状态: 被阻塞 用于 create-blocker、no-ready-task、invalid-state、开放冲突、验证失败、过时/来源不匹配、非AI拥有任务所有权或跳过了必需的审查且没有替代。

相关技能