SuperAPI AI 工具集

atlas-write

编程与开发

查看项目

更新于 11-04 02:23

技能介绍

Atlas Write 用于生成 Project Atlas,即一份教人读懂代码库的地图。读者读完一个节点,应知道这一部分做什么、它与其他哪些部分有联系。地图由代码生成,之后可重新生成,不需要手工编辑。

使用前提:先用 git rev-parse --show-toplevel 取得仓库根目录,并且只在根目录内工作。代码是唯一来源;README、上下文文件或 ADR 若存在可作为证据,但不是前提条件,也不读取聊天记录、工单或会话记录。输出写入仓库忽略的路径,先把输出路径加入 .git/info/exclude,或使用用户指定的路径。

工作流程分为八步。第一步找出真实的部分:读构建清单,再读导入关系;一个部分之所以真实,是因为构建声明了它,或一组文件互相导入而很少导入其他东西。不要根据文件夹层级推断层次,深层文件夹不等于低层级;不要为了让图好看而虚构分组,二十个部分就画二十个,并在节点中说明项目有二十个部分;不要渲染空层级,每个分支的深度各自决定。当每个命名的部分都能对应到 ls 能找到的目录或构建目标时,此步完成。

第二步先锚定再写作:每个节点携带锚点三元组 [路径, 行号, 那里有什么],没有锚点就没有节点。要打开每个被锚定的文件,读锚点周围的几行;没读过的锚点只是带行号的猜测。当每个锚点路径都存在、且命名符号确实在命名行上时,此步完成。

第三步把节点写成四样东西:每个深度的每个节点都渲染同样四项,往下走一层:它内部有什么;这些内部事物之间的边;离开它的边;一段覆盖上述内容的段落。一条边之所以真实,是因为能指出承载它的调用点或类型引用;要用读者的话说出跨过这条边的是什么,例如“属于这里的文件”或“每轮一次读取”。没有说明载物的边只是一条线,教不了东西。向上抽象时保留跨边界的内容,丢弃留在内部的内容,父段落要基于抬升后的视角重新写,绝不把子节点的句子拼接起来。

第四步两种长度、平实用词:只有短和长两种正文长度,没有第三种。两者都用简化技术英语写,每句不超过 25 词,一段一个主题,最多六句,使用主动语态,每句都要朗读检查。先说这部分做什么,再说它是什么。命名要来自工作本身,绝不来自源码:地图的命名是给从未打开过仓库的人读的,代码里出现过某个词并不构成使用它的理由。测试每个名字的标准是:一个有能力的陌生人能否知道这是什么。按部分的功能给组命名,不要用团队内部比喻;绝不用“它不是什么”来命名;只有普通英语词,或项目发布了定义它的术语表时才允许使用。路径、类型和标识符保持原样,只出现在锚点、路径字段和行内代码中,它们是证据,不是标题。如果团队自己的词确实关键,把平实名称放在标题里,在定义它的段落中附带一次团队用词。

第五步处理流程与概念:流程是从入口到出口的一条代码路径,按有序步骤列出,每一步都可见,各带自己的锚点;流程没有深度,永不嵌套。概念是代码里出现的一个词,加上出现它的位置,它下钻到自己的证据,而不下钻到更小的概念。每个部分列出它体现的概念,这是部分与概念之间唯一的边。

第六步说明没找到什么:只有当构建清单声明时才写“没有”;其他地方写“未找到”,并说明查找了什么。当代码无法确定某个断言时,省略该断言并在报告中说明,不要用听起来对的句子填补空白。

第七步输出:一个 JSON 文件,每个节点一个对象,以 id 为键。节点字段包括 id、kind(part、flow、concept)、depth(数字)、parent、name、line、short、long、inside、among、leaving、concepts、steps、anchors、evidence、bottom、claims。depth 是数字,不是词。claims 记录每个断言写入时的提交以及来源路径,这样一个提交可以使一句话过期而节点其余部分仍然成立。bottom 标记锚点是出口的节点,该节点把路径作为跳进读者编辑器的入口,并说明这一点;不要下钻到每文件一个节点。当文件能解析、且 inside、among、leaving、concepts 中的每个 id 都作为键存在时完成。

第八步校验:一次一个节点,在没有见过你推理过程的上下文中运行 atlas-review。Claude Code 中使用 Agent 工具,每个节点一个代理;其他框架则在已输出的文件上开新会话。有虚假断言的节点返回第二步,不要凭记忆与检查器争辩,要打开它指出的行。当每个节点都返回零条虚假记录时完成。

最后给出报告,内容包括:输出路径、节点数量、每个分支的深度及停止原因、无法确定的断言,以及地图未覆盖的仓库部分。