返回资讯中心
外部精选
软件工程
#社区热议

为编码助手搭建高效harness的十种实践模式

来源标题:Ten harness patterns that you can apply to a real repo

面向真实代码仓库的编码助手需要明确的起点:团队现有工具、陌生命令的使用指引,以及结构化工作流的技能支持。文章建议从搜索、git 历史、测试、linter 和仓库脚本入手,把助手容易猜测出错的环节写入 AGENTS.md。当同类错误反复出现时,再将指引提炼为专用技能,形成从熟悉工具到可复用工作流的递进路径。

Hacker Newsnvmdbljstm2026/11/3 · 14 天前17 分钟阅读

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

Coding assistant 需要一个清晰的起点:团队已经在用的工具、对不熟悉命令的指引,以及少量用于需要更多结构的工作流的 skill。先从搜索、git 历史、测试、linter 和小型仓库脚本入手。把 agent 否则只能靠猜的部分写下来。当同样的错误反复出现时,就把这些指引提炼成一个聚焦的 skill。这样,harness 就有了一个务实的进阶路径:熟悉的工具、明确的参考、再到可复用的工作流。

常见的开发工具之所以是实用的 harness 基础组件,是因为 coding assistant 通常知道它们的语法,并且能直接检查它们的输出。rg、git log 和 git diff 这类命令无需额外集成,就能暴露仓库的当前结构和历史。

在 AGENTS.md 里放一份简短的首选工具清单:

  • 在添加抽象之前,先用 rg 查找现有实现。
  • 用 git log --oneline -- <file> 调查令人意外的代码。
  • 在总结或提交改动之前,先用 git diff。
  • 用仓库的 test 和 lint 目标来验证修改。 让这些指令只针对你仓库中真正重要的决策。如果 assistant 已经能正确使用某个命令,教程就没多大意义。有用的指引是:从哪里开始、遵循哪些项目约定、在改代码之前要检查哪些证据。

这些默认做法在不同 assistant 和编辑器之间也能通用。即使模型或 agent 界面发生变化,仓库的历史、命令输出和测试依然有用。

内部 CLI 或自定义脚本需要更多说明。它的名字可能暗示了用途,却隐藏了重要细节:必需的 flag、工作目录、生成的文件或前置条件。

给 agent 一份紧凑的参考,涵盖用途、何时使用、一个安全的示例,以及如何查看帮助。对于一个迁移辅助脚本,可以写成这样:

当改动需要数据库迁移时,使用 scripts/create_migration.py。 它按照本仓库的命名约定生成迁移文件。 示例:python scripts/create_migration.py --name add_user_timezone 帮助:python scripts/create_migration.py --help 在应用之前先检查生成的迁移文件。 如果生成失败,先报告错误,再选择其他方案。

这份参考应当回答 agent 否则只能通过反复试错才能解决的问题。如果某个命令需要特定的环境,或者会产出一个需要审查的产物,要说明。较长的说明放到链接的工具参考里。

帮助输出给 assistant 提供了一种在假设出错时恢复的办法。教它在编造另一个 flag 或重复失败的调用之前,先查看该输出。一份小而持续维护的参考通常就够了;在添加更复杂的工作流之前,先从这里开始。

有时命令本身很简单,但周围的工作流总是出错。assistant 可能跳过前置步骤、按错误顺序执行、误读结果,或者在验证之前就把工作标记为完成。这就是引入 skill 的一个有用触发点。

skill 应当说明步骤顺序、步骤之间的决策,以及完成标准。对于迁移辅助脚本,一个聚焦的工作流可以是:

在经验表明需要的地方加入恢复指引。如果生成失败,检查错误和帮助输出。如果验证暴露出有歧义的数据转换,在继续之前先把该决策摆出来。

围绕一个反复出现、且有可识别失败模式的任务来构建 skill。它的价值在于承载命令参考本身无法提供的流程知识。

skill 库的规模和一个任务需要多少个 skill 是两个独立的决策。你可以为许多工作流维护指引,同时只加载与当前改动相关的少数几个。

SkillsBench 提供了一个有用的信号。在其报告的任务组中,一个 skill 将性能提升了 18.0 个百分点,两到三个提升了 19.0 个百分点,四个及以上提升了 10.1 个百分点。其长度比较还显示,紧凑和标准长度的指引比全面文档带来更大的收益。这些比较支持一个务实的起点:一小组聚焦的 skill。它们并没有为每个仓库或任务确立一个普遍上限。

把每个 skill 的描述写得足够精确,让 agent 能选中它:它处理什么、何时调用,以及哪些相邻任务属于别处。避免多个 skill 对同一职责给出略有不同的指令。当你已经知道该用哪个 skill 时,就显式调用它。

让 SKILL.md 聚焦于执行工作流所需的步骤和决策。链接到扩展示例和背景材料,以便在相关时阅读。在修订 skill 时,移除过时的变通做法和重复的指令。否则,这些指引会积累出它本要解决的同样的歧义。

agent 只有能检查结果,才能改进自己的工作。给它一份可发现的验证命令菜单,告诉它优先使用该菜单,并把这些命令连接到团队实际依赖的检查上。把命令定义放在仓库现有的任务运行器里。下面的示例使用 Makefile,但同样的方法也适用于其他运行器:一个地方来发现要运行什么以及怎么运行。

按照 assistant 需要的结果来命名任务: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 同步,内容未经改写;遇到排版缺失或需要图片、视频时请以原文为准。

打开原文
去社区讨论 →