Harness 工程实战：用 AGENTS.md 与 Codex 搭建 Agent-First 规模化 AI 编码骨架

1. 为什么 Agent-First 团队需要一个 Harness 骨架如果你正在带一个 3 到 10 人的小团队最近半年大概率经历过这种场面每个人都在用 Codex 或类似的编码 Agent单点效率确实高但合到一起就乱套。有人把任务描述写在聊天记录里有人把规范塞进一个 800 行的 AGENTS.md还有人干脆每次对话重新贴一遍架构说明。结果就是同一个仓库里Agent 生成的代码风格碎片化、依赖方向混乱、文档和实现各说各话。Harness 工程要解决的就是这件事。它把「让 Agent 稳定干活」从玄学 Prompt 变成一套可复现的工程骨架环境怎么设计、上下文怎么注入、任务怎么分发、结果怎么验证、失败怎么回滚。人不再负责逐行写代码而是负责掌舵、搭脚手架、建反馈回路。这套骨架里有两个核心构件。第一个是 AGENTS.md它不是百科全书而是一张「目录页」负责把 Agent 导航到真正的知识源。第二个是 Codex 的接入配置让多个 Agent 共享统一的模型通道和 Key 管理避免每个人各配一套、额度分散、调用链路不可观测。我试过把这两件事拆开做结果发现单独优化 AGENTS.md 而不统一模型通道多 Agent 协作时依然会出现「同一个任务在不同 Agent 手里行为不一致」的问题。所以这篇会把 AGENTS.md 模板和 Codex 接入配置放在一起讲最后给一套本地验证 Agent 调用链路的可复制步骤。适合谁看正在把 AI 编码从「个人玩具」推进到「团队基础设施」的工程师、Tech Lead以及需要管理多个 Agent 任务分发的平台同学。读完你应该能拿到一份可直接落地的 AGENTS.md 骨架、一份 Codex 的 settings.json 配置以及一条能跑通的验证链路。2. TaoToken 前置统一 Key 与 API 通道多 Agent 协作的第一个坑不是 Prompt是凭证管理。如果每个 Agent 实例、每个开发同学各自持有不同的 Key你会遇到三个问题额度无法统一观测、调用失败无法定位是哪个环节、切换模型要改一堆配置。TaoToken 在这里的角色是提供统一的 API 通道。你可以在官网 https://taotoken.net/?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_content 了解整体能力实际接入时用的是 API 端点 https://taotoken.net/api这个地址不加 UTM 参数直接写进配置文件即可。对 Harness 工程来说统一通道的价值在于所有 Agent 的模型调用都经过同一个入口你可以在一个地方管理 Key、观察调用量、按项目或按 Agent 分配额度。这比在每个开发机上散落一堆配置要可控得多。具体操作上你需要先拿到一个 API Key。进入控制台创建即可控制台入口https://taotoken.net/console?utm_sourcetaotoken_aicg_blog_endutm_contentconsoleutm_campaignrewriteAPI Keys 管理https://taotoken.net/api-keys?utm_sourcetaotoken_aicg_blog_endutm_contentapi-keysutm_campaignrewrite创建 Key 的时候建议按用途命名比如harness-codex-dev、harness-codex-ci这样后面看调用日志时能直接对应到具体场景。如果你团队里有人专门跑长期编码任务或 Agent 流水线可以单独了解 Coding PlanCoding Planhttps://taotoken.net/coding-plan?utm_sourcetaotoken_aicg_blog_endutm_contentcoding-planutm_campaignrewrite注意Key 只创建一次就够不要在每个 Agent 配置里重复粘贴明文。推荐用环境变量注入配置文件里只引用变量名。拿到 Key 之后先别急着写 AGENTS.md。建议先用模型对话页面确认通道可用模型对话https://taotoken.net/chat?utm_sourcetaotoken_aicg_blog_endutm_contentchatutm_campaignrewrite在对话页面里发一条简单请求确认返回正常再进入下一步的配置文件编写。这一步能帮你排除掉「Key 无效」「端点写错」这类低级问题避免后面调试 Agent 时把配置错误误判成 Prompt 问题。3. 可复制配置AGENTS.md 模板与 Codex settings.json这一节是整篇的核心交付物。我会先给 AGENTS.md 的目录页模板再给 Codex 的 settings.json 骨架最后说明两者怎么配合。3.1 AGENTS.md 目录页模板关键原则AGENTS.md 控制在 100 行左右只做导航不塞细节。真正的知识放在 docs/ 目录作为系统事实来源。# AGENTS.md 本文件是 Agent 的导航入口不是规范全集。 详细内容请按下方索引跳转到 docs/ 对应文档。 ## 仓库结构速览 - 业务代码按领域垂直拆分每个领域内部固定分层 - 分层顺序types - config - db - logic - runtime - ui - 依赖方向只允许上层依赖下层禁止反向依赖 ## 文档索引 | 主题 | 文档路径 | 说明 | | --- | --- | --- | | 架构总览 | docs/ARCHITECTURE.md | 模块划分与依赖规则 | | 设计文档索引 | docs/design-docs/index.md | 所有设计文档入口 | | 执行计划 | docs/exec-plans/active/ | 进行中的复杂任务计划 | | 技术债追踪 | docs/exec-plans/tech-debt-tracker.md | 待偿还技术债 | | 数据库结构 | docs/generated/db-schema.md | 自动生成勿手改 | | 产品规格 | docs/product-specs/index.md | 需求与验收标准 | | 前端规范 | docs/FRONTEND.md | 组件与样式约定 | | 质量评分 | docs/QUALITY_SCORE.md | 当前质量基线 | | 可靠性 | docs/RELIABILITY.md | 容错与回滚策略 | | 安全 | docs/SECURITY.md | 风险操作与权限边界 | ## 任务执行约定 1. 接到任务先读 docs/exec-plans/active/ 下是否有对应计划 2. 涉及架构变更必须先更新 docs/design-docs/ 再改代码 3. 复杂任务写成计划文件纳入 Git 管理可追溯可回滚 4. 提交前运行 linter架构规则违反将直接阻断提交 ## 禁止事项 - 禁止跨层反向依赖 - 禁止在 generated/ 目录手写内容 - 禁止绕过 linter 提交这份模板的要点是「导航式阅读」。Agent 拿到任务后先看索引表定位到相关文档再深入阅读而不是一次性把整个仓库的规范塞进上下文。上下文预算是稀缺资源100 行的目录页比 800 行的单体手册更有效。3.2 Codex settings.json 骨架Codex 的配置核心是把模型通道指向统一端点并用环境变量注入 Key。下面是一份可复制的骨架{ model_provider: taotoken, model: claude-sonnet-4-5, providers: { taotoken: { base_url: https://taotoken.net/api, api_key_env: TAOTOKEN_API_KEY, wire_api: chat } }, agents: { default: { provider: taotoken, instructions_file: AGENTS.md, max_context_docs: 5 }, reviewer: { provider: taotoken, instructions_file: AGENTS.md, role: code-review } }, harness: { task_dir: docs/exec-plans/active, lint_on_submit: true, auto_fix_pr: true } }几个参数说明参数作用建议值base_url统一 API 端点https://taotoken.net/apiapi_key_env从环境变量读 KeyTAOTOKEN_API_KEYinstructions_fileAgent 导航入口AGENTS.mdmax_context_docs单次注入文档数上限3 到 5lint_on_submit提交前跑架构检查true环境变量这样设置export TAOTOKEN_API_KEY你的Key如果你用的是 Claude Code 这类工具接入方式略有不同可以参考对应文档接入文档https://taotoken.net/doc?utm_sourcetaotoken_aicg_blog_endutm_contentdocutm_campaignrewriteClaudeCodeAnthropic 接入https://taotoken.net/claudecode-anthropic?utm_sourcetaotoken_aicg_blog_endutm_contentclaudecode-anthropicutm_campaignrewrite3.3 多 Agent 任务分发配置Harness 工程里任务分发不是靠人喊而是靠计划文件。在 docs/exec-plans/active/ 下放一个任务文件Agent 读取后按步骤执行# docs/exec-plans/active/refactor-auth.yaml task: 重构认证模块 owner: agent-default steps: - id: 1 action: 读取 docs/design-docs/auth.md - id: 2 action: 按分层规则重写 logic 层 - id: 3 action: 运行 linter 校验依赖方向 - id: 4 action: 生成 PR 并触发 reviewer agent review: agent: reviewer auto_merge: false这样任务的全貌对 Agent 可见而不是只执行单条指令。复杂任务写成计划文件、纳入 Git 管理是 Harness 工程里「可追溯、可回滚」的基础。4. 验证请求本地跑通 Agent 调用链路配置写完必须验证。这一步的目标是确认「AGENTS.md 被正确读取、模型通道可用、任务能分发、结果能回传」。4.1 验证模型通道先用 curl 直接打一次 API确认 Key 和端点没问题curl -X POST https://taotoken.net/api/v1/chat/completions \ -H Authorization: Bearer $TAOTOKEN_API_KEY \ -H Content-Type: application/json \ -d { model: claude-sonnet-4-5, messages: [{role: user, content: 回复 OK}] }如果返回里有正常的 message 内容说明通道通了。如果返回 401检查环境变量是否生效返回 404检查 base_url 是否写成了带路径的完整地址。4.2 验证 AGENTS.md 被读取在仓库根目录启动 Codex发一条探测指令codex 读取 AGENTS.md告诉我文档索引里有哪些主题预期结果是 Agent 能列出索引表里的主题而不是泛泛回答。如果它答不出具体主题说明 instructions_file 路径不对或者 AGENTS.md 不在工作目录根下。4.3 验证任务分发放一个测试计划文件让 Agent 执行codex 执行 docs/exec-plans/active/test-task.yaml观察它是否按 steps 顺序执行并在最后触发 reviewer。这一步能验证 harness.task_dir 配置是否正确。4.4 验证架构约束生效故意写一段违反依赖方向的代码然后提交git add . git commit -m test: 违反分层依赖如果 lint_on_submit 生效提交应该被阻断并提示具体违反了哪条规则。这一步是 Harness 工程和普通 Prompt 工程的分水岭约束不是写在文档里靠自觉而是通过工具强制执行。5. 本篇常见错排查5.1 AGENTS.md 越写越长最常见的退化路径一开始 100 行两周后变成 500 行一个月后没人维护。判断标准很简单如果 AGENTS.md 里出现了具体代码示例、详细参数说明、完整 API 列表就说明它越界了。这些内容应该下沉到 docs/ 对应文档AGENTS.md 只保留索引和禁止事项。5.2 上下文注入过多导致 Agent 漏约束max_context_docs 设成 20看起来信息很全实际上 Agent 会做局部模式匹配反而漏掉真正重要的约束。建议从 3 开始按需增加。上下文预算是稀缺资源注入越多单条约束的权重越低。5.3 Key 明文散落在多个配置如果 settings.json 里直接写了 api_key一旦仓库泄露或配置被复制Key 就暴露了。统一用 api_key_env 引用环境变量CI 环境里用密钥管理注入。多 Agent 场景下不同用途用不同 Key方便按用途观测调用量。5.4 任务计划文件不纳入 Git计划文件如果只放在本地Agent 执行到一半换机器就断了也无法回溯「为什么这么做」。把 docs/exec-plans/ 纳入 Gitactive 和 completed 分开历史决策依据可查。5.5 架构规则只写文档不跑 linter这是最隐蔽的坑。规则写在文档里Agent 会模仿仓库里已有的代码模式包括坏的写法。必须把架构规则变成 linter 可执行的检查违反就阻断提交。否则人工清理的速度永远追不上 Agent 生成代码的速度。5.6 多 Agent 行为不一致同一个任务default agent 和 reviewer agent 给出不同结论通常是两者读取的 instructions_file 不同或者 provider 配置不一致。检查 settings.json 里每个 agent 的 provider 和 instructions_file 是否指向同一套。6. 把 Harness 骨架跑起来之后骨架搭好只是起点。真正决定上限的是这套系统能不能长期自稳、持续复利。几个可以立刻做的动作第一把技术债偿还变成日常。启用后台自动化 Agent定时扫描代码库识别不符合规范的代码直接生成修复 PR。这类修复通常很轻量评审成本低很多可以直接合并。从「攒一个月做一次大扫除」变成「每天日常打扫」技术债的利息才不会滚起来。第二逐步提升 Agent 自主等级。当测试、验证、评审、反馈处理、失败恢复都编码进系统后Agent 可以端到端驱动新特性交付校验代码库状态、复现 bug、实施修复、驱动验证、打开 PR、响应反馈、修复构建失败只在需要判断时升级给人类。但这个能力高度依赖仓库特定结构和持续投入不要在没有同等建设的情况下直接外推。第三把人类判断编码成可复用机制。哪些环节人的杠杆最大通常是架构决策、风险操作拦截、跨模块权衡。把这些判断写成 linter 规则、计划文件模板、评审检查项而不是留在某个人脑子里。如果你还没接入统一通道可以从 API Keys 页面创建一个专用 Key 开始API Keyshttps://taotoken.net/api-keys?utm_sourcetaotoken_aicg_blog_endutm_contentapi-keysutm_campaignrewrite接入细节和参数说明看文档接入文档https://taotoken.net/doc?utm_sourcetaotoken_aicg_blog_endutm_contentdocutm_campaignrewrite长期跑编码任务或 Agent 流水线的团队可以了解 Coding PlanCoding Planhttps://taotoken.net/coding-plan?utm_sourcetaotoken_aicg_blog_endutm_contentcoding-planutm_campaignrewrite软件工程纪律没有消失它只是从「写代码技巧」迁移到了「环境设计、反馈回路与控制系统设计」。AGENTS.md 和 Codex 配置只是这套控制系统的入口真正的功夫在于你愿不愿意把每一条约束都变成可执行、可验证、可回滚的机制。