用 Skill 管理项目文档：让 Code Agent 读懂你的业务

1. 为什么 Code Agent 总在真实仓库里改错代码先说一个我踩过的坑。去年接手一个 Spring Boot 项目业务是「用户选场景 → 和 AI 角色扮演对话 → 按四步法实时评分」。代码量不大但耦合度不低。我让 Code Agent 改评分逻辑它很快定位到评分引擎按「每个维度独立打分」写了一段实现。看起来没毛病跑起来才发现四个评分维度之间有依赖关系——如果用户根本没表达感受那「需要」和「请求」的权重应该降权而不是独立计算。这条规则写在 PRD 里没写在代码注释里Agent 自己翻不到。类似的坑不止一个。练习会话有「闯关」和「自由练习」两种模式状态机不同场景关卡的解锁依赖前置场景通过但解锁逻辑散落在两个 Service 里sessionId 在练习域和用户画像域里含义不同混用会导致数据归属错误。这些问题的根因一样领域知识没有被结构化地记录在仓库里。代码告诉你「怎么做」但说不清「为什么这样做」「哪些约束不能碰」。这就是本文要解决的问题用 Skill 管理项目文档让 Codex、Cline 这类 Code Agent 在动手前先读懂你的业务。核心检索词是 Skill、Code Agent、Codex、AGENTS.md、repo-map。适合谁适合正在用 Code Agent 做存量项目迭代、被「改一处崩三处」折磨的开发者。读完你能拿到一套可复制的 Skill 目录结构、AGENTS.md 模板、repo-map 生成脚本以及验证 Agent 是否真的读懂业务的步骤。先说结论Code Agent 的上限不在模型能力而在你的仓库里有没有它能读懂的知识。模型再强读不到业务约束照样写出「语法正确、业务错误」的代码。下面从知识架构讲起一路给到可复制的配置和排障。2. TaoToken 前置给 Code Agent 一个稳定的模型入口在讲 Skill 之前得先把模型入口这件事说清楚。Code Agent 要读 AGENTS.md、要跑 repo-map 脚本、要理解业务语义这些都依赖一个稳定的模型调用通道。我实测下来用 TaoToken 作为统一入口比较省心它兼容 OpenAI 风格的接口Codex、Cline、Claude Code 这类工具都能直接接。官网地址是 https://taotoken.net/?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_content API 端点是 https://taotoken.net/api 注意 API 地址不加 UTM 参数。你需要先拿到 API Key入口在 https://taotoken.net/api-keys?utm_sourcetaotoken_aicg_blog_endutm_contentapi_keysutm_campaignrewrite 。拿到 Key 之后不同工具的配置方式略有差异但核心三件套是一样的Base URL、API Key、Model ID。这里要强调一点Skill 体系本身是「知识组织方式」和用哪家模型无关。但如果你希望 Agent 在读取大量 references 文件时保持稳定模型入口的稳定性就很关键。我试过在高峰期切换入口结果 Agent 读到一半超时方案生成到一半断了反而更浪费时间。所以先把入口固定下来再谈知识组织。关于模型选择如果你只是做文档理解和代码定位普通对话模型就够如果要做长期编码、Agent 自动跑多轮建议看 Coding Plan入口在 https://taotoken.net/coding-plan?utm_sourcetaotoken_aicg_blog_endutm_contentcoding_planutm_campaignrewrite 。模型对话的调试入口在 https://taotoken.net/chat?utm_sourcetaotoken_aicg_blog_endutm_contentmodel_chatutm_campaignrewrite 接入文档在 https://taotoken.net/doc?utm_sourcetaotoken_aicg_blog_endutm_contentdocutm_campaignrewrite 。为什么把这段放在前面因为后面所有 Skill 配置、repo-map 脚本、验证请求都要通过这个入口跑。你先把 Key 拿到、把工具接上再往下跟做不然每一步都会卡在「请求发不出去」。控制台入口在 https://taotoken.net/console?utm_sourcetaotoken_aicg_blog_endutm_contentconsoleutm_campaignrewrite 可以在这里看调用记录排查问题时很有用。3. 可复制配置Skill 目录结构、AGENTS.md 模板与 repo-map 脚本这一节是全文的技术核心给的都是能直接复制粘贴的配置。先说整体目录结构再说 AGENTS.md 模板最后给 repo-map 生成脚本。3.1 Skill 目录结构整个知识体系分三层对应 Agent 拿到需求后的认知路径第一层是 AGENTS.md 加 repo-map做全局索引与路由第二层是各业务域 Skill装模块核心知识第三层是 references 目录下的详情文件按需展开。目录长这样repo-root/ ├── AGENTS.md ├── .codex/ │ └── skills/ │ ├── nvc-repo-map/ │ │ ├── SKILL.md │ │ └── scripts/ │ │ └── gen_repo_map.py │ ├── nvc-practice-domain/ │ │ ├── SKILL.md │ │ └── references/ │ │ ├── lifecycle.md │ │ ├── round-pipeline.md │ │ ├── state-machine.md │ │ ├── practice-report.md │ │ └── gotchas.md │ ├── nvc-scoring-engine/ │ │ ├── SKILL.md │ │ ├── references/ │ │ └── scripts/ │ │ └── extract_agent_contracts.py │ ├── nvc-scenario-domain/ │ ├── nvc-profile-domain/ │ ├── nvc-auth-user/ │ ├── nvc-knowledge-base/ │ └── nvc-change-playbook/ └── src/main/java/...每个 Skill 是一个 SKILL.md 主文件加一组 references 引用文件。主文件控制在 3000 字以内覆盖四个维度路由判定、使用顺序、关键入口、必守约束。元数据里的 name 和 description 常驻可见用于路由判断主文件在 Skill 被触发时加载references 在 Agent 判断需要时才读。这就是渐进式披露的上下文经济学——大量知识但每次只加载一部分。3.2 AGENTS.md 模板AGENTS.md 是 Agent 拿到需求后读的第一个文件Token 消耗很少但完成最关键的决策我应该读哪个模块的知识。模板如下# AGENTS.md ## 项目简介 本项目是基于非暴力沟通理论的 AI 练习平台。用户选择场景后与 AI 角色扮演对话 系统按四步法观察→感受→需要→请求实时评分。后端 Spring Boot Spring AI。 ## 知识入口 - 全局路由.codex/skills/nvc-repo-map/SKILL.md - 业务域知识.codex/skills/nvc-*-domain/SKILL.md - 跨域变更.codex/skills/nvc-change-playbook/SKILL.md ## 工作约定 1. 动手前先读 nvc-repo-map确认需求归属哪个业务域。 2. 读对应业务域的 SKILL.md再按需读 references。 3. 改动涉及接口、DTO、评分、表结构时必须读 nvc-change-playbook。 4. 发现 Skill 描述与代码不一致在方案中标注差异不要静默按旧知识改。 ## 禁止事项 - 不要跨域混用 sessionId练习域和画像域含义不同。 - 不要跳过闯关模式的评分达标校验。 - 不要只存单边对话AI 回复和用户回复必须成对。3.3 repo-map 生成脚本repo-map 承担路由层核心是一张「需求关键词 → 业务域」的映射表。手工维护容易漏所以配一个生成脚本从代码结构里提取模块和入口和手工维护的映射表交叉比对。脚本用 Python 写放在 nvc-repo-map/scripts/gen_repo_map.py#!/usr/bin/env python3 扫描 Java 源码生成模块到入口类的映射供 repo-map 交叉校验。 import os import re import json ROOT src/main/java MODULE_PATTERN re.compile(rmodules/([a-z-])/) ENTRY_PATTERN re.compile(rpublic class (\w(Controller|Service|Agent))) def scan(): result {} for dirpath, _, filenames in os.walk(ROOT): for fn in filenames: if not fn.endswith(.java): continue path os.path.join(dirpath, fn) m MODULE_PATTERN.search(path) if not m: continue module m.group(1) with open(path, encodingutf-8) as f: content f.read() for em in ENTRY_PATTERN.finditer(content): result.setdefault(module, []).append({ class: em.group(1), path: path.replace(\\, /) }) return result if __name__ __main__: data scan() with open(repo-map.generated.json, w, encodingutf-8) as f: json.dump(data, f, ensure_asciiFalse, indent2) print(f生成 {len(data)} 个模块的入口映射)跑一次python3 gen_repo_map.py会生成 repo-map.generated.json。把它和 SKILL.md 里手工写的入口列表比对不一致就说明知识该更新了。脚本是校验锚点不是替代品——自动生成的索引用来和手工维护的知识交叉比对两者不一致以代码为准更新 Skill。3.4 业务域 SKILL.md 模板以练习域为例主文件覆盖四个维度--- name: nvc-practice-domain description: 需求命中练习会话创建、对话轮次推进、闯关/自由模式切换、 练习报告生成时使用。涉及场景解锁逻辑时主域是场景域不是本域。 --- # 练习域 ## 路由判定 命中以下关键词时使用练习、对话、轮次、闯关、自由模式、练习报告。 反面判定看起来像对话但涉及场景解锁主域是场景域。 ## 使用顺序 1. 先看 references/lifecycle.md 确认会话阶段。 2. 再看 references/round-pipeline.md 确认单轮流程。 3. 改状态推进看 references/state-machine.md。 4. 改报告生成看 references/practice-report.md。 ## 关键入口 - app/src/main/java/nvc/practice/modules/practice/api/PracticeController.java - app/src/main/java/nvc/practice/modules/practice/service/PracticeSessionService.java - app/src/main/java/nvc/practice/modules/practice/service/PracticeRoundService.java - app/src/main/java/nvc/practice/modules/practice/service/PracticeReportService.java ## 必守约束 - 闯关模式和自由练习是两套状态机不要混写。 - 一轮对话里 AI 回复和用户回复必须成对存在。 - 练习报告雷达图数据来源于每轮评分的维度均值不是最后一轮分数。 - 闯关模式下当轮评分全部达标才能解锁下一轮。注意 description 字段的写法把触发条件写成「需求命中某个 API 路径或涉及某个业务动作」同时附带反面条件。写得太窄会漏触发写得太宽会误触发。4. 验证请求确认 Agent 真的读懂了业务配置写完不算完得验证 Agent 是不是真的按 Skill 走。这一节给可复制的验证步骤和成功结果判断标准。4.1 验证一路由是否正确给 Agent 一个模糊需求看它是否先读 repo-map、是否路由到正确的业务域。测试请求需求用户反馈闯关模式下某一轮评分没达标但下一轮还是解锁了帮我排查。预期行为Agent 先读 nvc-repo-map命中「闯关、解锁、评分」关键词路由到练习域和场景域然后读 nvc-practice-domain 的 state-machine.md 和 nvc-scenario-domain 的解锁逻辑。如果它直接去改评分引擎说明路由层没生效。4.2 验证二约束是否被遵守给一个会触发约束的需求看 Agent 是否主动引用约束。测试请求需求优化练习报告的生成速度把雷达图数据改成用最后一轮评分。预期行为Agent 应该指出「雷达图数据来源于每轮评分的维度均值不是最后一轮分数」这是 nvc-practice-domain 的必守约束。如果它直接照做说明约束没被读到。4.3 验证三跨域变更是否触发 playbook测试请求需求给练习会话加一个字段同时要改接口、DTO 和数据库表。预期行为Agent 读 nvc-change-playbook给出影响检查清单和回滚策略。如果它只改了一个文件就交差说明跨域变更的触发条件没写清楚。4.4 成功结果长什么样跑通之后Agent 的输出应该包含明确说明读了哪个 Skill、引用了哪条约束、列出了关键入口的完整路径、标注了知识描述与代码的差异如果有。我实测下来配好 Skill 之后Agent 改练习评分逻辑时不再去动 NvcScoreService 的打分逻辑而是去调整 NvcDependencyGraph 的依赖关系——这正是我们想要的。4.5 用模型对话做快速验证如果你不想每次都跑完整 Agent可以先用模型对话入口做快速验证。把 SKILL.md 的内容贴进去问「这个需求应该改哪个文件」看回答是否符合预期。入口在 https://taotoken.net/chat?utm_sourcetaotoken_aicg_blog_endutm_contentmodel_chatutm_campaignrewrite 。这样能在正式跑 Agent 前先确认知识本身写得对不对。5. 本篇常见错排查401、local proxy failed、reading choices、OAuth配置和验证过程中最容易卡在几个报错上。这一节对照真实报错给排查路径。5.1 401 Unauthorized最常见。原因通常是 API Key 没配对或者 Base URL 写错了。检查三件套Base URL 是不是 https://taotoken.net/api Key 是不是从 https://taotoken.net/api-keys?utm_sourcetaotoken_aicg_blog_endutm_contentapi_keysutm_campaignrewrite 拿的Model ID 是不是填对了。注意 API 地址不加 UTM 参数加了反而可能被当成非法路径。5.2 local proxy failed这个报错通常出现在工具配置了本地代理但代理没起来。排查顺序先确认工具的网络配置里有没有多余的本地代理设置有就关掉再确认 Base URL 是不是直连 https://taotoken.net/api 。如果你在 Codex 的 config.toml 里配了 proxy 字段删掉再试。5.3 reading choices 相关报错这个报错一般出现在模型返回格式不符合预期时。Code Agent 期望结构化输出但模型返回了非结构化文本。排查确认 Model ID 是否支持结构化输出确认 Skill 里的输出契约是否写清楚了 JSON 结构。如果用的是 Cline检查 MCP 配置里的 model 字段和实际调用是否一致。5.4 OAuth 相关报错Claude Code 这类工具走 OAuth 流程时如果 token 过期或 scope 不对会报 OAuth 错误。排查重新走一遍授权流程确认 scope 包含需要的权限。如果用的是 Codex 的 auth.json检查里面的 token 字段是否过期。这里要写全三件套Base URL 填 https://taotoken.net/api Key 填你的 API KeyModel ID 填你选的模型。5.5 Skill 没被触发不是报错但很常见。Agent 跑完没读任何 Skill直接开始改代码。原因通常是 description 写得太窄或者 AGENTS.md 里没写清楚知识入口。排查把 description 改成「需求命中某个 API 路径或涉及某个业务动作」并在 AGENTS.md 里明确写「动手前先读 nvc-repo-map」。5.6 知识过时导致改错Agent 按 Skill 描述改了代码但 Skill 描述和实际代码不一致。这是最危险的情况。排查跑一遍 gen_repo_map.py比对生成的入口映射和 SKILL.md 里写的在 nvc-change-playbook 里加硬约束改完代码必须检查 Skill 是否需要同步更新。排障时如果拿不准去接入文档 https://taotoken.net/doc?utm_sourcetaotoken_aicg_blog_endutm_contentdocutm_campaignrewrite 对照参数或者去控制台 https://taotoken.net/console?utm_sourcetaotoken_aicg_blog_endutm_contentconsoleutm_campaignrewrite 看调用记录。6. 长期编码与 Agent 场景的落地建议如果你只是偶尔用 Code Agent 改改代码上面这套配置可能有点重。但如果你在做长期迭代的存量项目或者想让 Agent 自动跑多轮任务这套 Skill 体系的价值就出来了。长期编码和 Agent 场景建议看 Coding Plan入口在 https://taotoken.net/coding-plan?utm_sourcetaotoken_aicg_blog_endutm_contentcoding_planutm_campaignrewrite 。落地时记住几条经验。第一从一个模块开始不要一次性写 7 个 Skill。先写最复杂的那个业务域跑通几个真实需求后再扩展。第二触发描述比正文更重要description 决定了 Agent 会不会读这个 Skill。第三统一流程命名「单轮对话评分」在练习域、评分引擎域、变更剧本里都叫同一个名字跨模块推理时 Agent 靠名字匹配关联关系。第四把约束写成人话「如果用户没说感受需要和请求的分数要往下降」比「评分维度间存在依赖关系需在评分前解析依赖图」更容易被正确执行。最后回到那个问题如果明天换一个完全不了解这个项目的人或 Agent 来改代码他需要知道什么才能不犯错答案不在代码注释里不在 wiki 里也不在每次口头交接的记忆里。答案在仓库里在 Agent 每次动手前能读到的那份结构化知识里。把 AGENTS.md 和 repo-map 作为可读业务入口用 Skill 组织起来Code Agent 才能真正读懂你的业务。