让 CLI 文档不再与代码脱节:在每次变更时用测试和 Tessl verifier 拦截文档漂移
Stop your docs drifting from your code: catch it on every change
Tessl 发布三部分系列教程,第一部分教你为 CLI 的 README 与代码同步构建两项检查:一个运行 CLI 并比对命令与 README 的 Node.js 确定性测试,以及一个用自然语言规则由 LLM 逐次变更校验的 Tessl verifier。两项检查在分支阶段即可拦截忘记更新文档的改动,为第二部分每周扫描循环打下基础。
TL;DR:循环是一个智能体流程,它在你可控的环境中完成一项工作,具有明确的输入和输出。例如,文档同步循环会将 CLI 的 README 与其代码进行比较,并在两者出现偏差时发起拉取请求。但循环的好坏取决于你信任它的能力,因此在构建循环之前,你需要一个可以信任的检查。在这个由三部分组成的系列的第一篇文章中,你将构建这个检查:一个测试和一个 Tessl 验证器,用于检查对 CLI 文档的每一次更改。你将看到它在应该失败时失败、在应该通过时通过,到最后你将拥有一个本身就很有用的检查,即使还没有循环来容纳它。
问题:智能体交付代码的速度,快过任何人维护周边杂务的能力。
你的编码智能体可以在几分钟内交付一个功能。但周边的杂务就是另一回事了:文档漂移、测试变得不稳定、智能体指令过时,整整一周都是如此。谁在跟进所有这些?如果你不确定,那你已经遇到了这个系列要解决的问题。
全部手动完成无法扩展。你可以时不时让智能体“整理一下”,但如果没有办法检查它的工作,你只知道它运行了,而不知道它是否修复了什么。有更好的办法。它叫做循环,这个系列将带你构建一个。
你将从中获得什么:在本文中,你将为一个保持 CLI 文档与代码同步的循环构建检查。它是对每次更改的两项检查:一个确定性测试,即一个标准的 Node.js 测试,运行 CLI 并将其命令与 README 进行比较,用于脚本可以检查的内容;以及一个 Tessl 验证器,一条用平实英语编写的规则,由 LLM 对每次更改进行检查,用于需要判断的内容。这意味着忘记文档的更改会在你仍在分支上时被捕获,包括你的测试看不到的那些。更好的是,每个循环都需要这样的检查,因此一旦你构建了一个,第 2 部分中的循环就有了立足点。
什么是循环?
在 Tessl,循环是一个只做一项工作的智能体流程。它接受定义的输入,在仅具有该工作所需访问权限和密钥的容器中运行智能体,并产生定义的输出。例如,实现者循环从 Linear 工单中获取规格,运行智能体构建代码,并打开一个拉取请求。然后,审查者循环可能会检查该拉取请求。像这样将循环串联起来,你就得到了一个工作流。在这里,你将构建一个循环:一个保持 CLI 的 README 与其代码同步的循环。这个系列全是动手实践,所以如果你想先了解更大的图景,反馈循环工程解释了不同类型的循环以及它们为何重要,而上下文驱动工厂展示了它们如何组合成一个工厂。
检查输出才是最重要的。调度智能体很容易。信任它所做的事情才是真正的工作,也正是它让循环值得运行,而不是又一个 cron 任务。
文档漂移是一个很好的第一个循环,因为工作很小,漂移很容易发现,而且你可以检查结果。这也正是我们建议开始的地方:选择一个狭窄的问题,在信任它按计划运行之前手动运行循环。一旦你构建了这个,Tessl 的文档中有更多示例循环可供接下来尝试。
你将构建什么
在整个系列中,你将构建一个循环,让 CLI 的 README 与其代码保持同步:它会阻止那些忘记更新文档的更改,并对任何漏掉的偏差发起拉取请求来修复。它由三部分组成:
- 第 1 部分:对每次更改的检查(本文)。 每次更改都必须通过两项检查:一项测试将 CLI 的命令与 README 进行比较,以及一个 Tessl 验证器,用于检查每当命令发生变化时 README 是否已更新。
- 第 2 部分:每周扫描。 一个你自己编写的循环,按计划将文档与代码进行比较,并在它们出现偏差时发起拉取请求。
- 第 3 部分:闭环。 将检查变成一道关卡:在每个拉取请求上运行它并阻止失败的更改,然后利用扫描发现的问题来加强它。

一旦它作为关卡被强制执行,它就能阻止新的偏差。扫描会捕获任何漏网之鱼,而每次捕获都会告诉你该在哪里收紧关卡。本文构建这项检查,即图中的方框 1 和 2。
先决条件
为了顺利运行一切,以下是你在开始之前需要准备的内容。
- Node.js 和 git。 示例 CLI 没有依赖项。
- Tessl CLI 和一个免费的 Tessl 账户。 使用
curl -fsSL https://get.tessl.io | sh安装 CLI,然后运行tessl login。如果你还没有账户,可以在登录时注册一个免费账户。
如果下面的任何内容表现异常,验证器文档 中有更多细节可以帮助你。
第 1 步:设置一个示例应用
你需要一些东西来检查,因此本系列使用一个名为 tally 的小型示例 CLI,你将首先构建它。它没有什么特别之处:两个命令和一个 README,刚好足以让偏差发生。一旦你看到检查正常工作,你就可以(也应该)将相同的设置指向一个真实项目。
设置一个工作目录并跟着操作。创建一个包含三个文件的文件夹。首先是 CLI 本身,它位于 bin/tally.js 中:
#!/usr/bin/env node
// Every command the CLI supports, with the description shown in --help
const commands = {
add: 'Add a number to the running total',
reset: 'Set the total back to zero',
};
const [cmd] = process.argv.slice(2);
if (!cmd || cmd === '--help') {
// Print usage and the command list
console.log('Usage: tally <command>\n\nCommands:');
for (const [name, desc] of Object.entries(commands)) console.log(` ${name.padEnd(8)}${desc}`);
} else if (!commands[cmd]) {
// Reject anything that isn't a known command
console.error(`Unknown command: ${cmd}. Run tally --help to see commands.`);
process.exit(1);
}接下来是描述它的文档,位于 README.md 中。留意最后一行,因为它即将成为一个问题:
# tally
A tiny CLI that keeps a running total.
## Commands
- `tally add` adds a number to the running total
- `tally reset` sets the total back to zero最后是一个 package.json,这样 npm test 就有东西可以运行:
{ "name": "tally", "type": "module", "bin": { "tally": "bin/tally.js" }, "scripts": { "test": "node --test" } }将所有内容提交到一个名为 main 的分支上,因为稍后你将以此为基础比较更改:
# Create the repo and commit the three files
git init && git add -A && git commit -m "start"
# Make sure the branch is called main
git branch -M main第 2 步:设置 Tessl
你将在第 4 步中编写的验证器通过 Tessl CLI 运行,因此在仓库中设置 Tessl:
# Set up Tessl for your coding agents
tessl init
# Commit the new files
git add -A && git commit -m "Set up Tessl"tessl init 会为你使用的任何编码代理进行设置,所以看到 AGENTS.md、CLAUDE.md 和一些 MCP 配置文件出现时不要感到惊讶。
第 3 步:从确定性检查开始
在求助于代理之前,先检查任何普通旧脚本可以检查的内容。脚本比 LLM 更快、更便宜,而且每次都会给出相同的答案。“每个记录在案的命令是否真的存在?”是一个是或否的问题,所以它属于测试。Tessl 自己的 验证器指南 有一个简单的经验法则:如果脚本可以检查它,就写一个测试。如果需要判断,比如命令的描述是否仍然与其功能相符,就写一个验证器。
添加 test/docs.test.js。它运行 CLI 的 --help,然后将它列出的命令与 README 中的命令进行双向比较,这样它既能捕获消失的命令,也能捕获没人来得及记录的命令:
import { test } from 'node:test';
import assert from 'node:assert/strict';
import { readFileSync } from 'node:fs';
import { execFileSync } from 'node:child_process';
// Commands the README mentions, written as `tally <command>`
const readme = readFileSync('README.md', 'utf8');
const documented = [...new Set([...readme.matchAll(/`tally ([a-z-]+)/g)].map((m) => m[1]))];
// Commands the CLI actually lists when you run --help
const help = execFileSync('node', ['bin/tally.js', '--help'], { encoding: 'utf8' });
const actual = [...help.matchAll(/^ {2}([a-z-]+)\s/gm)].map((m) => m[1]);
// Sanity check: the README parsing found something
test('README documents at least one command', () => assert.ok(documented.length > 0));
// No stale docs: nothing in the README that the CLI lacks
test('every documented command exists in the CLI', () =>
assert.deepEqual(documented.filter((c) => !actual.includes(c)), []));
// No missing docs: nothing in the CLI that the README lacks
test('every CLI command is documented', () =>
assert.deepEqual(actual.filter((c) => !documented.includes(c)), []));运行 npm test,你应该看到所有三个测试都通过。请注意,该测试运行 CLI 并读取其真实的 --help 输出,而不是信任命令的另一种描述。这样,README 就是根据用户实际看到的内容进行检查,而不是根据可能同样过时的东西。
测试无法捕获的内容
这个测试无法判断行为。它知道 reset 存在,但它不知道“将总数重置为零”是否仍然是 reset 实际做的事情。为此,你需要能够阅读和推理的东西,比如 LLM,这就是 Tessl 验证器的用武之地。
第 4 步:添加判断检查
验证器是用纯文本编写的规则,存放在你的仓库中。每次运行时,LLM 裁判会根据它检查变更并返回通过或失败,因此它就像针对脚本无法表达的规则的测试。验证器发布文章涵盖了背景知识,如果你想了解的话;在这里,你将编写一个。与第 3 步的测试一起,它构成了两部分检查。
你的规则很简单:如果变更触及了命令,同一变更必须更新 README。添加 verifiers/cli-docs-sync.json:
{
"name": "CLI changes update the README",
"instruction": "When a change adds, removes, renames or changes the behavior of a tally command, the same change updates README.md so it still describes what the command actually does.",
"relevant_when": "The diff changes a command name, its description, or what a command does in bin/tally.js.",
"context": "README.md is the only user documentation for the tally CLI; users and agents rely on it.",
"scope": "diff",
"scope_reason": "Synchronization rule: the README update must ship in the same change as the CLI change.",
"checklist": [
{ "name": "readme-updated", "rule": "If the diff changes a command's name or behavior in bin/tally.js, the diff also changes README.md to describe it. Not applicable if no command changed." },
{ "name": "readme-matches-behavior", "rule": "For each command the diff changes, README.md's description says what the code in bin/tally.js now does. A README edit that mentions the command but still describes the old behavior fails. Not applicable if no command changed." }
]
}重要部分:
relevant_when- 验证器何时适用。保持具体,这样裁判只检查触及命令的变更。“diff 更改了 bin/tally.js 中的命令”足够具体;“diff 更改了 JavaScript”会为每次重构和拼写错误修复唤醒裁判。scope- 裁判查看的内容。使用file时,它一次判断一个文件,这适合“每个 API 路由都使用共享响应助手”这样的规则。使用diff时,它整体判断变更。此规则涉及两个文件一起更改,因此需要diff。验证器文档涵盖了其他选项。
第二个检查清单项是判断介入的地方:脚本可以判断 README 已更改,但只有能读取两个文件的东西才能判断它现在是否说了正确的内容。
然后通过向 tessl.json 添加 verify 块来告诉 Tessl 验证器覆盖哪些文件:
"verify": {
"groups": {
"docs-sync": {
"path": "verifiers/cli-docs-sync.json",
"level": "warn",
"include": ["bin/**/*.js", "README.md"]
}
}
}重要部分:
level-warn报告发现但不阻止任何操作。一旦你信任它,就将其切换为error。include- 此验证器覆盖的文件。它需要 CLI 和 README,这样裁判才能看到变更的两侧。
对验证器进行 lint 以确保其有效,然后提交两个文件:
# Check the verifier file is valid
tessl change verify lint verifiers/cli-docs-sync.json
# Commit the verifier and the tessl.json change
git add -A && git commit -m "Add docs-sync verifier"观察它失败
一个你只见过通过的检查并没有证明任何东西,所以让我们破坏一些测试看不到的东西。在一个新分支上,更改 reset 的功能:它不再回到零,而是恢复上次保存的总数。更新其在 bin/tally.js 中的描述,并完全不要动 README:
# Start a throwaway branch for the experiment
git checkout -b drift-test
# Change what reset does, without touching the README
sed -i.bak 's/Set the total back to zero/Restore the last saved total/' bin/tally.js && rm bin/tally.js.bak
git commit -am "reset restores the last saved total"
# The test still passes: every command name still matches
npm test
# Preview what the verifier will judge, then run it for real
tessl change verify --base main --dry-run --show-files
tessl change verify --base mainnpm test 仍然通过,因为每个命令名称仍然匹配。验证器是唯一注意到的东西。
试运行是一个方便的习惯:它告诉你确切会判断什么以及会进行多少次裁判调用,在你花费任何东西之前。这里它只计划了一次。然后实际运行失败,裁判告诉你确切原因。你会看到你的 docs-sync#cli-docs-sync 验证器被标记为失败,并为变更破坏的每个检查清单项提供一个发现。LLM 编写这些发现,所以措辞每次运行都不同,但它们会说类似这样的话:reset 的描述在 bin/tally.js 中更改了,而 README 仍然说它将总数重置为零。
输出中有几件事第一次看起来可能有点奇怪。摘要报告的是警告而不是错误,因为组的 level 是 warn,失败的 warn 检查不会阻止拉取请求。它还显示“0 个匹配文件”,这听起来令人担忧但并非如此:diff 验证器整体判断变更,而不是逐文件判断。
观察它通过
现在在同一分支上更新 README,并再次运行它:
# Bring the README in line with the new behavior
sed -i.bak 's/sets the total back to zero/restores the last saved total/' README.md && rm README.md.bak
git commit -am "docs: update reset description"
# Both checks should pass now
tessl change verify --base main
npm test这次验证器通过了,测试也通过了。现在你知道检查在应该失败时失败,在应该通过时通过,这是真正信任它的唯一方式。在继续之前整理一下:
git checkout main && git branch -D drift-test这个检查有一个盲点,而且是刻意设计的。它检查的是变更,因此看不到已经存在于你仓库中的漂移,也无法阻止从未经过它的变更。这正是循环的用武之地。
接下来是什么
你已经构建了一个检查:对脚本能检查的内容做确定性测试,对需要判断的内容做验证器。你已经看到它捕捉到测试遗漏的漂移,并在 README 修复后保持安静,所以你知道它值得信任。即使在还没有循环之前,这也值得保留:把测试和验证器复制到一个你关心的项目中,并将 include 路径指向你自己的代码和文档。
在第 2 部分中,你将通过编写第一个循环来覆盖检查的盲点:每周扫描一次,在整个仓库中比较文档与代码,并在它们发生漂移时打开一个拉取请求。
来源:Tessl Blog · tessl.io