1. 为什么编码 Agent 需要一份 AGENTS.md 行为规范Harness Engineering 这个词最近在编码 Agent 圈子里被反复提起说白了就是给 Agent 套上一副“缰绳”——不是限制它的能力而是让它每次动手之前都知道边界在哪、目标是什么、什么算做完。我试过让 Agent 在一个中型 RAG 项目里自由发挥结果它把apps/api和apps/web的依赖方向搞反了前端直接 import 了后端 service 层的模块跑起来才发现循环依赖。那次之后我才认真对待 AGENTS.md 这件事。AGENTS.md 本质上是一份放在仓库根目录的“Agent 行为契约”。它和 README 不一样README 是给人看的AGENTS.md 是给编码 Agent 看的。它要回答三个问题这个项目要构建什么、Agent 该怎么工作、任务真正完成的标准是什么。配合 ARCHITECTURE.md 定义系统骨架、CLAUDE.md 定义 Claude Code 的启动指令三者构成一套可执行的规范体系。适合谁读这篇如果你正在用 Cline、Claude Code、Codex 这类编码 Agent 做真实项目并且发现 Agent 经常跑偏、改错文件、忽略测试、或者每次都要手动提醒它读文档那这套方法就是为你准备的。本文会给出可直接复制的 AGENTS.md 模板、目录结构、约束条目示例并演示在 Cline MCP 中把 Base URL 改到 TaoToken 后跑通一次规范校验验证 Agent 是否真的按规范执行。核心检索词先明确Harness Engineering 是一套让编码 Agent 在可控边界内工作的工程实践AGENTS.md 是这套实践的落地载体ARCHITECTURE.md 和 CLAUDE.md 是配套的骨架与启动指令。三者缺一不可只有 AGENTS.md 而没有 ARCHITECTURE.mdAgent 知道规则但不知道系统怎么拼只有 ARCHITECTURE.md 而没有 AGENTS.mdAgent 知道骨架但不知道工作流程。我踩过的坑是一开始只写了一份很长的 AGENTS.md把所有规则堆在一起结果 Agent 每次只读前几行就开始动手。后来拆成 AGENTS.md 管规则、ARCHITECTURE.md 管结构、docs/ 下各专项文档管细节Agent 的命中率明显提升。关键原则是AGENTS.md 要短而硬ARCHITECTURE.md 要全而准专项文档要深而专。2. TaoToken 前置准备Base URL、API Key 与 Model ID 三件套在演示 Cline MCP 跑通规范校验之前需要先把接入层准备好。TaoToken 提供的是兼容 OpenAI 接口规范的 API 网关编码 Agent 通过它来调用模型。你需要准备三样东西Base URL、API Key、Model ID。这三件套在任何编码 Agent 的配置里都是必须的缺一个都跑不起来。Base URL 统一使用https://taotoken.net/api注意这里不加任何 UTM 参数保持干净。API Key 需要到控制台创建路径是 console 页面下的 api-keys 管理。Model ID 根据你用的模型来填比如claude-sonnet-4-20250514或者gpt-4o这类具体以模型对话页面列出的可用模型为准。如果你用的是 Claude Code接入方式略有不同需要参考 ClaudeCodeAnthropic 的文档配置。Cline MCP 的配置则是在 Cline 的设置里找到 API Provider选择 OpenAI Compatible然后填入 Base URL 和 API Key。这里有个细节Cline 的 Base URL 字段有时候会自动补/v1而 TaoToken 的路径是/api所以填的时候要确认最终请求地址是https://taotoken.net/api/v1/chat/completions这种形式不要多也不要少。我实测下来Cline 里配置 TaoToken 最稳的方式是API Provider 选 OpenAI CompatibleBase URL 填https://taotoken.net/apiAPI Key 填控制台生成的 keyModel ID 填你需要的模型。保存后 Cline 会发一个测试请求如果返回正常就说明接入成功。如果报 401先检查 key 有没有复制完整如果报 model not found检查 Model ID 拼写。对于长期做编码和 Agent 任务的场景可以考虑 Coding Plan它在额度上更适合高频调用。如果只是验证模型效果用模型对话页面就够了。接入文档在 doc 页面有详细说明遇到配置问题可以先翻文档。需要强调的是TaoToken 在这里的角色是模型调用网关不是替代你的编辑器或 IDE。Cline 仍然是你的编码 Agent 宿主TaoToken 只是它背后调用的模型服务。这个边界要清楚不然配置的时候容易搞混。3. 可复制配置AGENTS.md 模板与 Cline MCP settings 片段这一节给出可直接复制的配置。先看 AGENTS.md 模板这是整个 Harness Engineering 的核心文件。模板设计原则是短、硬、可执行。每一条规则都必须是 Agent 能判断“做了还是没做”的不能是“尽量”“建议”这种模糊表述。# AGENTS.md This repository is designed for agent-assisted development: humans define intent, constraints, and review standards; agents implement, test, document, and improve the system. ## Product Build an internal AI system for company use: - Organization-network access only for end users. - LLM runtime with Ollama. - Model routing across DeepSeek R1 distilled models, Mistral, and Llama 3.1 class models. - RAG over approved OEM whitepapers, datasheets, and internal documents. - JWT, RBAC, document-level permissions, audit logs, and prompt-injection controls. - React web app backed by a Python API backend that also owns LLM orchestration. - Observability across latency, token usage, cache hit rate, retrieval quality, and hallucination feedback. ## Start Here - Architecture map: ARCHITECTURE.md - Copilot/Codex instructions: .github/copilot-instructions.md - Product behavior: docs/product-specs/index.md - Engineering plans: docs/exec-plans/active/ - Security rules: docs/SECURITY.md - Reliability rules: docs/RELIABILITY.md - Quality scorecard: docs/QUALITY_SCORE.md - Frontend rules: docs/FRONTEND.md - Design principles: docs/DESIGN.md - External/library references for LLMs: docs/references/ ## Agent Operating Rules 1. Before changing code, read the relevant product spec, design doc, architecture section, and active execution plan. 2. Prefer small, reviewable PR-sized changes. 3. If a requirement is ambiguous, write the assumption into the active execution plan before implementing. 4. Update docs when behavior, interfaces, data shapes, security rules, or operational assumptions change. 5. For frontend work, use Tailwind CSS and shadcn/ui components unless an existing design system overrides this. 6. Internet access is allowed for approved runtime integrations, but company data, prompts, traces, and documents must only flow to approved services. 7. Validate data at every trust boundary: upload, auth, retrieval, tool call, model response, and API response. 8. Treat security, observability, and evaluation tooling as product code. 9. When you discover repeated review feedback, convert it into docs, tests, lints, or checklists. ## Expected Agent Loop 1. Read task and relevant docs. 2. Create or update an execution plan in docs/exec-plans/active/. 3. Implement the smallest coherent slice. 4. Run tests, linters, type checks, and relevant evaluation scripts. 5. Validate manually through API/UI where applicable. 6. Update generated docs such as schema maps. 7. Record decisions and remaining risks in the execution plan. 8. Move completed plans to docs/exec-plans/completed/. ## Definition of Done - Product behavior matches the relevant spec. - Access control and document permissions are enforced. - Retrieval results are source-attributed. - Model outputs include uncertainty or refusal behavior where required. - Tests cover the main path and at least one failure path. - Observability emits useful traces, metrics, and audit events. - Documentation reflects the implemented behavior.这份模板的关键在于 Definition of Done 部分。很多 Agent 跑偏是因为“完成”的定义不清晰它以为代码写完就算完但实际需要测试覆盖、文档更新、可观测性埋点。把 DoD 写死Agent 就没有模糊空间。接下来是 Cline MCP 的 settings 片段。Cline 的配置存在 VS Code 的 settings.json 里MCP 服务器的配置格式如下{ cline.mcpServers: { taotoken-gateway: { command: npx, args: [-y, modelcontextprotocol/server-filesystem, /path/to/your/project], env: { OPENAI_BASE_URL: https://taotoken.net/api, OPENAI_API_KEY: sk-your-key-here, OPENAI_MODEL: claude-sonnet-4-20250514 } } } }注意这里的OPENAI_BASE_URL填的是https://taotoken.net/api不要加/v1因为 MCP server 内部会自己拼接路径。OPENAI_API_KEY换成你在 console 创建的 key。OPENAI_MODEL换成你实际要用的 Model ID。如果你用的是 Claude Code配置在~/.claude/settings.json或者项目级的.claude/settings.json{ env: { ANTHROPIC_BASE_URL: https://taotoken.net/api, ANTHROPIC_API_KEY: sk-your-key-here, ANTHROPIC_MODEL: claude-sonnet-4-20250514 } }Codex 的配置在~/.codex/auth.json{ openai_api_key: sk-your-key-here, base_url: https://taotoken.net/api, model: gpt-4o }三件套的对应关系要记牢Base URL 统一是https://taotoken.net/apiAPI Key 从 console 的 api-keys 页面创建Model ID 从模型对话页面查。任何一处填错都会导致请求失败。4. 验证请求在 Cline MCP 中跑通一次规范校验配置写好后需要验证 Agent 是否真的按 AGENTS.md 执行。验证方法是设计一个“规范校验任务”让 Agent 去检查代码是否符合 AGENTS.md 里的约束条目然后看它的输出是否引用了正确的文档、是否按 Expected Agent Loop 的步骤走。具体操作在 Cline 里打开你的项目确保根目录有 AGENTS.md 和 ARCHITECTURE.md。然后在 Cline 对话框里输入这样的任务请检查 apps/api/app/services/orchestrator.py 是否符合 AGENTS.md 中的 Agent Operating Rules。 具体要求 1. 先读 AGENTS.md 和 ARCHITECTURE.md 2. 说明你读了哪些文件 3. 逐条对照 Operating Rules 检查 4. 如果发现违规指出具体条目和代码位置 5. 不要直接修改代码只输出检查报告发送后观察 Cline 的行为。如果配置正确且 AGENTS.md 生效Agent 应该先输出它读取了哪些文件然后逐条对照规则给出检查结果。如果 Agent 直接开始改代码说明它没有遵守“不要直接修改代码”的指令这时候需要检查 AGENTS.md 是否被正确加载。我实测下来Cline 在读取 AGENTS.md 后会在回复开头列出“Read AGENTS.md, ARCHITECTURE.md, docs/SECURITY.md”这样的文件清单然后才开始分析。这个行为本身就是规范生效的信号。如果它没有列文件清单就直接分析说明 AGENTS.md 没有被优先读取需要检查 Cline 的 instruction files 配置。验证成功的标志有三个第一Agent 在动手前先读了 AGENTS.md 和 ARCHITECTURE.md第二Agent 的输出引用了具体的规则条目编号第三Agent 遵守了“只输出报告不修改代码”的约束。三个都满足说明 Harness Engineering 的规范层已经生效。如果要做更严格的验证可以故意在代码里埋一个违规点比如在apps/web里 import 了apps/api的模块然后让 Agent 去检查。看它是否能发现这个跨层依赖违规并引用 ARCHITECTURE.md 里的依赖方向规则。这个测试能验证 Agent 是否真的理解了规范而不是只做了表面检查。验证通过后你可以把这次检查报告作为模板后续每次 Agent 完成任务后都跑一遍类似的规范校验。这样就把 Harness Engineering 从“一次性配置”变成了“持续执行的流程”。5. 本篇常见错排查401、local proxy failed、reading choices、OAuth配置和验证过程中最容易遇到四类报错逐个说清楚原因和排查方法。第一类401 Unauthorized。这个最常见原因是 API Key 无效或没传对。排查步骤先确认 key 是从 console 的 api-keys 页面创建的没有多余空格再确认配置里 key 的字段名正确Cline 里是OPENAI_API_KEYClaude Code 里是ANTHROPIC_API_KEYCodex 里是openai_api_key最后确认 Base URL 没有拼错https://taotoken.net/api不要写成https://taotoken.net/api/v1或https://taotoken.net/v1。如果 key 确认没问题还是 401到模型对话页面发一条测试消息看是否能正常返回以此判断是 key 问题还是配置问题。第二类local proxy failed。这个报错通常出现在 Cline 或 Claude Code 启动时原因是本地代理配置冲突。排查步骤检查环境变量里有没有HTTP_PROXY、HTTPS_PROXY、ALL_PROXY这些如果有且指向了一个不可用的地址就会报 local proxy failed。解决方法是清掉这些环境变量或者确保它们指向可用的地址。另外检查 VS Code 的http.proxy设置如果设了一个失效的代理也会导致这个问题。第三类reading choices 相关报错。这个通常出现在请求返回后解析响应时报错信息类似Cannot read properties of undefined (reading choices)。原因是返回的 JSON 结构不符合预期可能是 Base URL 路径不对导致返回了 HTML 错误页也可能是 Model ID 不存在导致返回了错误对象。排查步骤先用 curl 直接请求一次看返回的 JSON 结构curl -X POST https://taotoken.net/api/v1/chat/completions \ -H Authorization: Bearer sk-your-key-here \ -H Content-Type: application/json \ -d {model:claude-sonnet-4-20250514,messages:[{role:user,content:hi}]}如果返回里有choices字段说明接口正常问题在 Agent 配置如果没有看返回的错误信息是什么。常见的是 model not found这时候去模型对话页面确认 Model ID 拼写。第四类OAuth 相关报错。这个出现在 Claude Code 或 Codex 的认证流程里报错信息类似OAuth token expired或invalid_grant。原因是这些工具默认走 OAuth 认证但配置了 Base URL 后应该走 API Key 认证。排查步骤确认配置里用的是 API Key 而不是 OAuth token如果之前登录过 OAuth先退出登录再重新配置检查~/.claude/settings.json或~/.codex/auth.json里是否有残留的 OAuth 字段有的话删掉。这四类报错覆盖了 90% 的接入问题。排查顺序建议是先 curl 验证接口通不通再检查 Agent 配置的字段名和路径最后检查环境变量和残留配置。按这个顺序走基本都能定位到问题。6. 把规范校验接入日常编码流程规范校验跑通一次之后下一步是把它变成日常流程的一部分。我的做法是在 AGENTS.md 的 Expected Agent Loop 里加一条每次任务完成后Agent 必须自己跑一次规范校验把结果写进 execution plan。这样就不需要人工每次提醒。具体实现是在 AGENTS.md 里追加一条规则10. Before marking a task complete, run a self-check against the Agent Operating Rules and record the result in the active execution plan.然后在docs/exec-plans/active/下的每个 plan 文件里加一个## Self-Check段落Agent 完成任务后要在这里填写检查结果。格式可以是## Self-Check - [x] Read AGENTS.md and ARCHITECTURE.md before editing - [x] Changes are PR-sized and reviewable - [x] Docs updated for behavior changes - [x] Tests cover main path and one failure path - [ ] Observability traces added (pending)这个自检清单让 Agent 的每一步都可追溯。如果某一项没打勾review 的时候一眼就能看到哪里没做完。对于长期做编码 Agent 任务的场景可以考虑用 Coding Plan 来支撑高频的模型调用。规范校验本身会消耗不少 token因为 Agent 要读多个文档、逐条对照、输出报告。如果只是偶尔验证用模型对话页面手动测就行。接入文档在 doc 页面有完整的配置说明包括 Cline、Claude Code、Codex 各自的配置示例。API Key 在 console 的 api-keys 页面管理可以创建多个 key 分别给不同工具用方便排查问题时隔离。最后说一个实用技巧把 AGENTS.md 里的规则条目编号固定下来不要随意增删。因为 Agent 在输出检查报告时会引用编号如果编号变了之前的报告就对不上了。新增规则就往后追加编号废弃规则就标记为 deprecated 而不是删除。这样整个规范体系就是可追溯的和 Harness Engineering 的核心理念一致——每一步决策都留记录Agent 不容易跑偏。