什么是 Harness Engineering
如果你觉得 AI 辅助编程像是在和一个聪明但健忘的实习生协作——它学东西很快，却不记得你昨天说过什么——那 Harness Engineering 就是你一直在寻找的答案。
实验性项目，非生产就绪
本项目的 Harness Engineering 实践目前处于初期探索阶段，文档描述的是设计意图，实际落地程度参差不齐：
- 推理型引导层（AGENTS.md、技能文档）：已完成基础定义，尚未经过多轮迭代和实战验证，内容仍在持续演进
- 架构依赖检查：当前未配置
dependency-cruiser或类似工具，分层边界主要依赖约定而非强制执行 - AI 代码审查 Agent：感知层中提到的"推理型"检查尚未实现，目前只有计算型传感器（lint / 测试 / 类型检查）
- 突变测试、架构漂移检测：属于规划中的方向，暂未引入
将文档描述的理想状态与当前实现之间的距离保持透明，是这个项目诚实的一部分。
从一个问题开始
你有没有遇到过这种情况：让 AI 帮你写了一段代码，它用了一种你们团队早就废弃的旧模式；或者，它生成的测试能跑通，但根本没覆盖你在意的边界条件？
这不是 AI 不够聪明，而是它缺少你团队的上下文。它不知道你们的架构约束，不记得上次代码审查的反馈，也不清楚"在这个项目里，错误处理应该这样写"。
Harness Engineering 就是解决这个问题的工程实践体系。
什么是 Harness？
在 AI 辅助编程语境中，"Harness"（驾驭层） 指的是 AI 模型之外的一切——所有用来引导 AI 行为的机制：
- 你写给 AI 读的说明文档（
AGENTS.md、Skills） - 自动运行的质量检查（lint、类型检查、测试）
- CI 流水线里的门控规则
- 项目结构本身带来的隐性约束
用一个图来理解：
你的 AI 编程工具
└── 构建方 Harness（系统提示、内置工具、代码检索机制）
└── 用户 Harness ← 这是你能控制的部分
├── 引导层（Feedforward）：告诉 AI 应该怎么做
└── 感知层（Feedback）：告诉 AI 它做得对不对Harness Engineering，就是持续设计和维护这个用户 Harness 的工程实践。
两个核心机制
Harness Engineering 围绕两个互补的控制方向展开：
引导层（Feedforward）
在 AI 行动之前就给出方向，提升"一次做对"的概率：
- 推理型：AGENTS.md、技能文档（Skills）、架构说明、编码风格指南
- 计算型：代码模板、脚手架脚本、代码修改工具（codemods）
引导层是被动的——它的价值取决于 AI 有没有"读到"并理解它。
感知层（Feedback）
在 AI 行动之后提供信号，让它发现并修正问题：
- 计算型：ESLint、TypeScript 类型检查、Jest 测试、架构依赖检查
- 推理型：AI 代码审查 Agent、语义分析
感知层是主动的——无论 AI 多自信，传感器都会说实话。
两者缺一不可
只有引导层：AI 记住了规则，但永远不知道有没有真正遵守。 只有感知层：AI 知道哪里错了，却不断犯同样的错误。
把两者结合起来，才能形成真正的自我修正闭环。
质量要尽量前移
一个经典的工程原则：越早发现问题，修复成本越低。
Harness Engineering 把这个原则应用到了 AI 辅助开发：
| 时机 | 应该运行什么 |
|---|---|
| 编写代码时 | LSP 实时提示、架构说明文档 |
| 提交代码前 | linter、快速测试套件、类型检查 |
| PR 合并前 | 完整测试套件、AI 代码审查 |
| 集成之后 | 更耗时的质量分析（突变测试、架构漂移检测） |
| 持续运行 | 死代码检测、依赖扫描、SLO 监控 |
什么是"可驾驭性"？
不是所有项目都同样容易被驾驭。可驾驭性（ Harnessability） 取决于项目的结构特性：
- 强类型系统：TypeScript 的类型检查天然就是一个可靠的感知传感器
- 清晰的模块边界：让架构约束规则更容易被自动化检验
- 框架约束：NestJS 的模块化结构限制了 AI 的"发挥空间"，减少了随意决策的可能性
- 一致的约定：统一的命名规范、错误处理模式……这些"环境提示"让 AI 更容易推断出"在这个项目里，应该这么做"
本项目在设计之初就把可驾驭性作为一等公民，这是它能作为 AI 友好型项目基线的核心原因之一。
这个项目的 Harness 长什么样
本项目的 Harness Engineering 实践分布在整个工程体系中：
引导层
| 机制 | 文件 | 作用 |
|---|---|---|
| AI 操作手册 | AGENTS.md、docs/AGENTS.md | 告诉 AI 核心原则、上下文获取路径、反馈循环 |
| 架构说明 | docs/03-architecture/ | AI 修改架构相关代码前的必读参考 |
| 技能文档 | .agents/skills/ | 专项任务的操作 SOP（如 git commit、PR 自动化） |
| 错误码目录 | src/constants/error-catalog.constant.ts | 防止 AI 硬编码错误信息或重复发明错误类型 |
感知层
| 机制 | 触发时机 | 验证内容 |
|---|---|---|
| TypeScript 编译 | 每次修改 | 类型安全、路径别名解析 |
| ESLint | 提交前 | 代码风格、潜在 bug |
| Jest 单元测试 | 每次修改 | 业务逻辑正确性 |
| E2E 测试 | CI | 接口契约、真实数据库集成 |
| CI 流水线 | PR 和推送 | 完整质量门控，包含多分支策略 |
想了解引导层和感知层的具体设计？分别查看：