learn-harness-engineering

在最近的 Vibe coding 时候，当项目比较大，功能比较多的时候，agent 经常会迷失在项目里，最终的效果不如我预期的好，为此，学习了一些Harness Engineering 的知识。

拿来直接用的话参考

• resources

• learn-harness-engineering

如何让 agent 看懂项目，继续上次会话

lecture-03-why-the-repository-must-become-the-system-of-record

为了防止让agent 重开之后忘记当前的项目/需要完成何种进度，需要在项目根目录下放置一些文件，比如

• AGENTS.md
• ARCHITECTURE.md 描述产品架构，技术栈各层的职责，数据流
• PRODUCT.md 描述产品功能范围和当前阶段目标
• init.sh

为什么需要将这些文件打散放到不同的md文件中，塞到一个AGNETS.md里不就好了？

• 考虑上下文预算，一开始的prompt里面塞大量信息会占用大量上下文预算，在contex有限的情况下 256k, 128k, 过多信息导致agent处理不高效
• 中间迷失效应， 长文本中 agnet 对开头，结尾信息敏感，对中间信息出现遗失
• 指令信噪比 塞的prompt 在 agent 运行是到底有多少会被用到
• 路由文件 相当于路由表，文件大纲
• 渐进式披露 先给概要信息，需要的时候再给详细信息。

lecture-04-why-one-giant-instruction-file-fails

跨会话工作的连续性

https://walkinglabs.github.io/learn-harness-engineering/zh/projects/project-03-multi-session-continuity/

每次开始前初始化；每次结束前交接；所有状态以文件，测试，git checkpoint 等形式保存

在初始阶段/冷启动（空项目）阶段，先创建 环境，测试，自举契约，任务分解，而不是顺手做一个任务，实现一个功能

AGENTS.md          # agent 每次启动/结束必须遵守的流程
PROGRESS.md        # 当前进度、已完成、进行中、下一步
DECISIONS.md       # 关键技术决策及原因
feature_list.json  # 功能清单和状态
init.sh            # 初始化/验证脚本
Makefile           # 标准命令入口
tests/             # 至少一个能跑通的测试

• 说下 feature_list.json

这相当于一个功能状态机对 agent 起到约束，对于多功能任务，只靠 PROGRESS.md 还不够。需要一个机器可读的功能清单，约束 agent 一次只做一个功能，并且不能没有验证就标完成

{
  "features": [
    {
      "id": "document_chunking",
      "name": "文档分块",
      "status": "passing",
      "validation": {
        "command": "make test TEST=tests/test_chunking.py",
        "evidence": "tests passed on 2026-05-12"
      }
    },
    {
      "id": "metadata_extraction",
      "name": "元数据提取",
      "status": "failing",
      "validation": {
        "command": "make test TEST=tests/test_metadata.py",
        "evidence": null
      }
    },
    {
      "id": "index_progress_ui",
      "name": "索引进度 UI 显示",
      "status": "failing",
      "validation": null
    },
    {
      "id": "qa_with_citations",
      "name": "带引用的问答",
      "status": "failing",
      "validation": null
    }
  ]
}

• 说下 MakeFile

Makefile 不是 C++ 专用工具，它本质上是一个通用的任务入口 / 自动化脚本调度器
它最早常用于 C/C++ 编译，因为 C/C++ 编译流程复杂：编译、链接、增量构建、依赖判断。但 make 并不关心你运行的是 C++、Python、Node、Go、Rust，还是文档生成命令。它只负责：

目标名:
	要执行的命令

注意：命令前面必须是 Tab，不是普通空格

例如一个python项目的 Makefile 可以是：

setup:
	pip install -r requirements.txt

test:
	pytest

lint:
	ruff check .

format:
	ruff format .

check: lint test

之后就可以运行

make setup
make test
make check