TicketAgent Harness 实践说明

文档目标

这份文档回答的不是“什么是 Harness”，而是“它在项目里怎么活着”

这里重点说明三件事：

TicketAgent 具体把哪些 Harness 方法落成了真实仓库机制。
这些机制分别在处理哪些多轮协作问题。
未来扩展时应该沿着哪些方向增强，而不是重新退回“全靠聊天记忆”的状态。

这份实践总结主要来自两类来源：一类是 learn-harness-engineering/docs/zh/resources/ 中沉淀的课程方法，另一类是 TicketAgent / TicketAgentPrototype 在真实迭代中的工程经验。

问题背景

为什么这个项目必须把 Harness 当成工程控制系统

TicketAgent 同时包含政策问答、财务规则、Agent 编排、前后端交互、自动化测试和多仓库协作。如果没有 Harness，项目会快速出现以下典型失控点：

上下文断裂

换一个 session 或换一个 agent 后，项目状态只能靠回忆恢复，之前的判断依据和剩余工作很容易丢失。

规则散落

业务规则会同时出现在提示词、页面、接口和测试里，后续修改极易发生漂移。

完成标准模糊

Agent 容易在没有回归证据、没有文档回写的情况下提前宣布任务完成。

跨仓库事实漂移

原型仓库、正式仓库和共享文档各自维护一套说法，最终谁是最新事实变得不清楚。

落地结构

Harness 在 TicketAgent 里的三层结构

1. 短入口

根部 AGENTS.md / CLAUDE.md 保持精简，专注于开工步骤、收尾动作、深链接索引和工程红线，不承担“把全部背景再讲一遍”的职责。

2. 共享事实来源

跨仓库公共治理文档统一收口到 ticket-agent-context/docs/。业务仓库下的 docs/ 只是运行入口，通过软链接与同步脚本对齐 shared context。

3. 机械约束文件

真正驱动日常协作闭环的，是 feature_list.json、claude-progress.md、init.sh、自动化测试与质量文档，而不是单一说明文档。

入口层

路由与边界

用短入口把 agent 快速送到正确文档，减少总说明文件持续膨胀。

事实层

shared context

把架构、产品、安全、可靠性和质量文档沉淀成跨仓库统一真理源。

状态层

可追踪进度

feature_list.json 与 claude-progress.md 接住多轮会话连续性。

验证层

机械完成标准

初始化、类型检查、回归测试与质量文档共同定义“真正做完”。

课程映射

从 Learn Harness Engineering 到 TicketAgent 的具体落点

课程实践	TicketAgent 落点	解决的问题
`AGENTS.md` / `CLAUDE.md`	仓库根入口 + 深链接路由	避免总指令文件过长，降低入口噪声
`feature_list.json`	shared context 统一维护的功能状态表	防止 agent 主观宣布完成
`claude-progress.md`	跨 session 进度与 blocker 记录	保持多轮会话连续性
`init.sh`	初始化与治理文档完整性校验	每次开工前先进入可工作状态
`ARCHITECTURE.md`	5 层领域架构事实来源	把分层边界写死到仓库里
`QUALITY_SCORE.md`	测试和质量看板	把“做完”变成“有证据地做完”
`SECURITY.md` / `RELIABILITY.md`	安全、降级、拦截与人工分流规范	避免敏感知识只存在口头共识
`exec-plans/` 与 SOP	技术债、可观测性与 UI 验证流程	把长期演进和验证路径产品化

高级 Harness

OpenAI 风格高级 Harness 在本项目中的关键体现

入口文件刻意保持短小

AGENTS.md 只负责开工步骤、单任务原则、收尾动作、深链接索引和工程红线。深层知识全部拆进专题文档，符合“短入口，深链接”的思路。

高价值知识明确编码进仓库

架构、产品、安全、可靠性、质量、技术债与 SOP 都被显式版本化，避免 agent 依赖聊天记忆或口头约定。

shared context 接住多仓库协作

凡是同时影响正式实现仓库与原型仓库的事实，优先进入 ticket-agent-context/docs/。这样 Skill、原型实现与正式实现都能读取同一套治理事实。

“验证”被提升为 Harness 内建能力

项目把初始化、类型检查、自动化测试和质量回写都纳入完成定义。完成不再是主观判断，而是机械证据。

标准闭环

一次标准的 Harness 驱动开发流程

读取状态：先看 claude-progress.md 与 feature_list.json，确认当前优先任务和 blocker。
初始化环境：运行 init.sh，确保软链接、依赖和基础检查都正常。
从入口继续深读：按任务类型进入 ARCHITECTURE.md、SECURITY.md、RELIABILITY.md 等专题文档。
单任务实现：只处理一个 feature，遵守分层边界和规则真理源约束。
机械验证：运行自动化测试与类型检查，并收集可回写的验证证据。
回写事实：更新 feature_list.json、claude-progress.md、QUALITY_SCORE.md，必要时同步 shared context。

实际收益

这套 Harness 真正给项目带来了什么

更少的上下文断裂

换一个会话或换一个 agent 后，仍能通过入口文档和状态文件快速恢复工作现场。

更少的文档漂移

shared context 让原型仓库、正式仓库和技能上下文都围绕同一套事实运行。

更客观的完成标准

测试、类型、状态回写和质量文档共同定义完成，而不是凭主观感觉收尾。

更稳定的架构边界

规则、SOP 和质量约束都沉淀在仓库里后，敏感逻辑更不容易绕过既有分层。

后续扩展

接下来应该怎么继续增强

为高风险改动补更多 exec-plans/active/ 执行计划，而不是只在对话中口头约定。
继续把验证 SOP 产品化，让更多 UI / API 回归检查可以标准复用。
新增 shared context 文档前，先确认它是否真的是跨仓库事实，而不是临时草稿。
保持入口文件短小，新增规则放到专题文档，再由入口做深链接。

结论很简单：在 TicketAgent 中，Harness 不是“辅助材料”，而是让 agent 能持续、可靠、可审计地工作的基础设施。