将Claude Code技能从WebFetch迁移到新CircleCI CLI：关于工具与API设计的经验教训
内容提要
作者用Claude Code将调试CI失败的技能从WebFetch迁移到新的CircleCI CLI，仅用一行提示完成。CLI隐藏了REST API细节，支持`run watch`阻塞调用和`--condensed`过滤噪声，还新增`testresult list`快速定位失败测试。文章强调为AI代理设计CLI工具的重要性，如完善`--help`输出和服务器端过滤，可提升可靠性和效率。
延伸解读
CLI 优于通用 HTTP 工具
文章指出，当 AI 代理需要与外部系统交互时，使用专用 CLI 比通用 HTTP 工具（如 WebFetch）更可靠。CLI 隐藏了 REST API 细节，避免了手动构造 URL、处理缓存和解析 JSON 的步骤，从而减少了出错机会。例如，`circleci run watch` 用阻塞调用替代轮询，`circleci artifact --output` 免去 URL 拼接。因此，在编写技能时，应优先选择 CLI，若没有，可向供应商提出需求。
为 AI 设计 CLI 的关键特性
文章强调，为 AI 代理设计的 CLI 应具备可发现性和针对性优化。`--help` 输出是接口的一部分，代理通过遍历帮助树即可学会使用。此外，`--condensed` 标志在服务端过滤噪声，减少 token 消耗并保持上下文聚焦，是“为 LLM 设计”的典范。这些特性不仅提升效率，也降低了代理出错的概率。
迁移过程本身的价值
作者仅用一行提示就完成了技能迁移，但更有价值的是 Claude Code 在过程中发现了新功能（如 `testresult list`）和未预见的捷径。这表明，AI 代理不仅能执行指令，还能主动探索工具能力，优化工作流。这提醒开发者，工具设计应鼓励代理自主发现，而迁移任务本身也可视为对工具易用性的检验。
Q&A
如何将Claude Code的CircleCI调试技能从WebFetch迁移到新的CircleCI CLI？
作者通过一行提示让Claude Code自动迁移：先重新组织技能文件，将GitHub Actions和CircleCI部分分开，然后提示Claude Code用新的CircleCI CLI替换WebFetch调用。Claude Code会遍历CLI的帮助树（如circleci --help、circleci run --help）并运行实际命令来理解JSON输出，然后重写技能。
为什么作者决定从WebFetch迁移到CircleCI CLI？
因为WebFetch直接访问REST API存在多个问题：需要处理API细节、缓存（约15分钟）导致需要添加缓存破坏参数、私有仓库需要暴露API令牌。而新的CLI隐藏了REST API细节，处理认证，并提供更简洁的命令，如circleci run watch和--condensed标志。
circleci run watch命令相比轮询API有什么优势？
circleci run watch是一个阻塞调用，其退出码编码了构建结果（0、1、6、8等），而轮询API需要不断检查状态直到运行结束。对于AI代理来说，阻塞调用更简单可靠，避免了复杂的轮询逻辑。
circleci job output get --condensed标志有什么作用？
--condensed标志会从服务器端过滤掉stdout中的噪声和重复行，只返回有趣的输出，从而减小payload大小，适合直接提供给AI工具。这降低了token成本，并让代理的上下文窗口专注于关键信息。
circleci testresult list命令如何帮助调试CI失败？
circleci testresult list默认显示作业的失败测试，使Claude Code无需下载任何工件即可快速定位失败的测试。技能现在会先尝试此命令，仅在需要更多信息时才回退到下载TEST-*.xml文件。
作者从这次迁移中总结出哪些关于为AI代理设计CLI工具的经验？
经验包括：1) 为AI代理设计的CLI应隐藏底层API细节，提供更短更可靠的路径；2) CLI的--help输出是接口的一等部分，必须完善，以便代理能自行发现命令；3) 服务器端过滤（如--condensed）能降低token成本并保持上下文聚焦，是设计API或CLI时值得考虑的功能。
