
Show HN:Specspec 将规范组织为从意图到结论的光谱
来源标题:Show HN: Specspec; specification as a spectrum from intentions to conclusions
开发者发布了一个名为 Specspec 的工具,用图谱把项目规范从核心意图一路关联到具体产出,让使用者可按不同部分自行决定委托给 AI 的抽象层级。该工具需 Python 3.11+ 和 Git,可从 PyPI 安装,init 命令会生成 AGENTS.md 指导编码代理先在图谱中规划再动手。作者称想法尚处早期,目前仅在代码和软件场景中试用过。
以下正文由 AI 翻译自 Hacker News 最新(原文版权归原站所有),可能存在偏差,重要内容请以原文为准。
specspec 把规格说明书组织成一条从意图到结论的光谱,服务于人与智能体的协作。一张 specspec 图谱从核心想法、宣言开始,一路连接到实现它的产物(代码行、书中的段落、演示文稿中的图形等)。对规格的每个部分,你都可以决定把哪个抽象层级委托出去。
你需要 Python 3.11+ 和 Git。从 PyPI 安装命令行工具(你的智能体和图谱编辑器都运行它),再用一两句话描述你的项目:
uv tool install specspec # 或:pipx install specspec
cd your-project
specspec init -m "# 帮助小团队就一份计划达成一致" -m "每个人都看到相同的日期,以及日期为何变动。"
然后在项目里启动你的编码智能体,像平常一样告诉它你想要什么。任何能执行 shell 命令的智能体都可以。init 写了一个 AGENTS.md 来教会它其余的事:先在图谱中规划再动手构建,记录它为你得出的结论,保持图谱与代码同步,并汇报它决定了什么、还有什么不确定。如果文件夹里还没有 Git,init 也会初始化 Git;如果你已有 AGENTS.md,它会追加内容。如果你的智能体读取的是别的指令文件,把它指向 AGENTS.md 即可。
到这里你就可以撒手不管了。当你想要更多控制权时,在图谱编辑器中打开图谱:想拉多远就从多远处俯瞰,打开智能体指给你的节点,修改某个节点或替换某个结论,然后让智能体继续。本页余下部分解释你看到的是什么。
用编码智能体构建时,很大一部分规格是在对话中写成的。你描述一个目标,智能体提出实现路径,你同意,它开始构建。几轮之后,你想要的和智能体建议的已经合并成同一份计划。有些细节留在那里是因为你需要它们,另一些只是因为它们是第一个可行的想法——而这份计划读起来两者毫无区别。
当你想要尝试别的做法时,这就成了问题。有了智能体,重建数据模型或 UI 只需几分钟。难的是知道旧的那套是为了什么,好让新的方案把它保留下来。
这也决定了你能多细致地跟进工作。一份把目标和细节混在一起的计划,没有一个合适的停止阅读的地方:你要么全部读完,要么全盘信任。大多数项目需要介于两者之间:对少数部分密切关注,对其余部分有个大致概念。
specspec 把计划以图谱的形式存放在仓库里、代码旁边,从你想要的排序到它如何实现。
每个节点都是 .specspec/ 下的一个简短 Markdown 文件。根节点是宣言:项目存在的目的。其余每个节点都声明自己的父节点,并且是从父节点得出的结论:它细化父节点,或确定实现父节点的一种方式。父节点就是该节点的意图。最外层的实现节点说明代码如何实现某项需求,并链接到相关的文件和行范围。
意图和结论是一条链接的两端,而不是两种节点。"让时间线易于阅读"是从宣言得出的结论,同时也是"在工作日时间线上展示任务"背后的意图。宣言与代码之间的每个节点都既是结论又是意图。靠近宣言的节点主要是意图:你想要什么、为什么,很多东西都系于其上。越往外越主要是结论:它如何实现。这个范围就是那条光谱,而节点在光谱上的位置由它在图谱中的位置决定。分支想有多深就有多深。
一个结论只是一种有效的结论。它基于推理——有些写在节点里,有些没有——而从同样的意图出发,也可以得出另一个结论。这在任何深度都成立,对你想要的东西也一样:当你的目标变化时,你改动靠近根节点的一个节点。一个节点有多牢固只有你自己知道,图谱对此不做标记。对一个 Python 库来说,语言属于宣言。对一个你并无偏好的应用来说,它是智能体在很靠下的位置得出的结论。
一个结论可以服务多个意图,这使图谱成为有向无环图而非树。在文件里,这不过就是第二个父节点:
---
id: OHYE-rI=
type: requirement
parents:
- rrvyriU=
- ABOH2aU=
---
# 高亮自上一版本以来发生变动的部分
将计划与上一次提交比较,并标出发生变动的日期。
你在图谱每个部分深入到什么程度,由你决定
图谱从意图延伸到结论,所以每一层深度都是一个你可以停下的地方。你可以只写宣言,让智能体画出它下面的一切。你也可以把某个分支一个结论一个结论地钉死,一直细到代码。阅读也是同样的道理:略读智能体画出的最上面两层,或者沿着某个分支一个节点一个节点地跟下去,直到你理解其中的每一步。超过你停下的那个点,智能体自行得出结论,并像其他节点一样把它的结论记录为节点。
在这个例子里,你从目标以及团队想要的两件事开始,其余由智能体画出。后来时间线变得重要,于是你接管了那个分支,一直管到代码,并亲自决定变动的日期要被高亮。"提案如何工作"仍然归智能体负责:仓库里的一个 JSON 文件、pull request 和 schema 检查。你从未仔细读过那个分支,但它随时都在。
标语"Engineering is on the spectrum now(工程如今在光谱之上)"指的就是这个范围。一端是亲力亲为的工程,每个决定都由你自己做。另一端是 vibe coding,由智能体替你做决定。用 specspec,你可以为项目的每个部分在光谱上选一个点,并随着项目推进移动它:在让你意外的地方深入,在事情已经稳定下来的地方后退一步。
图谱编辑器就是为此而生的。缩小视图,你能看到整张图谱,如果你愿意,还可以按与宣言的距离着色。放大到某个分支并选中一个节点,你就能读到它的文本,周围是它的父节点和子节点。图中的阴影区域……
(原文较长,此处译出前 6000 字,完整内容请点「打开原文」。)
正文由 探How 从来源站点 RSS 同步,内容未经改写;遇到排版缺失或需要图片、视频时请以原文为准。