Harness Engineering 与状态锚点

什么是 Harness Engineering

Harness Engineering 是一种以"脚手架优先"为核心思想的软件开发方法，尤其在 AI 辅助开发场景下越来越受到关注。

“Harness”（脚手架/支撑框架）这个词借用自工程领域，在软件中指围绕核心系统搭建的一套结构化支撑层，包括：

• 明确的文档约定（说明系统当前状态、设计决策）
• 测试框架和实验入口（可快速验证变更）
• 状态记录文件（捕捉项目在某个时间点的快照）
• 接口契约和边界定义

它的目标是让代码库对人和 AI 助手都更"可理解、可修改、可安全演进"。

状态锚点是什么

状态锚点（State Anchor） 是 Harness Engineering 的核心实践之一。

它是一个显式的文档文件（通常命名为 harness-state.md、project-state.md 等），用来在某个时间点精确记录系统的当前状态，就像 Git commit 对代码的作用，它对"上下文"做了一次快照。

典型内容

一个状态锚点文件通常包含：

## 当前状态（2026-04-09）

### 已完成
- [x] 核心数据模型定义完毕
- [x] API 接口初版上线

### 进行中
- [ ] 用户认证模块（50%）

### 已知问题
- /api/user 接口在并发场景下偶发 500

### 下一步
- 完成认证模块 → 接入集成测试 → 上线 v0.2

状态锚点的作用

1. 消除"现在在哪"的认知负担

每次回到一个项目，最耗时的事情不是写代码，而是重建上下文：“上次做到哪了？““这个模块稳定了吗？““还有什么坑没踩完？”

状态锚点直接回答这些问题，让你和协作者可以零摩擦地进入工作状态。

2. 给 AI 助手提供精确上下文

当你使用 GitHub Copilot、Claude 等 AI 工具辅助开发时，AI 没有持久记忆，每次对话都是全新的。如果你在对话开始时粘贴或引用 harness-state.md，AI 可以立刻理解：

• 项目是什么
• 现在处于哪个阶段
• 哪些部分是稳定的，哪些是危险区域
• 接下来的目标是什么

这比每次用自然语言重新解释项目背景要精准、高效得多。

3. 保护已验证的进度

开发过程中，“我已经验证过这个能工作"和"这个我没测过"是完全不同的。状态锚点帮助你显式区分：

• 经过验证的稳定部分（可以依赖）
• 正在实验中的部分（可能破坏）
• 已知有问题的部分（需要绕开）

这对 AI 辅助开发尤其重要——它防止 AI 在你不知情的情况下"修复"一个你其实已经刻意保留的行为。

4. 支撑增量演进

Harness Engineering 强调小步推进。每完成一个里程碑，就更新状态锚点，标记新的稳定基线。这样整个项目的演进路径是清晰、可回溯的，类似于在不稳定的地形上一步一步打下安全桩。

如何开始

对于个人开源项目，建议在项目根目录或文档目录创建 harness-state.md，内容不需要复杂，保持简洁即可：

# Project Harness State

## 日期
2026-04-09

## 项目概览
一句话描述项目是什么。

## 当前稳定基线
列出已经可以工作的核心功能。

## 进行中
当前正在做什么实验。

## 已知问题 / 风险点
需要注意的坑。

## 下一个里程碑
到达下一个稳定状态需要完成什么。

在每次重要变更后更新它，把它当成"给未来的自己写的交接文档”。

总结

状态锚点的本质是：把"你脑子里知道的事"外化成结构化文本，让它成为系统的一部分，而不是只存在于记忆中。