1. AGENTS.md 每轮都进请求：上下文预算被吃掉的位置在哪里
仓库根目录的 AGENTS.md 从三十多行长到三百行，是许多用编码助手维护仓库的后端开发者都经历过的事情。最初只写了三五条，随着每次被模型气到，就往里补一条：不许在回答结尾重复一遍结论、不许给三套方案让我挑、不许把已经排除的选项再列出来当参考。补到最后，这份文件本身成了一份情绪清单，读起来像一位被反复冒犯的人在写交接文档。
问题出在它的读取方式。支持该约定的编码助手会在会话开始时读取这份文件，之后每一轮请求都把它随上下文一起发出。也就是说，文件里每增加一段规则文本，都会在后端开发者的每一次追问里重复计费。一个会话来回二十轮，ATE 规则本身就被发送了二十次。当一份约定文件膨胀到十几 KB，真正用来描述任务的那几十个字，反而成了附带内容。
TaoToken 提供统一入口，把 Claude Code、Codex 这类编码助手的请求收敛到同一个 Base URL，具体入口见 https://taotoken.net/?utm_source=taotoken_aicg_blog_end&utm_content=agents-md-intro 。接入动作本身很简单，剩下的工作是把这份约定文件的体积压下来。
上下文预算由三块内容共同占用：约定文件的固定开销、会话历史的累计开销、工具调用返回内容的瞬时开销。第三块最难预测，一次全仓搜索可能返回几千行日志；第二块与会话长度成正比，靠及时清空会话解决。第一块是唯一可以被精确控制和长期复用的部分，它占的空间不大，但每一轮都在场。
三十多行的约定文件大约两千个字符，换算成 Token 不过一千出头。这个数量看起来微不足道，然而它的作用不是占用总量，而是挤占了模型处理任务描述时可用的人际距离。当规则文本比任务文本长十倍，注意力分配会明显偏向规则，模型开始把精力花在"我这句话是否违反某条格式要求"上，而不是理解代码结构。表现就是回答变得啰嗦、犹豫，时不时补一句"如果你希望我采用另一种方式，请告诉我"。
把这部分预算压下来的做法并不复杂：留下可以在几秒内判定真假的规则，删掉需要反复解释才能理解的规则，把与特定任务相关的细则挪到单独的文档里按需读取。下文给出的顺序是先建立终端对照来观察差异，再给出精简后的约定片段，然后完成 Base URL 的一次性配置。
2. 终端问答对照：同一句指令在约束前后的两种输出
先看一个真实场景。仓库里有一个已经废弃的连接池配置字段，需要在代码和测试里同步删除。指令只有一句：
codex "删除 src/pool/connector.py 里已经废弃的 max_idle 字段，同步更新引用它的测试文件"在约定文件只有零散几条格式要求的阶段，返回结果的结构大致是这样：
我先看了一下代码结构。删除这个字段有几种做法可以讨论。 方案一：直接删除字段，同时修改所有引用点。风险是如果有外部模块通过字典读取配置，会在运行时报 KeyError。 方案二：保留字段并在读取处标记为废弃，下一版本再移除。风险是配置文档和实际代码不一致。 方案三：保留字段，同时在配置校验层增加一次告警输出。 综合来看，方案一最为直接，方案二更为稳妥，方案三兼顾了两者。你可以根据团队实际情况选择。需要注意的是，无论选择哪种方案，都要确保测试覆盖。 如果你希望我继续，我可以先按方案一实施。这段回答包含了三层信息冗余。它先声明"我先看了一下代码结构"，没有任何信息量；然后给出三个平行方案，其中后两个在那个仓库里根本没有存在理由，因为连接池配置只被一个模块读取；最后用一句"如果你希望我继续"把决定权推回来，等于要求提问者再发一次指令。整个过程消耗的 Token 数量远大于任务本身。
在约定文件写清楚规则之后，同一个仓库、同一句指令，返回结果变成：
删除 src/pool/connector.py 中的 max_idle 字段。 改动位置： 1. src/pool/connector.py：移除 dataclass 字段定义与默认值。 2. src/pool/pool_factory.py：移除构造参数中的 max_idle。 3. tests/test_pool_factory.py：移除两处传入 max_idle 的关键字参数。 已执行：python -m pytest tests/test_pool_factory.py，全部通过。差异集中在三点。第一，回答没有开头声明动作，因为规则已经把"叙述自己正在做什么"列为多余输出。第二，只有一个方案，因为规则要求每个问题给出一个覆盖全部已知约束的完整方案，不允许把无法同时成立的做法并列。第三，改动结束后直接给出验证命令和结果，因为规则把"实施、运行、测试"写成任务完成的前置条件，模型不会停在"你可以测试一下"。
这种差异并非某一家模型的特性，任何支持自定义系统提示或约定文件的编码助手都能被同样的规则约束。关键在于规则必须是可判定的：写"说人话"没有用，模型无法判断边界；写"回答结尾不出现总结段落"就可以被逐字检查。这一条区分标准，是下面精简片段的核心依据。
3. 精简后的 AGENTS.md 片段与拆分目录
原始版本里的规则大致可以分成三类：输出格式、方案设计、代码改动行为。三类都存在同一个毛病，用声明式的语气描述抽象期望，没有给出可以被检查的具体形态。把每条规则改写成可判定的条目之后，文件体积能从十几 KB 降到两 KB 以内。
下面是可以直接放进仓库根目录的片段：
# 仓库约定（完整规则见 docs/agents/） ## 输出格式 - 全部回答使用中文完整词汇，不使用单个字的缩写形式。 - 回答中不出现对比句式，包括「不是……而是……」「要……而不是……」。 - 回答结尾不添加总结段落、过渡句、行动邀请。 - 回答中只列出与当前任务直接相关的文件、方案、选项。 - 需要展示结构时使用 mermaid 或代码块，不使用字符拼图。 ## 方案设计 - 每个问题只给出一个方案，该方案一次覆盖全部已知约束。 - 不提出分阶段推进的措辞，不区分保守方案与激进方案。 - 搜索过程与排除结果不写入回答。 ## 代码改动 - 依赖直接 import，不使用异常捕获包裹 import 语句。 - 错误在出现位置立即终止程序，不做降级处理。 - 撤销改动通过手动编辑文件完成，不执行 Git 恢复命令。 - 中间产物写入仓库内 scratch/ 目录，该目录已列入 .gitignore。 - 任务完成后必须执行对应测试命令，并把命令与结果写入回答。 ## 文件操作 - 不读写 /tmp 目录下的内容。 - 修改文件前重新读取当前内容，以工作区现状为基准。 - 涉及数据库的命令由开发者本人执行，助手只输出语句文本。这份片段大约九百个字符，全部条目都能在几秒内判定。剩下的细则，比如某个模块的接口约定、某个服务的部署流程，放进 docs/agents/ 目录下的独立文件，由开发者在需要时手动引用。这样处理之后，约定文件从"每次都在场"变成"按需出现"。
拆分时需要处理一个问题：Claude Code 默认读取仓库根目录的 CLAUDE.md，Codex 读取 AGENTS.md。两个文件分别维护会产生漂移。比较省事的做法是让 CLAUDE.md 只保留一行导入语句：
@AGENTS.mdClaude Code 支持在约定文件中导入其他文件，这行语句会把 AGENTS.md 的内容带入会话。两个助手从此读取同一份内容，仓库里只需要维护一个规则来源。
文件瘦身之后，规则的效果不会自动变好，还需要保证每条规则对应的行为确实被触发。判断方法很简单：故意在对话中让它列举一个已经排除的选项，如果模型照做，说明那条"只列出与当前任务直接相关的选项"的表述仍然不够明确，需要补一个反例进去。规则文本的迭代过程，本质上就是不断把模糊表述替换成可判定表述的过程。
4. Base URL 一处填写：Claude Code、Codex、CC Switch 三套配置
约定文件解决的是输出质量问题，接入配置解决的是请求去向问题。TaoToken 把所有兼容接口收敛到同一个地址，Base URL 只在一处填写：https://taotoken.net/api。这个地址不带任何查询参数，直接作为各家工具的基础地址使用。完整说明见 https://taotoken.net/?utm_source=taotoken_aicg_blog_end&utm_content=agents-md-config 。
Claude Code 通过环境变量读取接入信息，配置写在~/.claude/settings.json，项目级配置可以放在仓库的.claude/settings.json：
{ "env": { "ANTHROPIC_BASE_URL": "https://taotoken.net/api", "ANTHROPIC_AUTH_TOKEN": "YOUR_API_KEY" } }需要指定模型时，再加一行ANTHROPIC_MODEL，取值填写控制台模型列表里显示的完整名称。修改完成后重启终端会话，让新的环境变量生效。验证方式是执行一次简单提问，如果返回正常文本，说明地址与密钥都被正确读取。
Codex 使用~/.codex/config.toml，字段结构与 Claude Code 完全不同，不能把ANTHROPIC_*系列变量套用过来：
model = "控制台模型列表中的完整名称" model_provider = "taotoken" [model_providers.taotoken] name = "TaoToken" base_url = "https://taotoken.net/api" env_key = "TAOTOKEN_API_KEY"这里env_key指向一个环境变量名称，Codex 会从这个变量里读取密钥，而不是把密钥明文写进配置文件。对应需要在 shell 配置文件中导出的内容：
export TAOTOKEN_API_KEY="YOUR_API_KEY"两套配置都完成之后，切换供应商的次数会明显上升，于是出现第三个工具。CC Switch 用来在多个供应商配置之间切换，它需要填写的项目是三件套：
- 供应商名称，填写
taotoken，用于在列表中区分。 - Base URL，填写
https://taotoken.net/api。 - API Key，填写
YOUR_API_KEY。
模型名称作为第四项可选内容填写，取值与控制台一致。三件套的填写顺序不影响结果，但地址项必须与前面的配置保持完全相同的字符串，多一个斜杠或少一个字符都会导致请求失败。
配置完成后建议做一次交叉验证：在 Codex 里提一个需要读取仓库文件的问题，确认它读到了 AGENTS.md 的内容；在 Claude Code 里做同样的提问，确认 CLAUDE.md 的导入语句生效。两边返回都正常，说明约定文件与接入配置已经互相配合。
5. YOUR_API_KEY 的放置位置与环境变量写法
密钥的处理方式决定了仓库能不能安全地公开。密钥不能写进 AGENTS.md，不能写进.claude/settings.json，也不能出现在任何会被提交的文件里。这两个位置都会随仓库进入版本历史，一次误提交就会留下长期记录。
推荐的做法是把密钥放进 shell 的启动文件，例如~/.zshrc或~/.bashrc：
export TAOTOKEN_API_KEY="YOUR_API_KEY" export ANTHROPIC_AUTH_TOKEN="YOUR_API_KEY"导出之后执行一次source ~/.zshrc，或者直接打开一个新终端。验证变量是否生效：
printenv TAOTOKEN_API_KEY printenv ANTHROPIC_AUTH_TOKEN前一条对应 Codex 的读取方式，后一条对应 Claude Code 的读取方式。两条输出都应当是相同的密钥字符串。如果某一条为空，说明当前 shell 没有加载对应的启动文件，检查文件名与当前使用的 shell 是否一致即可。
项目级配置里引用环境变量而不是明文，Claude Code 的 settings.json 可以写成：
{ "env": { "ANTHROPIC_BASE_URL": "https://taotoken.net/api", "ANTHROPIC_AUTH_TOKEN": "${TAOTOKEN_API_KEY}" } }这样仓库里的配置文件可以直接提交，密钥仍然留在本机。Codex 的 config.toml 本身就是通过env_key间接读取，不需要额外处理。
密钥管理还有一个容易被忽略的场景：约定文件里会写明"修订时手动编辑文件，不执行 Git 恢复命令"，这类规则的目的之一是避免密钥或中间产物被误操作带入历史。配套的做法是在仓库根目录的.gitignore里加入：
scratch/ .env .claude/settings.local.jsonscratch/目录用于存放编码助手产生的中间结果，例如它导出的接口清单、临时的分析文本。这个目录必须提前创建并加入忽略清单，否则助手可能把中间结果写到/tmp，而约定文件已经禁止读写该目录。
密钥的轮换同样简单。到控制台生成新的 Key，替换 shell 启动文件里的字符串，重新加载配置即可。旧密钥在新密钥生效后可以直接删除，不需要保留过渡期。控制台入口是 https://taotoken.net/?utm_source=taotoken_aicg_blog_end&utm_content=agents-md-key 。
6. 体积体检与日常维护：把上下文预算压回可控范围
规则文本与配置文件都稳定之后，剩下的事情是定期检查体积。做法比想象中简单，一条命令就能给出当前状态：
wc -l AGENTS.md wc -c AGENTS.md字符数是更关键的指标，因为它与请求里实际携带的内容量直接相关。两千个字符以内属于健康范围，超过五千字符需要重新审视每条规则的必要性。常见膨胀来源有三类：为某次偶发问题临时添加的规则、与其他规则表达同一约束的重复条目、把具体任务的实现细节写进通用约定。
处理这三类内容的方式各有不同。偶发问题的规则在解决之后可以直接删除，如果担心复发，把它移到 docs/agents/ 下的独立文件。重复条目合并成一条更精确的表述，合并过程往往能顺带发现两条规则之间的冲突。实现细节从约定文件里移出，放进代码注释或者模块文档。
会话历史的清理同样属于预算维护。长时间运行的会话会累积大量工具返回内容，比如目录树、测试输出、diff 文本。这些内容在后续请求里会随历史一起发送。完成一个任务之后开启新会话，比在同一个会话里连续处理五个任务更省资源。判断时机的方法很直接：当助手开始重复询问已经确认过的信息，说明历史已经超出了它能够稳定处理的长度。
维护节奏可以固定下来。每次提交涉及约定文件的改动时，顺带看一眼字符数；每月检查一次 docs/agents/ 目录，把已经不适用的细则删除；每季度重新读一遍 AGENTS.md，删掉那些在最近三个月里从未被触发的条目。最后这条最容易被跳过，也最关键，一份只增不减的规则文件在半年之后必然回到起点。
实测下来，把约定文件从三百行压到四十行左右，再配合 Base URL 统一配置，终端体验的变化主要集中在两点。模型的回答长度明显缩短，改动说明从十几行降到四五行的同时信息量没有下降；需要确认的来回次数减少，任务从提问到落地通常只需要一次往返。这两点带来的 Token 节省会随会话长度累积，越是长时间维护的仓库，收益越明显。
需要的工具入口按使用顺序排列如下。想先看看模型对话的表现，可以从 https://taotoken.net/models/detail/chat?utm_source=taotoken_aicg_blog_end&utm_content=agents-md-chat 进入。打算长期使用编码助手，可以查看 https://taotoken.net/coding-plan?utm_source=taotoken_aicg_blog_end&utm_content=agents-md-plan 里的方案说明。准备好密钥之后，到 https://taotoken.net/console/api-keys?utm_source=taotoken_aicg_blog_end&utm_content=agents-md-apikey 创建，然后按照 https://taotoken.net/doc/ClaudeCodeAnthropic?utm_source=taotoken_aicg_blog_end&utm_content=agents-md-claudecode 里的步骤完成 Claude Code 的接入。把 Base URL 写成https://taotoken.net/api，把密钥放进环境变量，剩下的就是把自己那份约定文件读一遍，删掉那些从未生效过的条目。
