1. 实习回家后项目卡在“能跑但不敢改”实习结束回到家我把公司电脑上的项目 clone 到自己的笔记本准备趁假期把之前没做完的运维处置知识库收个尾。结果第一天就卡住了项目能跑但我不敢动。原因很具体——这个项目里塞了太多“口头约定”提交信息要带类型前缀、测试必须用 Testcontainers 起真实 PostgreSQL、报告归档不能阻塞 SSE 主链路、标签提取失败要存空数组而不是回退规则。这些规则在我脑子里不在仓库里。换台机器、换个会话Codex 就完全不知道。我试过每次开新对话都手动贴一遍规则贴到第三次就烦了。更麻烦的是Codex 在没有约束时会“自作主张”我让它实现一个状态筛选它顺手给我加了租户隔离和权限校验我让它写个标签提取它给我设计了一套规则回退加模型重试的复杂链路。代码本身没错但对一个还在验证核心闭环的 MVP 来说这些全是负担。后来我把问题拆成三层哪些是每次都要遵守的仓库规则哪些是可复用的工作流程哪些是仓库之外的外部能力。对应到 Codex 的定制体系就是 AGENTS.md、Skills 和 MCP。再配一条统一的模型调用通道把 Key 和 API 地址收敛到一处换机器、换会话都不用重新配。这篇就按我实际落地的顺序把 AGENTS.md 片段、Skills 目录结构、config.toml 骨架和验证动作完整写出来你可以直接照着复现。2. 先把 TaoToken 的 Key 和通道准备好在写任何配置文件之前先把模型调用通道固定下来。我踩过的坑是项目里散落着好几处 API 地址和 Key有的写在环境变量有的硬编码在测试配置里换一台机器就要重新找一遍。统一到一个入口之后后面 config.toml 里只引用一个变量就行。TaoToken 在这里的角色是统一 Key 和 API 通道你拿到一个 Key配一个 base_urlCodex 和项目里的模型调用都走这条通道。官网入口在 https://taotoken.net/?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_content API 地址是 https://taotoken.net/api 这个不加 UTM直接填进配置。操作顺序是这样先打开模型对话页面确认通道可用再去控制台创建 Key最后把 Key 写进本地环境变量。模型对话入口https://taotoken.net/models?utm_sourcetaotoken_aicg_blog_endutm_contentmodel_chatutm_campaignrewrite 。控制台入口https://taotoken.net/console?utm_sourcetaotoken_aicg_blog_endutm_contentconsoleutm_campaignrewrite 。Key 管理页面https://taotoken.net/api-keys?utm_sourcetaotoken_aicg_blog_endutm_contentapi_keysutm_campaignrewrite 。创建完 Key 之后不要直接写进任何会提交到 Git 的文件。我用的是本地 shell 配置文件# ~/.zshrc 或 ~/.bashrc export TAOTOKEN_API_KEYsk-你的Key export TAOTOKEN_BASE_URLhttps://taotoken.net/api改完执行source ~/.zshrc然后用一条 curl 确认通道通curl -s $TAOTOKEN_BASE_URL/v1/models \ -H Authorization: Bearer $TAOTOKEN_API_KEY \ | head -c 300能返回模型列表的 JSON 片段说明 Key 和地址都对。这一步别跳过后面 config.toml 报错时你会省很多排查时间。如果你更习惯在网页里先验证模型是否可用模型对话页面直接选一个模型发一句话就行比 curl 更直观。3. AGENTS.md把口头规则变成仓库制度AGENTS.md 的作用是“每次任务开始前 Codex 都会读的仓库规则”。它和聊天里的临时指令不一样临时指令只影响当前会话AGENTS.md 进了 Git换机器、换会话、换协作者都生效。官方文档里也强调它会按从全局到项目、从根目录到当前目录的顺序组合所以根目录放通用规则子目录放局部规则。我这份 AGENTS.md 刻意写得很短只放长期有效的制度不放具体实现细节。具体实现会变制度不该天天改。下面是可以直接复制的片段# AGENTS.md ## 项目定位 运维处置知识库 MVP。核心闭环生成报告 - 异步归档 - 用户标记 RESOLVED - 相似问题召回已解决经验。 ## 状态约束 - 事件状态只有三个OPEN、RESOLVED、DISMISSED。 - 初始状态必须是 OPEN不允许模型自动标记为 RESOLVED。 - 召回时只注入 RESOLVEDDISMISSED 和 OPEN 一律排除。 ## Git 提交规范 - 执行 git commit 前先让用户确认 type: 简要描述。 - type 取值范围feat / fix / refactor / test / docs / chore。 ## 测试要求 - 涉及 PostgreSQL、pgvector、状态过滤、向量检索的改动必须用 Testcontainers 起真实容器验证。 - 外部模型调用Embedding、标签提取在测试中 Mock不打真实付费接口。 - 不允许用“代码已生成”代替测试通过。 ## 项目错误与优化记录 - 编译、测试、启动、MCP、RAG、性能或配置问题必须记录到 docs/project-error-optimization-log.md。 - 每条记录包含时间、类型、现象、触发场景、根因、影响范围、解决方案、验证方式、后续建议。 ## 阶段边界 - 当前阶段不实现登录权限、用户级隔离、事件删除、前端搜索、OPEN 条件召回。 - 以上内容统一放入 Phase 2 清单不在当前任务中顺手实现。这份文件里最值钱的是最后两条。“阶段边界”直接压住了 Codex 的企业级冲动——它看到状态筛选会想加权限看到召回会想加用户隔离你把“不做什么”写进仓库规则它就不会顺手扩范围。“错误与优化记录”则让失败变成项目资产而不是聊完就忘。一个细节AGENTS.md 不要写成需求文档。需求会变制度相对稳定。我见过有人把整个 PRD 塞进去结果每次改需求都要改 AGENTS.mdCodex 读到的规则和实际代码经常对不上。4. Skills把“会做”变成“按流程做”AGENTS.md 管“什么不能做”Skills 管“按什么步骤做”。一个 Skill 通常是一个目录里面必须有 SKILL.md可选带脚本、参考资料和资产。它的加载方式是渐进的先暴露元数据被选中后才读完整说明。这意味着你可以放很多 Skill但不会一次性撑爆上下文。我的 Skills 目录结构是这样.codex/ └── skills/ ├── brainstorming/ │ └── SKILL.md ├── writing-plans/ │ └── SKILL.md ├── executing-plans/ │ └── SKILL.md └── project-blog/ ├── SKILL.md └── references/ └── outline-template.md四个 Skill 对应四个阶段澄清需求、写计划、执行计划、写复盘。它们串起来是一条链前一个的输出是后一个的输入。下面给一个 brainstorming 的 SKILL.md 骨架你可以直接改成自己的--- name: brainstorming description: 在写代码前逐项确认业务边界、状态流转、失败降级和阶段边界。 --- # Brainstorming ## 触发条件 用户提出新功能、新模块或模糊需求且尚未形成明确 Spec 时。 ## 执行规则 1. 先阅读项目根目录相关文档和 AGENTS.md不要直接写代码。 2. 每次只问一个关键问题并给出你的推荐项和理由。 3. 问题覆盖业务边界、状态流转、召回范围、失败降级、Phase 2 内容。 4. 用户确认后输出一份决策清单每项包含决策点、选择、原因。 ## 禁止 - 不要一次性抛出十个问题。 - 不要在用户确认前生成实现代码。 - 不要替用户决定 Phase 2 的内容。writing-plans 的 SKILL.md 核心是强制计划可验收--- name: writing-plans description: 把确认后的设计拆成按文件、可验证的实施计划。 --- # Writing Plans ## 输出格式 每个任务必须包含 - 文件路径与修改范围 - 对外接口和状态约束 - 失败时是否影响主链路 - 自动化测试场景 - 手工验收步骤 - 明确不在本阶段实现的内容 ## 禁止 - 禁止出现“实现 Service”“完成前端”这类无法验收的抽象动作。 - 禁止把多个文件改动合并成一个任务。Skill 和普通 Prompt 的区别就在这里普通 Prompt 只服务当前问题Skill 携带完整步骤和质量门禁下次任务直接复用。你不需要每次重新解释“先澄清再规划”调用$brainstorming就行。5. config.toml把模型通道和 MCP 收敛到一处Codex 的配置文件放在~/.codex/config.toml。这个文件管两件事模型通道和 MCP 服务。我把 TaoToken 的 base_url 和 Key 引用写在这里项目里的模型调用也读同一组环境变量避免两套配置漂移。# ~/.codex/config.toml model claude-sonnet-4-5 model_provider taotoken [model_providers.taotoken] name TaoToken base_url https://taotoken.net/api env_key TAOTOKEN_API_KEY wire_api chat [mcp_servers.stitch] command npx args [-y, stitch/mcp-server] env { STITCH_API_KEY 你的StitchKey } [project] instructions_file AGENTS.md几个关键点。env_key指向环境变量名不写明文 Key这样 config.toml 可以安全地放进 dotfiles 仓库。wire_api按你实际使用的接口类型填chat 和 responses 两种模式不要混。MCP 服务用command args启动Stitch 这类设计工具通过 MCP 接入后Codex 就能在任务里直接调用它生成页面结构而不是凭空堆 CSS。如果你用的是 Claude Code 那套工作流接入文档在 https://taotoken.net/doc?utm_sourcetaotoken_aicg_blog_endutm_contentdocutm_campaignrewrite 里面有 base_url 和 Key 的对应写法。长期做编码和 Agent 任务的话Coding Plan 页面 https://taotoken.net/coding-plan?utm_sourcetaotoken_aicg_blog_endutm_contentcoding_planutm_campaignrewrite 里有套餐说明按自己的调用量选就行。配好之后项目里的模型调用也统一读这两个变量比如 Java 侧String baseUrl System.getenv(TAOTOKEN_BASE_URL); String apiKey System.getenv(TAOTOKEN_API_KEY); // 标签提取用低成本模型架构评审用高阶模型 String tagModel qwen3.6-flash;这样换机器只需要配一次环境变量config.toml 和项目代码都不用改。6. 验证从一条请求到真实页面配置写完不算完要验证调用真的生效。我按从轻到重的顺序做了四步。第一步确认 Codex 读到了 AGENTS.md。在项目根目录开一个会话直接问请复述当前项目的状态约束和 Git 提交规范。如果它能说出“三个状态、初始 OPEN、只召回 RESOLVED、提交前确认 type”说明 AGENTS.md 生效了。说不出来就检查instructions_file路径和文件位置。第二步确认模型通道通。让 Codex 执行一条最小请求curl -s $TAOTOKEN_BASE_URL/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}] }返回内容里带ok说明 Key、base_url、模型名三者都对。这一步失败最常见的原因是 base_url 多写了或漏写了/v1对照接入文档确认。第三步确认 Skill 能被调用。输入$brainstorming加一句需求看它是否按“每次只问一个问题”的规则执行。如果它一口气抛出一堆问题说明 SKILL.md 没被加载检查目录名和 frontmatter 的 name 是否一致。第四步跑真实测试。这是最重的一步也是最能暴露问题的一步mvn test我的项目最终是 17 个测试、0 失败、0 错误。核心 Service 测试启动真实pgvector/pgvector:pg16容器Embedding 和标签模型被 Mock。测试覆盖了默认状态、状态枚举、标签失败存空数组、Embedding 失败不阻塞存档、相似检索只返回 RESOLVED、低于阈值不进 Prompt、异步失败不影响主响应这些契约。测试通过之后再启动项目打开页面在桌面端和 500px 宽度下各操作一遍确认列表、筛选、弹窗 Markdown 渲染都正常。7. 本篇常见错排查AGENTS.md 不生效。先确认文件在项目根目录且 config.toml 里的instructions_file指向正确。如果放在子目录Codex 只在处理该目录文件时才读。另一个常见原因是文件里塞了太多需求细节Codex 读到了但优先级被后面的临时指令覆盖。config.toml 报 provider 找不到。检查model_provider的值和[model_providers.xxx]的段名是否完全一致大小写敏感。env_key写的是环境变量名不是 Key 本身写错了会报鉴权失败。curl 返回 401。九成是 Key 没 export 成功或者用了旧终端的缓存。新开一个终端echo $TAOTOKEN_API_KEY确认有值。如果值对但还报错检查 base_url 是否误加了尾部斜杠导致路径拼接成双斜杠。Skill 调用没反应。检查 SKILL.md 的 frontmatter 是否有name和description目录名和 name 建议保持一致。渐进式加载意味着元数据不对Skill 根本不会被选中。测试连不上数据库。Testcontainers 需要本地 Docker 在运行。如果报端口冲突检查是否有残留容器没清理docker ps -a看一眼。pgvector 镜像要指定pg16标签用普通 postgres 镜像会缺向量类型。移动端截图异常。我遇到过内置浏览器在 500px 视口下缩放异常看起来像 CSS 回归。后来用独立 headless 浏览器重新渲染同一页面结果正常判定为工具链差异而非代码问题。第一次观察是线索不是结论换一条链路复核再下判断。标签提取失败导致事件丢失。这是设计问题不是 bug。正确行为是保存空 tags保留报告和向量检索能力不启动规则回退或更贵模型重试。如果你发现事件没保存检查异步链路是不是把异常吞掉了。异步存档阻塞了主响应。检查归档逻辑是否真的放到了后台线程池而不是在 SSE 返回前同步执行。测试里应该有一条“异步失败不影响主响应”的用例来锁住这个契约。8. 下一步怎么走配置骨架搭好之后日常使用其实很轻新任务先让 Codex 读 AGENTS.md 和相关文档模糊需求调$brainstorming确认后调$writing-plans出计划执行阶段调$executing-plans涉及前端设计再走 Stitch MCP。模型通道统一走 TaoTokenKey 和 base_url 只配一次。如果你也在家补项目建议先把 AGENTS.md 写短、写死把“不做什么”写进去。Skills 先建两个就够一个澄清一个写计划。MCP 按需接不要一上来全配。验证动作从一条 curl 开始到真实容器测试结束中间任何一步失败都别用“代码已生成”糊过去。需要继续查接入细节的话API Keys 页面在 https://taotoken.net/api-keys?utm_sourcetaotoken_aicg_blog_endutm_contentapi_keysutm_campaignrewrite 接入文档在 https://taotoken.net/doc?utm_sourcetaotoken_aicg_blog_endutm_contentdocutm_campaignrewrite 。先把通道跑通再谈项目完善顺序别反。