返回资讯中心
外部精选
软件工程
#开发者实时流

Reverse-Spec-Flow:将现有源码转为AI可读规范的工作流

来源标题:Reverse-Spec-Flow

Reverse-Spec-Flow 发布了一套工作流,可从无规范、规范过时或已成黑盒的应用源码中生成供 AI agent 读取使用的 Markdown 规范,支持通过 ID 和索引按需查找。其每条陈述都标注源码位置(path:line),并由与撰写者隔离的验证 agent 逐条比对源码核查。

Hacker News 最新YY-EN40P2026/11/22 · 今天28 分钟阅读

以下正文由 AI 翻译自 Hacker News 最新(原文版权归原站所有),可能存在偏差,重要内容请以原文为准。

一个把现有源代码转成「AI 友好规格」供 AI agent 使用的工作流 docs/ 下的文档以及 AI agent 遵循的规则目前是用日语写的。 reverse-spec-flow 从应用的源代码中生成供 AI agent 阅读和使用的规格——这些应用没有规格、规格已过时,或者已经变成了黑盒。输出是 Markdown,让 agent 能通过 ID 和索引只查它需要的部分。生成规格的典型用途如下: 它面向希望用 AI agent 重新构想或维护现有系统的开发者和架构师。人也可以读这些规格,但主要读者是 AI agent。规格同样由 AI agent 编写。 因此,reverse-spec-flow 最优先通过机制而非 agent 的自我报告来保证以下两件事。 每条陈述都引用证据——每条陈述都带有支撑它的代码位置(path:line)。 与作者分开验证——由一个验证者 AI agent 对照被分析的源代码检查每条陈述,该 agent 与编写规格的 agent 相互隔离。它不仅确认引用了位置,还确认所引用的行确实支撑该陈述。 未知就写未知——任何无法从代码中确认的内容都不靠猜测填补,而是保留为 UNKNOWN。 2. 覆盖率——在代码图 100% 被规格化之前,工作不算完成 先构建用于计数的清单(分母)——第一步构建一张结构图(代码图),列出模块、入口点和外部连接,以及它们之间如何连接。 清单用完才算完成——工作流会统计代码图的每个元素是否都已被规格化,直到一个不剩才算完成。它不会停在「我们看过了主要部分」。 清单的正确性由适合目标技术的计数方法(见下文「Playbooks」)支持,并结合对配置文件等其他来源的交叉检查来发现遗漏。 对这两者,工作是否完成不由 agent 说「完成」来决定,而由门禁脚本 gates.sh 是否返回通过(exit 0)来决定。 便于 AI agent 查找——每个规格文件和需求都有唯一、稳定的 ID(例如 REQ-F-01)。 规格之间通过 ID 相互引用,工作流还构建从 ID 到文件的索引,以及从源文件到规格的反向索引,这样 AI agent 无需读全部内容,只查所需即可。 包含使用规格的 AI agent 必须遵循的规则(specs/AGENTS.md)。 重新构想的独立层——可以分开写:哪些依赖当前技术,以及任何重新构想的应用无论用什么技术都需要什么。 并行处理大型代码库——代码按业务领域逐个读取,因此永远不必一次性加载整个代码库。 如果 AI 工具支持子 agent(拆分工作并行运行的 AI agent),业务领域可以并行处理。 能扛住上下文溢出——进度和下一步操作写入文件并提交到 git。 如果 agent 的上下文溢出或会话结束,打开新会话即可从记录继续。 经验可传承——项目中得到的经验会被记录,通用的经验可以反馈回 reverse-spec-flow 本身 (见下文「Documentation」)。 不修改目标——规则要求 AI agent 不得修改源代码,gates.sh 会检测源代码的改动。规格写入独立的 git 仓库。分析 git clone 或源代码副本。 下文将 Claude Code、Kiro 等产品称为 AI 工具,在其中工作的 AI 称为 AI agent。 bash 和 git(macOS / Linux。Windows 上推荐 WSL。Git Bash 也能用,但检查耗时更长) 一个 AI 工具(见下文「支持的 AI 工具」) 你想分析的源代码 不需要数据库或专用平台。

1. 克隆到你想分析的文件夹旁边(例如 legacy-order-system/)

cd /path/to/workspace # legacy-order-system/ 在这里 git clone https://github.com/aws-samples/sample-reverse-spec-flow.git

2. 创建规格仓库

init.sh <target> <name (letters, digits, . _ -)> [purpose (asked interactively if omitted)]

./sample-reverse-spec-flow/init.sh ./legacy-order-system order-system rebuild

如果目标技术有对应的 Playbook(一组计数规则;见下文「Playbooks」),可以指定它(可选;不指定也能工作)

./sample-reverse-spec-flow/init.sh ./legacy-order-system order-system rebuild --playbook java-jaxrs-jpa 这会在目标旁边创建 legacy-order-system-spec/(规格仓库)。 后续所有工作都在 legacy-order-system-spec/ 上新开的会话中进行。 不要在运行 init.sh 的 sample-reverse-spec-flow/ 会话中开始分析。 如果你使用 Kiro IDE,在 Kiro IDE 中打开该仓库之前,先阅读 legacy-order-system-spec/HOST-SETUP.md。 3. 在你的 AI 工具中打开 legacy-order-system-spec/,并给出类似这样的指令: 阅读 spec-extraction/AGENTS.md。 要分析的源代码在 /path/to/workspace/legacy-order-system/(只读;不要修改它)。 填写 spec-extraction/AGENTS.md 中的 <PLACEHOLDER> 值,然后从 Phase 0 开始。 同样的指令也会显示在 init.sh 输出的末尾。 Phase 0 摄取 固定目标的 commit 并确定范围 Phase 1 代码图 列出模块、入口点、外部连接及其连接方式(覆盖率分母) Phase 2 分析 从每个视角分析(架构、需求、API、数据、行为、非功能性),并带证据

(原文较长,此处译出前 6000 字,完整内容请点「打开原文」。)

正文由 探How 从来源站点 RSS 同步,内容未经改写;遇到排版缺失或需要图片、视频时请以原文为准。

打开原文
去社区讨论 →