
为编码助手搭建可落地的仓库工作流:十条 harness 模式
来源标题:Ten harness patterns that you can apply to a real repo
文章提出用十种 harness 模式帮助编码助手在真实仓库中高效工作,核心是从团队已有工具入手。建议在 AGENTS.md 中列出首选工具,如用 rg 查找现有实现、用 git log 调查代码历史、用 git diff 核对改动。当同类错误反复出现时,再把相关指导固化为专门的 skill。
以下正文由 AI 翻译自 Hacker News 最新(原文版权归原站所有),可能存在偏差,重要内容请以原文为准。
编码助手需要一个清晰的起点:团队已经在用的工具、对不熟悉命令的说明,以及一些用于需要更多结构的工作流的技能。从搜索、git 历史、测试、linter 和小的仓库脚本开始。把 agent 否则只能靠猜的部分写下来。当同样的错误反复出现时,把那条说明转化为一个聚焦的技能。这样就给 harness 提供了一条实用的进阶路径:熟悉的工具、明确的参考,然后是可复用的工作流。
常见的开发工具之所以是有用的 harness 原语,是因为编码助手通常知道它们的语法,并且能直接查看它们的输出。rg、git log 和 git diff 这类命令能揭示仓库当前的结构和历史,而无需额外的集成。
在 AGENTS.md 里放一份简短的偏好工具清单:
- 在新增抽象之前,用
rg查找已有的实现。 - 用
git log --oneline -- <file>调查令人意外的代码。 - 在总结或提交变更之前,用
git diff查看差异。 - 用仓库的测试和 lint 目标来验证改动。 让这些说明针对你仓库中真正重要的决策。如果助手已经能正确使用某个命令,再写教程意义不大。有用的说明是:从哪里开始、遵循哪些项目约定、改代码前要查看哪些证据。
这些默认做法也能很好地跨助手和编辑器通用。即使模型或 agent 接口发生变化,仓库的历史、命令输出和测试依然有用。
内部 CLI 或自定义脚本需要更多解释。它的名字可能暗示了用途,却隐藏了重要细节:必需的 flag、工作目录、生成的文件或前置条件。
给 agent 一份简洁的参考,涵盖用途、何时使用、一个安全的示例,以及如何查看帮助。对于一个迁移辅助脚本,可以写成这样: 当变更需要数据库迁移时,使用 scripts/create_migration.py。 它按照本仓库的命名约定生成迁移文件。 示例:python scripts/create_migration.py --name add_user_timezone 帮助:python scripts/create_migration.py --help 在应用生成的迁移之前先检查它。 如果生成失败,先报告错误,再选择其他方案。
这份参考应当回答 agent 否则只能靠试错解决的问题。如果某个命令需要特定的环境,或会产出一个需要审查的产物,要说明这一点。较长的解释放在链接的工具参考里。
帮助输出给助手提供了一种在假设错误时恢复的途径。教它在编造另一个 flag 或重复失败的调用之前先查看该输出。一份小而持续维护的参考通常就够了;先从这里开始,再添加更复杂的工作流。
有时命令本身很直接,但周围的工作流总是出错。助手可能跳过前置条件、以错误的顺序执行步骤、误读结果,或在验证之前就把工作标记为完成。这就是使用技能的一个有用触发点。
技能应当说明顺序、步骤之间的决策以及完成标准。对于迁移辅助脚本,一个聚焦的工作流可以是: 在经验表明需要的地方加入恢复指引。如果生成失败,查看错误和帮助输出。如果验证暴露出有歧义的数据转换,在继续之前先把该决策摆出来。
围绕一个反复出现、且有可识别失败模式的任务来构建技能。它的价值在于承载仅靠命令参考无法提供的流程知识。
技能库的规模和一个任务需要多少技能是两个独立的决策。你可以为许多工作流维护说明,同时只加载与当前变更相关的那几个。
SkillsBench 提供了一个有用的信号。在其报告的任务组中,一个技能将表现提升了 18.0 个百分点,两到三个技能提升了 19.0 个百分点,四个及以上提升了 10.1 个百分点。其长度比较还显示,紧凑和标准长度的说明比全面的文档带来更大的收益。这些比较支持一个实用的起点:一小组聚焦的技能。它们并不为每个仓库或任务确立普遍的上限。
让每个技能的描述足够精确,以便 agent 能选中它:它处理什么、何时调用它,以及哪些相邻任务属于别处。避免多个技能对同一职责给出略有不同的说明。当你已经知道正确的技能时,显式调用它。
让 SKILL.md 以执行工作流所需的步骤和决策为中心。链接到扩展示例和背景材料,以便在相关时阅读。在修订技能时,移除过时的变通做法和重复的说明。否则,这些说明会积累出它本应消除的那种歧义。
agent 只有能检查结果,才能改进自己的工作。给它一份可发现的验证命令菜单,告诉它优先使用这份菜单,并把命令与团队真正依赖的检查连接起来。把命令定义放在仓库现有的任务运行器中。下面的示例使用 Makefile,但同样的方法也适用于其他运行器:在一个地方发现要运行什么以及如何运行。
按助手需要的结果来命名任务:lint、test-unit、test-integration 或 check。这些名称让验证目标更容易对应到命令,也让你无需重写 agent 说明就能更换底层工具。
目标还记录了正确的调用方式,包括从环境中重建时容易遗漏的细节: .PHONY: lint test-unit check
CI: static-analysis
lint: ## Run the project's lint checks uv run ruff check .
CI: unit-tests
test-unit: ## Run unit tests PYTHONPATH=. uv run pytest tests/unit check: lint test-unit ## Run lint and unit tests
(原文较长,此处译出前 6000 字,完整内容请点「打开原文」。)
正文由 探How 从来源站点 RSS 同步,内容未经改写;遇到排版缺失或需要图片、视频时请以原文为准。