Harness 核心原理 5｜Instruction 指令层：用 AGENTS.md 与 System Prompt 给 AI 立规矩、定人设

1. 为什么你的 AI 编码助手总在“自由发挥”如果你用过本地 AI 编码工具大概率遇到过这些情况让它改一个函数它顺手把整个文件重写了让它输出 diff它给你一段散文式解释你明明说了“不要动配置文件”它转头就去改settings.json。这些不是模型能力问题而是指令层没搭好。在 Harness 这套拆解框架里指令层Instruction是六大组件的第一块基石。它回答三个问题AI 是谁、要做什么、绝对不能做什么。放到本地编码工具场景里指令层落地成两个具体文件AGENTS.md负责项目级规矩和人设settings.json负责运行时把请求接到统一的 Key/API 通道。前者管“行为”后者管“通路”缺一不可。这篇面向正在用本地 AI 编码工具、准备接入统一 API 通道的开发者。我会给出可直接复制的AGENTS.md骨架、settings.json配置片段以及验证指令层是否真正生效的具体动作。全程围绕一个目标让 AI 从“随机应变”变成“按规矩执行”。2. 前置准备统一 Key/API 通道与项目目录在写指令之前先把通路打通。本地编码工具要调用模型需要一个稳定的 API 入口。我用 TaoToken 作为统一通道好处是 Key 和模型名集中管理换模型不用改一堆配置文件。先拿到 API Key。访问控制台创建https://taotoken.net/console?utm_sourcetaotoken_aicg_blog_endutm_contentconsoleutm_campaignrewrite创建后到 API Keys 页面复制https://taotoken.net/api-keys?utm_sourcetaotoken_aicg_blog_endutm_contentapi-keysutm_campaignrewriteAPI 基础地址统一用https://taotoken.net/api注意这个地址不加 UTM 参数直接作为base_url写入配置。项目目录建议这样组织让指令层文件有明确归属my-project/ ├── AGENTS.md # 项目级指令层 ├── .agent/ │ └── settings.json # 运行时配置 ├── src/ └── README.mdAGENTS.md放在项目根目录工具启动时会自动读取。.agent/settings.json放运行时参数包括 API 通道和模型选择。两者分工清晰一个定义“怎么做事”一个定义“通过哪条路做事”。3. 可复制配置AGENTS.md 骨架与 settings.json3.1 AGENTS.md 骨架下面这份骨架经过实际项目验证分角色、目标、边界、输出格式四段。你可以直接复制后改业务词。# 角色 你是本项目的 AI 编码助手名字叫 DevBot。 你熟悉 TypeScript 与 Node.js代码风格遵循项目 ESLint 配置。 语气简洁只讲重点不寒暄。 # 目标 1. 根据用户描述修改或新增代码改动范围严格限定在用户指定的文件内。 2. 每次改动前先用一句话说明你打算改什么、改哪个文件。 3. 输出代码时使用 diff 格式标明文件路径。 # 边界 - 不要修改 AGENTS.md、settings.json、package.json 之外的配置文件。 - 不要执行 git push、git reset --hard、rm -rf 等破坏性命令。 - 如果用户要求改动超出指定文件范围回复“该改动超出当前文件范围请确认是否继续。” - 不要编造不存在的依赖或 API不确定时明确说“需要确认”。 # 输出格式 - 先输出改动说明不超过 50 字。 - 再输出 diff 代码块标注语言为 diff。 - 最后输出一句验证建议例如“运行 npm test 验证”。这份骨架的关键在于边界用了具体禁止项而不是“注意安全”这种空话。模型对 if-then 式规则执行得更稳。3.2 settings.json 配置片段运行时配置把请求接到统一通道。以下片段适用于多数本地编码工具的配置结构{ provider: openai-compatible, base_url: https://taotoken.net/api, api_key: sk-你的Key, model: claude-sonnet-4-20250514, instruction_file: AGENTS.md, max_tokens: 4096, temperature: 0.2 }几个参数说明base_url指向统一通道instruction_file告诉工具去读根目录的AGENTS.mdtemperature设 0.2 是为了让编码任务更稳定减少自由发挥。如果你做的是长期编码或 Agent 类任务可以考虑 Coding Plan 方案额度更适配高频调用https://taotoken.net/coding-plan?utm_sourcetaotoken_aicg_blog_endutm_contentcoding-planutm_campaignrewrite配置写完后工具启动时会先加载AGENTS.md作为 System Prompt 的一部分再拼接用户输入。这就是指令层的组装过程。4. 验证指令层是否生效三个具体动作配置写完不代表生效。下面三个动作可以快速验证指令层是否真正起作用。4.1 动作一越界请求测试在对话里输入“帮我把 package.json 里的版本号改成 2.0.0。”如果指令层生效AI 应该回复类似“该改动涉及 package.json属于配置文件根据边界规则需要你确认是否继续。”如果它直接改了说明AGENTS.md没被读取或者边界写得不够具体。4.2 动作二输出格式测试输入“给 utils.ts 加一个 formatDate 函数。”生效时AI 会先给一句改动说明再输出 diff 代码块最后给验证建议。如果它输出一大段散文解释、没有 diff说明输出格式约束没生效。检查AGENTS.md里“输出格式”段是否被正确解析。4.3 动作三角色一致性测试输入“你好今天天气怎么样”生效时AI 应该简短回应并拉回编码任务比如“我是 DevBot专注本项目编码。有代码需要改吗”如果它开始聊天气说明角色定义太弱需要加强“只讲重点不寒暄”这类约束。三个动作都通过说明指令层基本生效。任何一个失败回到对应段落加具体规则。5. 本篇常见错排查5.1 AGENTS.md 没被读取最常见的原因是文件名或路径不对。确认文件在项目根目录且settings.json里的instruction_file值与实际文件名一致。有些工具要求文件名全大写有些要求放在.agent/目录下以你所用工具的文档为准。5.2 边界规则被忽略如果 AI 仍然越界通常是边界写得太抽象。把“不要做危险操作”改成具体列表“不要执行 git push、git reset --hard、rm -rf”。模型对具体命令名的识别率远高于抽象描述。5.3 API 请求 401 或 404401 一般是 Key 错误或没带对。检查api_key是否完整复制base_url是否为https://taotoken.net/api。404 通常是路径拼错确认没有多余斜杠或缺少/api。可以在模型对话页面先测一下 Key 是否可用https://taotoken.net/chat?utm_sourcetaotoken_aicg_blog_endutm_contentmodel-chatutm_campaignrewrite5.4 指令太长导致截断AGENTS.md如果超过几千字可能被截断后面的边界规则就丢了。把最重要的边界放在文件前部或者拆分成多个文件按需加载。接入文档里有关于指令长度和组装顺序的说明https://taotoken.net/doc?utm_sourcetaotoken_aicg_blog_endutm_contentdocutm_campaignrewrite5.5 模型不遵守 diff 格式有些模型对 diff 格式支持不稳定。可以在AGENTS.md里加一个正例展示期望的 diff 样式。示例比描述更有效。如果仍然不行换一个对代码格式支持更好的模型在模型对话页面切换测试。6. 把指令层当成项目资产来维护指令层不是写一次就完事。项目在变规矩也要跟着变。我的做法是把AGENTS.md纳入版本控制每次调整都提交方便回滚和对比。团队协作时谁改了哪条边界一目了然。另外一个小技巧把AGENTS.md里的边界规则和 CI 检查对齐。比如边界说“不要改配置文件”CI 里就加一条检查确保 AI 提交的 diff 没碰配置文件。指令层管事前CI 管事中两层配合才稳。如果你还在用裸 Key 直连、每个工具配一遍建议统一到一条通道上。Key 集中管理模型随时切换指令层文件跟着项目走。这样换工具、换模型规矩不用重写。接入方式和配置示例都在文档里照着改一遍就能跑通。