来源：Harness engineering: leveraging Codex in an agent-first world 逐段提取所有为 Agent 搭建环境需要做的工作内容，覆盖所有流程和场景 日期：2026-02-28
第一章：仓库初始化脚手架（Repository Scaffold）
文章原文：“The initial scaffold—repository structure, CI configuration, formatting rules, package manager setup, and application framework—was generated by Codex CLI”
| # | 工作项 | 说明 |
|---|---|---|
| 1.1 | 仓库目录结构模板 | 预定义标准化的目录结构（src/、docs/、scripts/、tests/ 等），Agent 首次进入即可理解项目骨架 |
| 1.2 | CI/CD 配置生成 | 由 Agent 可读可写的 CI 配置（pipeline、lint、test、deploy），不依赖外部 UI 配置 |
| 1.3 | 格式化规则（Formatting Rules） | .editorconfig、.prettierrc、.eslintrc 等格式化配置，Agent 写出的代码自动符合格式 |
| 1.4 | 包管理器配置 | package.json/pyproject.toml 等包管理器锁定版本、脚本入口，Agent 可直接 npm run xxx |
| 1.5 | 应用框架脚手架 | 应用的基础框架代码（路由、状态管理、入口文件），Agent 在此基础上扩展而非从零开始 |
| 1.6 | AGENTS.md 初始版本 | ~100 行的”目录表”文件，指向 docs/ 中更深层的文档，作为 Agent 的入口地图 |
第二章：工程师角色重定义 — Agent 赋能基础设施
文章原文：“breaking down larger goals into smaller building blocks, prompting the agent to construct those blocks” “what capability is missing, and how do we make it both legible and enforceable for the agent?”
| # | 工作项 | 说明 |
|---|---|---|
| 2.1 | 任务分解机制 | 将大目标拆解为 Agent 可独立完成的小构建块（design → code → review → test），每块有明确输入输出 |
| 2.2 | Prompt 驱动的交互模式 | 人类通过 prompt 描述任务 → Agent 执行 → 开 PR。不手写代码，所有代码变更通过 Agent 产出 |
| 2.3 | Agent 自审回路（Ralph Wiggum Loop） | Agent 写完代码后：① 本地自审 → ② 请求其他 Agent review → ③ 回复反馈 → ④ 迭代直到所有 reviewer 满意 |
| 2.4 | 标准开发工具直接可用 | Agent 直接使用 gh（GitHub CLI）、本地脚本、仓库内嵌技能，不依赖人类复制粘贴上下文 |
| 2.5 | Agent-to-Agent 审查链 | Review 工作逐步从人类转移到 Agent-to-Agent，人类 review 变为可选 |
| 2.6 | 能力缺失的反馈回路 | Agent 失败时，不是”更努力”，而是问”缺少什么能力”→ 补充工具/抽象/文档 → 再让 Agent 执行 (加blocker) |
第三章：应用可理解性（Application Legibility）
文章原文：“we made the app bootable per git worktree” “wired the Chrome DevTools Protocol into the agent runtime”
| # | 工作项 | 说明 |
|---|---|---|
| 3.1 | 应用按 worktree 可启动 | 每个 git worktree 可独立启动一个应用实例，Agent 每个变更有自己的隔离运行环境 |
| 3.2 | Chrome DevTools Protocol 集成 | 将 CDP 接入 Agent 运行时，创建 skill 操作 DOM 快照、截图、页面导航 |
| 3.3 | Agent 可复现 Bug | Agent 能启动应用 → 导航到问题页面 → 触发 bug → 观察运行时事件 |
| 3.4 | Agent 可验证修复 | Agent 修复后 → 重启应用 → 重新验证 → 确认问题消失，形成闭环 |
| 3.5 | Agent 可推理 UI 行为 | 通过 DOM 快照和截图，Agent 能直接理解和推理 UI 状态与交互行为 |
| 3.6 | 本地可观测性栈 — 日志 | 部署 Victoria Logs（或类似），暴露 LogQL 查询接口给 Agent |
| 3.7 | 本地可观测性栈 — 指标 | 部署 Victoria Metrics（或类似），暴露 PromQL 查询接口给 Agent |
| 3.8 | 本地可观测性栈 — 链路追踪 | 部署 Victoria Traces（或类似），暴露 TraceQL 查询接口给 Agent |
| 3.9 | 可观测性数据收集器 | 部署 Vector（或类似）作为数据采集层，将应用的 logs/metrics/traces 扇出到各存储 |
| 3.10 | 可观测性按 worktree 隔离 | 每个 worktree 的可观测性栈是临时的，任务完成后自动拆除 |
| 3.11 | 性能可作为 prompt 约束 | 可观测性使得 “确保启动 < 800ms”、“关键链路 span < 2s” 这类 prompt 可机械验证 |
第四章：仓库知识作为记录系统（Repository Knowledge as System of Record）
文章原文：“give Codex a map, not a 1,000-page instruction manual” “progressive disclosure”
| # | 工作项 | 说明 |
|---|---|---|
| 4.1 | AGENTS.md 作为目录表 | ~100 行，只做导航，指向深层文档。不堆砌规则 |
| 4.2 | ARCHITECTURE.md | 顶层领域划分 + 包分层依赖图，Agent 理解”代码住在哪里” |
| 4.3 | docs/design-docs/ + index.md | 设计文档目录，含索引、验证状态、版本信息 |
| 4.4 | docs/design-docs/core-beliefs.md | Agent-first 运营核心信条，定义不可违反的基本原则 |
| 4.5 | docs/exec-plans/active/ | 当前活跃的执行计划（含进度和决策日志），版本化管理 |
| 4.6 | docs/exec-plans/completed/ | 已完成的执行计划归档，Agent 可回溯历史决策 |
| 4.7 | docs/exec-plans/tech-debt-tracker.md | 技术债务追踪器，记录已知债务、优先级、修复计划 |
| 4.8 | docs/generated/ | 自动生成的文档（如 db-schema.md），由代码/schema 自动产出 |
| 4.9 | docs/product-specs/ + index.md | 产品规格目录，含索引，描述用户场景和功能定义 |
| 4.10 | docs/references/ | 第三方依赖文档的 LLM 友好版本（xxx-llms.txt），Agent 不需联网查文档 |
| 4.11 | DESIGN.md | 全局设计原则和设计系统说明 |
| 4.12 | FRONTEND.md | 前端特有约束、组件规范、样式系统 |
| 4.13 | PLANS.md | 计划管理元文档（如何写计划、计划的生命周期） |
| 4.14 | PRODUCT_SENSE.md | 产品感知文档（用户是谁、核心价值、产品方向），Agent 做决策时参考 |
| 4.15 | QUALITY_SCORE.md | 各产品领域和架构层的质量评分，跟踪质量趋势 |
| 4.16 | RELIABILITY.md | 可靠性要求和 SLO 定义 |
| 4.17 | SECURITY.md | 安全约束、数据处理规则、认证要求 |
| 4.18 | 文档 CI 校验 — 新鲜度检查 | Linter/CI job 验证文档是否过时（最后更新时间 vs 代码变更时间） |
| 4.19 | 文档 CI 校验 — 交叉引用检查 | Linter/CI job 验证文档间的链接是否有效、引用是否存在 |
| 4.20 | 文档 CI 校验 — 结构正确性检查 | Linter/CI job 验证文档目录结构是否符合约定 |
| 4.21 | Doc-Gardening Agent | 定期自动运行的 Agent 任务，扫描不反映真实代码行为的文档 → 自动开修复 PR |
第五章：Agent 可理解性优化（Agent Legibility）
文章原文：“anything it can’t access in-context while running effectively doesn’t exist” “Slack discussion… if it isn’t discoverable to the agent, it’s illegible”
| # | 工作项 | 说明 |
|---|---|---|
| 5.1 | 隐性知识显性化机制 | 所有 Slack 讨论、口头决策、架构共识必须编码为仓库内 markdown，否则对 Agent”不存在” |
| 5.2 | 决策日志（Decision Log） | 重要技术决策记录在 exec-plans/ 或专用文件中，包含背景、选项、最终决定和原因 |
| 5.3 | 依赖选择偏好 — “无聊技术”优先 | 偏好可组合、API 稳定、训练数据中充分表示的技术栈。Agent 更容易建模 |
| 5.4 | 可选：自研替代不透明库 | 当外部库行为不透明时，由 Agent 自研子集实现（如自研 p-limit 替代品），紧密集成监控，100% 测试覆盖 |
| 5.5 | Agent Onboarding 文档 | 像给新员工写 onboarding 文档一样给 Agent：产品原则、工程规范、团队文化（甚至 emoji 偏好） |
| 5.6 | 外部知识内化为仓库文档 | 第三方文档以 xxx-llms.txt 形式存入 docs/references/，Agent 运行时无需联网 |
第六章：架构与品味的机械化执行（Enforcing Architecture and Taste）
文章原文：“enforce invariants, not micromanage implementations” “lint error messages inject remediation instructions into agent context”
| # | 工作项 | 说明 |
|---|---|---|
| 6.1 | 分层领域架构定义 | 每个业务领域按固定层级划分：Types → Config → Repo → Service → Runtime → UI |
| 6.2 | 依赖方向验证 Linter | 自定义 linter 校验代码只能”向前”依赖（Types→Config→…→UI），禁止反向依赖 |
| 6.3 | 跨切面关注点边界（Providers） | auth、connectors、telemetry、feature flags 通过统一的 Providers 接口注入，禁止直接引用 |
| 6.4 | 结构化测试（Structural Tests） | 验证架构约束的测试用例（如”某模块不能 import 某模块”），CI 中运行 |
| 6.5 | 品味不变量 — 结构化日志 | 静态校验所有日志调用必须使用结构化格式，不允许 console.log("xxx") |
| 6.6 | 品味不变量 — Schema/类型命名约定 | Linter 校验 schema 和 type 的命名是否符合团队约定 |
| 6.7 | 品味不变量 — 文件大小限制 | Linter 限制单文件最大行数，防止 Agent 产出巨型文件 |
| 6.8 | 品味不变量 — 平台可靠性要求 | 特定于平台的可靠性校验（如超时设置、重试策略、错误处理） |
| 6.9 | Lint 错误信息 = Agent 修复指导 | 自定义 lint 的错误信息设计为”Agent 友好”格式，包含具体修复步骤，直接注入 Agent 上下文 |
| 6.10 | 不变量 vs 自由度边界明确 | 明确区分”必须遵守的边界”和”允许自由发挥的空间”，Agent 在边界内有自主权 |
| 6.11 | 边界解析不变量 | 在数据边界处强制解析/验证数据形状（parse, don’t validate），具体用什么库不限 |
| 6.12 | 人类品味持续反馈回路 | Review 评论、重构 PR、用户 bug 报告 → 转化为文档更新或编码进工具 → Agent 自动遵守 |
| 6.13 | 当文档不足时规则晋升为代码 | 如果同一类问题反复出现，从”文档约束”升级为”lint 规则”机械化执行 |
第七章：合并哲学（Merge Philosophy）
文章原文：“minimal blocking merge gates” “corrections are cheap, and waiting is expensive”
| # | 工作项 | 说明 |
|---|---|---|
| 7.1 | 最小化阻塞式门禁 | PR 合并不需要人类批准（或仅需最小批准），依赖 Agent review + CI 自动验证 |
| 7.2 | 短生命周期 PR | PR 从创建到合并尽可能快，避免长期 open 的 PR 产生合并冲突 |
| 7.3 | Test Flake 容忍策略 | 测试抖动不阻塞合并，用后续 Agent 运行修复，而非无限等待 |
| 7.4 | Agent 自主合并能力 | Agent 可以 squash and merge 自己的 PR，无需等待人类操作 |
| 7.5 | 快速修正文化 | 出了问题用后续 PR 快速修复，而非在合并前追求完美 |
第八章：Agent 全覆盖生成（Agent-Generated Everything）
文章原文：“everything in the codebase” 列出的生成物清单
| # | 工作项 | 说明 |
|---|---|---|
| 8.1 | 产品代码生成 | 业务逻辑代码由 Agent 产出 |
| 8.2 | 测试代码生成 | 单元测试、集成测试、E2E 测试由 Agent 产出 |
| 8.3 | CI 配置生成 | Pipeline 定义文件由 Agent 产出和维护 |
| 8.4 | 发布工具生成 | 版本发布、部署脚本由 Agent 产出 |
| 8.5 | 内部开发工具生成 | 开发者效率工具（脚手架、代码生成器等）由 Agent 产出 |
| 8.6 | 文档和设计历史生成 | docs/ 下所有文档由 Agent 产出和维护 |
| 8.7 | 评估框架生成 | Agent 工作质量的评估 harness 由 Agent 自己产出 |
| 8.8 | Review 评论和回复生成 | PR review 评论和回复由 Agent 产出 |
| 8.9 | 仓库管理脚本生成 | 管理仓库自身的脚本（清理、迁移等）由 Agent 产出 |
| 8.10 | 生产监控看板定义 | Dashboard definition files 由 Agent 产出 |
| 8.11 | 人类角色：优先级 + 验收 | 人类做：排优先级、翻译用户反馈为验收标准、验证结果。Agent 挣扎时 → 识别缺失能力 → 让 Agent 自己写修复 |
第九章：自治能力递增（Increasing Levels of Autonomy）
文章原文：Agent 可端到端完成的完整链路
| # | 工作项 | 说明 |
|---|---|---|
| 9.1 | 代码库状态验证 | Agent 能在开始前验证当前代码库状态（编译通过、测试通过、无未提交变更） |
| 9.2 | Bug 自动复现 | Agent 能根据 bug 描述自动复现问题 |
| 9.3 | 失败录屏 | Agent 能录制展示 bug 的视频/截图证据 |
| 9.4 | 自动修复实现 | Agent 实现修复代码 |
| 9.5 | 修复自动验证 | Agent 通过驱动应用验证修复是否有效 |
| 9.6 | 修复录屏 | Agent 录制展示修复成功的视频/截图证据 |
| 9.7 | 自动开 PR | Agent 创建包含变更描述和证据的 PR |
| 9.8 | 自动回复反馈 | Agent 能回复 Agent 和人类的 review 反馈并迭代修改 |
| 9.9 | 构建失败检测与修复 | Agent 检测到 CI 失败后自动诊断和修复 |
| 9.10 | 升级机制 | 仅当需要人类判断时才升级给人类，其余自行处理 |
| 9.11 | 自主合并 | 所有检查通过后 Agent 自行合并变更 |
第十章：熵管理与垃圾回收（Entropy and Garbage Collection）
文章原文：“Codex replicates patterns that already exist—even suboptimal ones” “golden principles” “functions like garbage collection”
| # | 工作项 | 说明 |
|---|---|---|
| 10.1 | Golden Principles 文档 | 编码进仓库的核心原则（如”共享工具包优于手写 helper”、“边界验证不 YOLO”），Agent 每次运行都读取 |
| 10.2 | 偏差扫描 Agent | 定期运行的后台 Agent 任务，扫描代码是否偏离 Golden Principles |
| 10.3 | 质量评分自动更新 | 偏差扫描结果更新 QUALITY_SCORE.md，跟踪各模块质量趋势 |
| 10.4 | 自动重构 PR 生成 | 扫描发现偏差后，自动开定向小型重构 PR |
| 10.5 | 重构 PR 快速审查流程 | 大多数重构 PR 可 1 分钟内审完，支持 automerge |
| 10.6 | 模式复制防护 | 识别 Agent 会复制的不良模式 → 从源头修复 → 防止在代码库中扩散 |
| 10.7 | 技术债持续偿还 | 将技术债视为”高息贷款”，每日小额偿还而非攒到大爆发 |
| 10.8 | 人类品味一次编码、持续执行 | 人类的审美/偏好编码为 lint 规则或文档 → Agent 自动在所有代码上执行 |
全景总结：5 大支柱 × 工作项分布
| 支柱 | 核心理念 | 工作项数 |
|---|---|---|
| 仓库作为唯一真相源 | 一切知识在 repo 内，Agent 看不到的等于不存在 | 4.1 |
| 应用对 Agent 可见 | Agent 能运行、观察、验证应用 | 3.1~3.11 = 11 项 |
| 架构机械化执行 | 不变量靠代码执行，不靠文档自觉 | 6.1~6.13 = 13 项 |
| Agent 全链路自治 | 从复现到合并的端到端闭环 | 2.1 |
| 持续熵管理 | 自动扫描偏差、评分、修复、防扩散 | 10.1~10.8 = 8 项 |
| 总计 | 92 项 |
底层依赖关系
仓库知识体系（Agent 能理解项目）
↓
架构机械化执行（Agent 被约束不犯错）
↓
应用可观测性（Agent 能验证自己的工作）
↓
全链路自治（Agent 端到端交付）
↓
持续熵管理（Agent 维护长期健康）
每一层都依赖前一层，跳层建设效果会大打折扣。