SuperAPI AI 工具集

brief-best-practices

编程与开发

查看项目

更新于 10-15 19:55

技能介绍

用途:在需要反复迭代(工作会进入循环)或出错代价很高时,编写或更新 BRIEF.md。BRIEF.md 是“验证方的规格”,是某一表面“好”的成文品味,使智能体可自行验证迭代、无需猜测或频繁打断。它处在 VISION → SPEC → BRIEF → HARNESS → LOOP → BOUNDARY 链条中的 BRIEF 层:SPEC 是合同(要建什么),BRIEF 是门槛(何为“好”、由谁判定)。琐碎的一次性改动无需 BRIEF。

位置与命名:始终命名为 BRIEF.md,与所管辖的表面同目录(项目根、apps/foo/BRIEF.md、packages/bar/BRIEF.md 或文档子树)。带日期的工作记忆放在其旁,如 DELTA.md(每轮差距,已排序)与 DEVIATIONS.md(不可行→最近可行,记录在案);BRIEF.md 是现在时法则,变更历史交给 git。

七个槽位(固定关切,顺序固定,形态可调):Bar(一句话说明何为可发布);Dimensions(“好”分解出的少数维度);Floors(每个维度的下限及测量方式,无测量方法的下限无效);Oracle(独立验证者:跑什么、谁判定、为何无法作弊,制作者≠判定者);Never(无论如何都算失败的绝对禁区);Decisions(已定取舍与假设,避免重复提问);Boundary(哪些必须由人操作:发布、生物识别、线上密钥、真正的未知)。任何模糊槽位应配具体范例或反例。

治理前言与编写规则:每份 BRIEF.md 以一行法则开头,声明现在时、无叙述性历史、Decisions 与 Boundary 仅经人确认方可修改。优先匹配仓库已有的“家规”形态;以证据为基础,不虚构阈值、信号或行为;Oracle 必须独立;下限是门槛不是上限;论断要与实际执行能力相称;保持简洁;发现规格与实现漂移要上报由人决定。

生命周期与循环:创建时人工批准,先搭 harness 再迭代;维护时 Decisions 随答疑增长、Floors 随门槛升高收紧;表面删除时移除或归档 BRIEF.md。harness 跑 Floors 输出带证据的通过/失败,Oracle 独立判定主观维度,循环按 act → verify → orient → decide 迭代直到所有 Floor 通过或给出有界的诚实阻塞。有人值守时可对琐碎工作省略仪式;无人值守时 BRIEF.md 与 harness 是唯一兜底,绝不越过 Boundary。参考资料含 template.md 与 example-payments.md,后者为转账流程的客观范例。