Harness Engineering

深度优先的工作模式 Mindset

遇到问题（例如 Agent 无法修复 Bug）时，解决方案永远不是“人去写代码”，而是：

• 识别缺失的能力： Agent 是因为看不到日志？还是不懂 UI 结构？
• 构建工具： 为 Agent 编写工具（如 Screenshot tool）或文档。
• 注入上下文： 将修复后的逻辑作为新能力赋予 Agent。

Ralph Wiggum Loop (反馈闭环) Workflow

人类仅通过 Prompt 与系统交互。所有的执行细节都封装在 Agent 的自我修正循环中：

视觉与交互感知 Tools

• 每个 Worktree 独立启动： Codex 针对每个任务启动一个独立的 App 实例。
• 集成 Chrome DevTools Protocol： 赋予 Agent 截图、抓取 DOM 快照、监听网络请求的能力。
• 能力解锁： 这使得 Agent 可以不仅“写代码”，还能“重现 Bug”和“验证 UI 修复”。

临时可观测性栈 Infrastructure

• Ephemeral Stack： 为每个开发任务部署临时的日志和指标栈（LogQL/PromQL）。
• 可量化的 Prompt： 工程师可以发出极度具体的指令，如 “确保服务启动时间在 800ms 以内” 或 “检查关键路径中没有 Span 超过 2 秒”。Agent 可以通过查询指标来验证这一目标是否达成。

渐进式披露架构 Architecture

• 目录索引法： `AGENTS.md` 仅包含指向 `docs/` 中具体文件的指针。
• 按需加载： Agent 先读取目录，再根据任务读取特定的设计文档或计划，而非一次性吞下所有信息。

单一事实来源 (SSOT) Protocol

• 禁止隐性知识： 任何 Slack 讨论、口头约定若未转化为 Repo 中的 Markdown 文档，对 Agent 来说就是不存在的。
• 计划即代码： 复杂的任务被分解为 `exec-plans` 存入代码库。Agent 可以读取当前进度，知道已完成了什么，以此实现长时任务的中断恢复。

自定义 Linter 作为教材 Tooling

普通的 Linter 只报错，Agent 的 Linter 需要教学。

• 教学式报错： 编写自定义 Linter，当检测到违规（如错误的命名、过大的文件）时，报错信息必须包含具体的修复指令和正确示例，直接注入 Agent 上下文。
• 强制分层： 编写结构化测试，禁止跨层依赖（例如：UI 层禁止直接调用数据库层），确保架构不被“抄近道”的 Agent 破坏。

黄金原则 (Golden Principles) Standards

• 边界严查： 强制要求所有数据输入必须经过 Schema 验证（如 Zod）。禁止 Agent 写出“猜测数据结构”的代码。
• 偏好无聊技术： 选择那些训练数据多、API 稳定的“无聊”库，Agent 更容易掌握。

自动垃圾回收 (Garbage Collection) Automation

• Doc-Gardening Agent： 专门的后台 Agent，定期扫描代码与文档的差异，自动提交 PR 修复过时文档。
• Refactor Agent： 自动扫描不符合“黄金原则”的代码（AI Slop），发起微重构 PR。
• 策略： 每天进行小规模的清理，而不是每周五进行一次大规模的人工“铲屎”。

极速合并策略 Process

• 极简门槛： 减少人工 Review 的阻塞。
• 快速试错： 遇到测试 Flake（不稳定），与其阻塞流水线等待人工排查，不如让 Agent 立即发起一个新的 PR 尝试修复。