Harness 工程：规格的强制执行体系

Agent 能读文件、改代码、跑命令之后，项目需要一个更明确的外壳来约束它。Harness 工程就是这个外壳：规则、权限、沙箱、检查、日志、回滚和人工确认点。

订单导出看似只是一个后台功能，但它能触发多种风险：导出敏感字段、绕过权限、拖慢数据库、生成不可追踪的文件、失败后无法恢复。Harness 的任务是让这些风险不能只靠“开发者记得”来控制。

Harness 守住什么

对于订单导出，Harness 至少要守住四类边界。

边界	说明	常见执行方式
数据边界	只能导出字段白名单，不导出敏感字段	字段白名单测试、敏感字段扫描
权限边界	只有具备导出权限的角色能操作	权限测试、接口鉴权、人工 review
性能边界	不允许大查询拖垮数据库	行数限制、异步任务、慢查询监控
变更边界	Agent 不能随意改权限体系和生产配置	禁区文件、分支保护、CI 检查

这些边界如果只写在口头规则里，很容易在快速迭代中被跳过。Harness 要把它们变成可执行检查。

项目规则

Harness 的第一层是项目说明。它应告诉 Agent：这个项目是什么、怎么验证、哪些地方不能碰。

# 订单后台 Harness 摘要

## 核心命令
- npm run test -- order-export
- npm run test -- order-list
- npm run build

## 导出规则
- 导出字段必须走字段白名单。
- 禁止导出手机号、详细地址、身份证号、用户备注和内部风控备注。
- 导出接口必须检查 order:export 权限。
- 超过 1 万行不能同步导出。

## 禁区
- 不修改生产数据库连接配置。
- 不绕过统一权限中间件。
- 不新增未经评估的文件存储公开地址。
- 不升级核心框架依赖。

这份说明不是给人看的装饰，而是 Agent 执行前必须读取的工作边界。

可执行检查

Harness 的第二层是命令和测试。订单导出的规格可以落到这些检查上：

npm run test -- order-export
npm run test -- order-permission
npm run test -- csv-sanitizer
npm run build

测试要覆盖关键风险，而不是只验证按钮存在：

• 无权限用户无法导出。
• CSV 表头只包含字段白名单。
• 敏感字段不会出现在文件内容中。
• 空结果生成表头。
• 超过行数限制时返回明确错误。
• 导出失败不会清空用户筛选条件。

CI 应要求这些检查通过。Agent 本地跑过只是第一层，CI 阻断才是团队层面的强制执行。

隔离环境

Agent 不应该直接在主干上修改高风险功能。订单导出适合在独立分支、worktree 或沙箱环境中完成。这样即使实现方向错误，也不会污染稳定分支。

隔离环境还包括数据隔离。用于验证导出的数据应该是脱敏样例或测试数据，不能直接连接生产库。下载文件也不应上传到真实外部存储，除非任务明确要求并经过确认。

人工确认点

Harness 不是把所有事情都自动化。对高风险动作，它应明确要求人工确认：

操作	为什么需要确认
新增敏感字段导出	涉及隐私和合规风险
修改权限模型	可能影响多个后台功能
支持大批量异步导出	需要任务表、存储、清理和监控设计
新增第三方存储或下载服务	涉及访问控制和数据生命周期
调整生产配置	影响发布和回滚

Agent 遇到这些动作时，应先产出方案和影响说明，而不是直接执行。

可观测性和审计

订单导出本身也需要可观测。Harness 应要求实现中留下排查线索：

• 谁在什么时间导出了什么范围的数据。
• 导出字段集合是什么。
• 导出成功、失败、超量、无权限分别有日志。
• 生成的文件是否有过期策略。
• 异常是否能关联到请求 ID 或任务 ID。

这些信息能帮助团队在事故后回答“导出了什么、谁导出的、是否越权、文件是否还能访问”。

回滚和恢复

Harness 还要考虑失败后的恢复。订单导出上线后，如果发现敏感字段泄露或数据库压力异常，团队需要能快速关闭入口、回滚代码或禁用导出任务。

适合写进 Harness 的恢复动作包括：

• 导出入口由 feature flag 控制。
• CI 产物和发布版本可追踪。
• 发现问题时能回滚到上一个稳定版本。
• 已生成文件有过期和删除机制。
• 审计日志能定位受影响导出记录。

没有恢复机制的自动化只是加速冒险。

分层建设

层级	适用情况	Harness 内容
个人项目	原型或低风险工具	README 命令、基础测试、Git diff 自查
小团队	真实后台功能	CI、权限测试、字段白名单、分支保护
中大型团队	涉及数据和合规	审计日志、风险库、人工确认、监控和回滚演练

不需要一开始就把所有系统建满。订单导出如果只是原型，轻量 Harness 足够；如果要进入生产后台，权限、字段和审计就不能省略。

Harness 的局限

Harness 可以拦住语法错误、构建失败、测试失败、敏感字段误导出、无权限接口放开等问题。但它不能替代业务判断。CSV 是否满足财务流程、导出能力是否应该开放给某个角色、数据保留多久合适，这些仍需要产品、技术和安全角色共同决定。

好的 Harness 会把“必须机器检查的部分”机器化，把“必须人判断的部分”显式化。

总结

Harness 工程让 Agent 的行动进入可控范围。它不是降低速度，而是把速度放进规则、检查和恢复机制中。

订单导出越接近真实数据，越需要 Harness。字段白名单、权限测试、CI、审计日志和人工确认点共同决定了这个功能能否可靠交付。

→ 下一步：组织流程工程