1. 为什么你的 AI Agent 每次进项目都像“失忆”你有没有遇到过这种场景让 Claude Code 帮你改一个搜索接口它上来就把src/lib/db/里的封装函数绕过去直接在组件里fetch数据库或者 Cursor 在补全时把prisma/migrations/下的 SQL 文件当成普通文本改了两行结果下次迁移直接冲突。更常见的是你明明在项目里跑npm run typecheck才能过 CIAgent 却只跑了npm test就宣布“任务完成”。这不是模型笨而是它每次进入你的代码库时都像第一次来——没有记忆没有上下文。代码库越大Agent 理解项目全貌的成本就越高越容易做出不符合项目规范的操作。AGENTS.md 就是解决这个问题的越来越多 AI Coding Agent 会自动发现或优先读取项目根目录的 AGENTS.md把它当作理解项目上下文的第一入口。Claude Code、Cursor、Codex 这类工具对它的支持程度不同有的自动读取有的需要你在规则里显式引用但方向是一致的——用一份人类可读、Agent 可解析的“项目说明书”把项目目标、目录结构、关键文件、命令体系、验证要求和禁区一次性讲清楚。这篇文章面向正在用 Claude Code、Cursor、Codex 做日常开发的你。我会给出可直接复制的 AGENTS.md 骨架配合 TaoToken 统一 Key/API 通道的配置示例并演示怎么在工具里验证 Agent 是否真的按说明书读取了项目上下文。你不需要一次写完美先写初版再在 Agent 踩坑的过程中迭代。2. TaoToken 前置统一 Key 与 API 通道在写 AGENTS.md 之前先把“Agent 怎么连上模型”这件事固定下来。很多团队的问题是Claude Code 用一套 KeyCursor 用另一套Codex 又单独配结果 AGENTS.md 里写的验证命令还没跑环境变量先乱了。TaoToken 的作用是提供一个统一的 API 通道让你在多个 Agent 工具之间复用同一套 Key 和接入地址减少配置漂移。官网入口在这里https://taotoken.net/?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_content 。API 基础地址是 https://taotoken.net/api 这个地址不加 UTM 参数直接用于代码里的 base_url。你需要先拿到 Key。进入控制台创建 API Keyhttps://taotoken.net/console?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_content 。创建后复制那串sk-开头的字符串后面所有工具都复用它。如果你还没决定用哪个模型可以先在模型对话页面试一下https://taotoken.net/chat?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_content 。对于长期编码和 Agent 场景Coding Plan 更适合按量使用https://taotoken.net/coding-plan?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_content 。接入文档在 https://taotoken.net/doc?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_content API Keys 管理页在 https://taotoken.net/api-keys?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_content 。Claude Code 专用接入说明在 https://taotoken.net/claudecode-anthropic?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_content 。注意不要把 Key 硬编码进 AGENTS.md 或提交到 Git。AGENTS.md 里只写“从环境变量读取”Key 放在本地.env或系统环境变量里。3. 可复制配置AGENTS.md 骨架 环境变量3.1 AGENTS.md 完整骨架下面这份骨架可以直接复制到项目根目录按你的项目替换占位内容。我把它控制在 200 行以内因为 Agent 每次都会读这个文件太长反而影响效率。# AGENTS.md — 给 AI 的项目说明书 本文档为 AI 编程助手Claude Code、Cursor、Codex 等提供项目上下文和操作规范。 请在每次代码修改前阅读本文档确保理解项目目标和约束。 ## 项目目标 本项目是一个面向中小团队的内部知识库系统SaaS核心目标 - 让团队用自然语言搜索内部文档3 秒内返回相关结果 - 支持 Markdown、PDF、Confluence 三种数据源自动索引 - 当前阶段MVP 开发优先保证核心搜索链路跑通暂不做权限系统 优先级搜索链路 索引稳定性 前端体验 权限 ## 关键目录 src/ ├── app/ # Next.js App Router 页面层 │ ├── api/ # API 路由服务端逻辑入口 │ └── (main)/ # 用户端页面 ├── components/ # 共享 UI 组件 │ └── ui/ # 基础 UI 库Button, Input, Modal ├── lib/ # 业务逻辑不要放组件 │ ├── db/ # 数据库查询层Prisma │ └── search/ # 搜索引擎封装 ├── prisma/ # 数据库 Schema 和迁移文件 └── tests/ # 测试文件与 src 目录结构对应 ## 先看这些文件 按优先级排列Agent 应按顺序阅读以理解项目核心 1. prisma/schema.prisma — 数据模型理解所有实体和关系的第一入口 2. src/lib/search/engine.ts — 搜索核心算法所有查询最终都走到这里 3. src/app/api/search/route.ts — 搜索 API 入口理解请求-响应格式 4. src/middleware.ts — 全局中间件理解认证和路由拦截逻辑 5. src/lib/constants.ts — 全局常量和配置项理解业务规则边界 ## 常用命令 ### 开发环境 bash npm run dev # 启动开发服务器 (localhost:3000) npm run db:studio # 启动 Prisma Studio 查看数据库 npm run db:push # 将 schema 变更同步到开发数据库测试npm test # 运行所有测试Vitest npm run test:watch # 监听模式 npx vitest src/lib/search # 只运行搜索模块测试类型检查与构建npm run typecheck # TypeScript 类型检查与构建分离更快 npm run lint # ESLint 检查 npm run build # 生产构建会自动跑 typecheck lint验证要求Agent 在完成任何代码修改后必须依次通过以下验证全部通过才算完成任务类型检查npm run typecheck必须零错误Lint 检查npm run lint必须零警告测试通过npm test必须全部通过构建成功涉及生产代码时npm run build必须成功特殊情况修改数据库 Schema 后必须同时运行npm run db:push新增 API 路由后必须确认返回类型与前端调用一致修改搜索引擎后必须跑npm run test:search专项测试禁区以下操作在任何情况下都不允许禁止直接修改数据库迁移文件prisma/migrations/下的文件由prisma migrate自动生成绝不能手动编辑migration.sql正确做法改 Schema 后重新生成迁移禁止引入新的后端依赖新增 npm 包前必须确认是否为已有依赖如需新增必须先询问确认禁止删除或修改测试文件测试失败时只能修改实现代码让测试通过只有新增功能并编写对应测试时才能新增测试文件禁止在组件中直接调用数据库所有数据库操作必须通过src/lib/db/中的封装函数组件和页面只能通过 API 路由获取数据禁止修改 ESLint/Prettier 配置.eslintrc.*、.prettierrc.*不可更改lint 报错时修改代码而非规则### 3.2 环境变量与 TaoToken 接入 在项目根目录创建 .env.local确保在 .gitignore 里写入 bash TAOTOKEN_API_KEYsk-你的Key TAOTOKEN_BASE_URLhttps://taotoken.net/api如果你用 Claude Code可以在~/.claude/settings.json或项目级配置里指定 Anthropic 兼容端点。具体字段参考接入文档https://taotoken.net/doc?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_content 。Claude Code 的专用说明在 https://taotoken.net/claudecode-anthropic?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_content 。如果你用 Cursor在 Settings → Models → OpenAI API Key 里填入 KeyBase URL 填https://taotoken.net/api。Codex 类似在配置里指定base_url和api_key环境变量。提示AGENTS.md 里不要写具体 Key只写“从TAOTOKEN_API_KEY环境变量读取”。这样换 Key 时不用改说明书。4. 验证请求Agent 是否真的读了 AGENTS.md写完说明书怎么确认 Agent 真的按它执行我试过最直接的办法给它一个会触发“禁区”的任务看它是否拒绝或先询问。4.1 用 Claude Code 验证在项目根目录启动 Claude Code输入请帮我在 src/components/SearchBox.tsx 里直接查询数据库获取最近 10 条文档。如果 AGENTS.md 生效Agent 应该指出这违反了“禁止在组件中直接调用数据库”的禁区并建议通过src/lib/db/封装或 API 路由实现。如果它直接开始写prisma.document.findMany()说明它没读或没重视 AGENTS.md。4.2 用 Cursor 验证在 Cursor 里打开 Chat输入修改 prisma/migrations/ 下的 migration.sql给 documents 表加一个 tags 字段。正确行为是Agent 拒绝手动改迁移文件并提示你应该改schema.prisma后运行npm run db:push或prisma migrate dev。4.3 用 API 直接验证通道如果你想确认 TaoToken 通道本身是通的可以用 curl 发一个最小请求curl https://taotoken.net/api/v1/chat/completions \ -H Authorization: Bearer $TAOTOKEN_API_KEY \ -H Content-Type: application/json \ -d { model: claude-3-5-sonnet, messages: [{role: user, content: 回复 OK}], max_tokens: 10 }返回里如果有choices字段且内容为OK说明 Key 和通道正常。模型名按你实际使用的填具体可用模型在模型对话页面能看到https://taotoken.net/chat?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_content 。4.4 验证结果对照表验证项期望行为失败表现禁区识别拒绝直接改迁移文件直接编辑migration.sql验证要求改完跑typechecklinttest只跑test就结束目录规范数据库操作走src/lib/db/组件里直接prisma查询命令准确性使用 AGENTS.md 里的完整命令猜测命令或省略参数5. 本篇常见错排查5.1 Agent 完全没读 AGENTS.md先确认文件名和位置。AGENTS.md 必须放在项目根目录大小写敏感。部分工具需要你在设置里显式开启“读取项目规则”或把 AGENTS.md 加入上下文。Claude Code 通常自动读取Cursor 需要在 Rules 里确认。如果还是不行在对话开头手动说一句“请先读 AGENTS.md”。5.2 读了但忽略禁区检查禁区写法是否足够强硬。用“禁止”开头解释原因给出正确做法。模糊的“尽量不要”会被 Agent 当成建议。另外禁区不要超过 8 条太多会稀释注意力。把最关键的放前面。5.3 验证命令跑不过常见原因是 AGENTS.md 里的命令和package.json不一致。比如你写了npm run typecheck但package.json里实际是npm run type-check。Agent 会精确复制你写的命令所以写之前先跑一遍确认。另外npm run build如果会自动跑 typecheck 和 lint就在 AGENTS.md 里注明避免 Agent 重复跑。5.4 Key 或通道报错如果 Agent 报 401 或连接失败先检查TAOTOKEN_API_KEY是否在启动 Agent 的终端里可见。在终端里执行echo $TAOTOKEN_API_KEY如果为空说明环境变量没加载。.env.local不会自动被所有工具读取Claude Code 和 Cursor 读取环境变量的方式不同必要时在工具设置里手动填。API Keys 管理页可以重新生成 Keyhttps://taotoken.net/api-keys?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_content 。5.5 AGENTS.md 太长导致响应变慢控制在 200 行以内。完整 API 文档、数据库设计文档、PRD 不要直接贴进去而是写“这些文档在哪里需要时再去读”。AGENTS.md 的目标是帮 Agent 快速理解项目不是替代所有项目文档。6. 把说明书变成团队资产AGENTS.md 不是一次写完就锁死的文件。它应该随项目演进同步更新建议在 PR 模板里加一条“是否更新 AGENTS.md”的检查项。团队里每个人踩到的 Agent 坑都可以变成禁区里的一条新规则。如果你还在选工具或配通道可以从模型对话页面先试一下效果https://taotoken.net/chat?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_content 。长期编码和 Agent 场景用 Coding Plan 更省心https://taotoken.net/coding-plan?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_content 。接入细节看文档https://taotoken.net/doc?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_content 。Claude Code 用户直接参考专用接入页https://taotoken.net/claudecode-anthropic?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_content 。最后留一个我踩过的坑AGENTS.md 里写的命令一定要在干净终端里跑一遍。我有次写了npm run test:search但那个脚本只在 CI 里存在本地根本没定义Agent 跑失败后开始自己猜命令反而绕过了验证要求。说明书里的每个字Agent 都会当真。
AGENTS.md 实战：给 AI Agent 写一份项目说明书，让 Claude Code 与 Cursor 少走弯路
1. 为什么你的 AI Agent 每次进项目都像“失忆”你有没有遇到过这种场景让 Claude Code 帮你改一个搜索接口它上来就把src/lib/db/里的封装函数绕过去直接在组件里fetch数据库或者 Cursor 在补全时把prisma/migrations/下的 SQL 文件当成普通文本改了两行结果下次迁移直接冲突。更常见的是你明明在项目里跑npm run typecheck才能过 CIAgent 却只跑了npm test就宣布“任务完成”。这不是模型笨而是它每次进入你的代码库时都像第一次来——没有记忆没有上下文。代码库越大Agent 理解项目全貌的成本就越高越容易做出不符合项目规范的操作。AGENTS.md 就是解决这个问题的越来越多 AI Coding Agent 会自动发现或优先读取项目根目录的 AGENTS.md把它当作理解项目上下文的第一入口。Claude Code、Cursor、Codex 这类工具对它的支持程度不同有的自动读取有的需要你在规则里显式引用但方向是一致的——用一份人类可读、Agent 可解析的“项目说明书”把项目目标、目录结构、关键文件、命令体系、验证要求和禁区一次性讲清楚。这篇文章面向正在用 Claude Code、Cursor、Codex 做日常开发的你。我会给出可直接复制的 AGENTS.md 骨架配合 TaoToken 统一 Key/API 通道的配置示例并演示怎么在工具里验证 Agent 是否真的按说明书读取了项目上下文。你不需要一次写完美先写初版再在 Agent 踩坑的过程中迭代。2. TaoToken 前置统一 Key 与 API 通道在写 AGENTS.md 之前先把“Agent 怎么连上模型”这件事固定下来。很多团队的问题是Claude Code 用一套 KeyCursor 用另一套Codex 又单独配结果 AGENTS.md 里写的验证命令还没跑环境变量先乱了。TaoToken 的作用是提供一个统一的 API 通道让你在多个 Agent 工具之间复用同一套 Key 和接入地址减少配置漂移。官网入口在这里https://taotoken.net/?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_content 。API 基础地址是 https://taotoken.net/api 这个地址不加 UTM 参数直接用于代码里的 base_url。你需要先拿到 Key。进入控制台创建 API Keyhttps://taotoken.net/console?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_content 。创建后复制那串sk-开头的字符串后面所有工具都复用它。如果你还没决定用哪个模型可以先在模型对话页面试一下https://taotoken.net/chat?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_content 。对于长期编码和 Agent 场景Coding Plan 更适合按量使用https://taotoken.net/coding-plan?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_content 。接入文档在 https://taotoken.net/doc?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_content API Keys 管理页在 https://taotoken.net/api-keys?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_content 。Claude Code 专用接入说明在 https://taotoken.net/claudecode-anthropic?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_content 。注意不要把 Key 硬编码进 AGENTS.md 或提交到 Git。AGENTS.md 里只写“从环境变量读取”Key 放在本地.env或系统环境变量里。3. 可复制配置AGENTS.md 骨架 环境变量3.1 AGENTS.md 完整骨架下面这份骨架可以直接复制到项目根目录按你的项目替换占位内容。我把它控制在 200 行以内因为 Agent 每次都会读这个文件太长反而影响效率。# AGENTS.md — 给 AI 的项目说明书 本文档为 AI 编程助手Claude Code、Cursor、Codex 等提供项目上下文和操作规范。 请在每次代码修改前阅读本文档确保理解项目目标和约束。 ## 项目目标 本项目是一个面向中小团队的内部知识库系统SaaS核心目标 - 让团队用自然语言搜索内部文档3 秒内返回相关结果 - 支持 Markdown、PDF、Confluence 三种数据源自动索引 - 当前阶段MVP 开发优先保证核心搜索链路跑通暂不做权限系统 优先级搜索链路 索引稳定性 前端体验 权限 ## 关键目录 src/ ├── app/ # Next.js App Router 页面层 │ ├── api/ # API 路由服务端逻辑入口 │ └── (main)/ # 用户端页面 ├── components/ # 共享 UI 组件 │ └── ui/ # 基础 UI 库Button, Input, Modal ├── lib/ # 业务逻辑不要放组件 │ ├── db/ # 数据库查询层Prisma │ └── search/ # 搜索引擎封装 ├── prisma/ # 数据库 Schema 和迁移文件 └── tests/ # 测试文件与 src 目录结构对应 ## 先看这些文件 按优先级排列Agent 应按顺序阅读以理解项目核心 1. prisma/schema.prisma — 数据模型理解所有实体和关系的第一入口 2. src/lib/search/engine.ts — 搜索核心算法所有查询最终都走到这里 3. src/app/api/search/route.ts — 搜索 API 入口理解请求-响应格式 4. src/middleware.ts — 全局中间件理解认证和路由拦截逻辑 5. src/lib/constants.ts — 全局常量和配置项理解业务规则边界 ## 常用命令 ### 开发环境 bash npm run dev # 启动开发服务器 (localhost:3000) npm run db:studio # 启动 Prisma Studio 查看数据库 npm run db:push # 将 schema 变更同步到开发数据库测试npm test # 运行所有测试Vitest npm run test:watch # 监听模式 npx vitest src/lib/search # 只运行搜索模块测试类型检查与构建npm run typecheck # TypeScript 类型检查与构建分离更快 npm run lint # ESLint 检查 npm run build # 生产构建会自动跑 typecheck lint验证要求Agent 在完成任何代码修改后必须依次通过以下验证全部通过才算完成任务类型检查npm run typecheck必须零错误Lint 检查npm run lint必须零警告测试通过npm test必须全部通过构建成功涉及生产代码时npm run build必须成功特殊情况修改数据库 Schema 后必须同时运行npm run db:push新增 API 路由后必须确认返回类型与前端调用一致修改搜索引擎后必须跑npm run test:search专项测试禁区以下操作在任何情况下都不允许禁止直接修改数据库迁移文件prisma/migrations/下的文件由prisma migrate自动生成绝不能手动编辑migration.sql正确做法改 Schema 后重新生成迁移禁止引入新的后端依赖新增 npm 包前必须确认是否为已有依赖如需新增必须先询问确认禁止删除或修改测试文件测试失败时只能修改实现代码让测试通过只有新增功能并编写对应测试时才能新增测试文件禁止在组件中直接调用数据库所有数据库操作必须通过src/lib/db/中的封装函数组件和页面只能通过 API 路由获取数据禁止修改 ESLint/Prettier 配置.eslintrc.*、.prettierrc.*不可更改lint 报错时修改代码而非规则### 3.2 环境变量与 TaoToken 接入 在项目根目录创建 .env.local确保在 .gitignore 里写入 bash TAOTOKEN_API_KEYsk-你的Key TAOTOKEN_BASE_URLhttps://taotoken.net/api如果你用 Claude Code可以在~/.claude/settings.json或项目级配置里指定 Anthropic 兼容端点。具体字段参考接入文档https://taotoken.net/doc?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_content 。Claude Code 的专用说明在 https://taotoken.net/claudecode-anthropic?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_content 。如果你用 Cursor在 Settings → Models → OpenAI API Key 里填入 KeyBase URL 填https://taotoken.net/api。Codex 类似在配置里指定base_url和api_key环境变量。提示AGENTS.md 里不要写具体 Key只写“从TAOTOKEN_API_KEY环境变量读取”。这样换 Key 时不用改说明书。4. 验证请求Agent 是否真的读了 AGENTS.md写完说明书怎么确认 Agent 真的按它执行我试过最直接的办法给它一个会触发“禁区”的任务看它是否拒绝或先询问。4.1 用 Claude Code 验证在项目根目录启动 Claude Code输入请帮我在 src/components/SearchBox.tsx 里直接查询数据库获取最近 10 条文档。如果 AGENTS.md 生效Agent 应该指出这违反了“禁止在组件中直接调用数据库”的禁区并建议通过src/lib/db/封装或 API 路由实现。如果它直接开始写prisma.document.findMany()说明它没读或没重视 AGENTS.md。4.2 用 Cursor 验证在 Cursor 里打开 Chat输入修改 prisma/migrations/ 下的 migration.sql给 documents 表加一个 tags 字段。正确行为是Agent 拒绝手动改迁移文件并提示你应该改schema.prisma后运行npm run db:push或prisma migrate dev。4.3 用 API 直接验证通道如果你想确认 TaoToken 通道本身是通的可以用 curl 发一个最小请求curl https://taotoken.net/api/v1/chat/completions \ -H Authorization: Bearer $TAOTOKEN_API_KEY \ -H Content-Type: application/json \ -d { model: claude-3-5-sonnet, messages: [{role: user, content: 回复 OK}], max_tokens: 10 }返回里如果有choices字段且内容为OK说明 Key 和通道正常。模型名按你实际使用的填具体可用模型在模型对话页面能看到https://taotoken.net/chat?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_content 。4.4 验证结果对照表验证项期望行为失败表现禁区识别拒绝直接改迁移文件直接编辑migration.sql验证要求改完跑typechecklinttest只跑test就结束目录规范数据库操作走src/lib/db/组件里直接prisma查询命令准确性使用 AGENTS.md 里的完整命令猜测命令或省略参数5. 本篇常见错排查5.1 Agent 完全没读 AGENTS.md先确认文件名和位置。AGENTS.md 必须放在项目根目录大小写敏感。部分工具需要你在设置里显式开启“读取项目规则”或把 AGENTS.md 加入上下文。Claude Code 通常自动读取Cursor 需要在 Rules 里确认。如果还是不行在对话开头手动说一句“请先读 AGENTS.md”。5.2 读了但忽略禁区检查禁区写法是否足够强硬。用“禁止”开头解释原因给出正确做法。模糊的“尽量不要”会被 Agent 当成建议。另外禁区不要超过 8 条太多会稀释注意力。把最关键的放前面。5.3 验证命令跑不过常见原因是 AGENTS.md 里的命令和package.json不一致。比如你写了npm run typecheck但package.json里实际是npm run type-check。Agent 会精确复制你写的命令所以写之前先跑一遍确认。另外npm run build如果会自动跑 typecheck 和 lint就在 AGENTS.md 里注明避免 Agent 重复跑。5.4 Key 或通道报错如果 Agent 报 401 或连接失败先检查TAOTOKEN_API_KEY是否在启动 Agent 的终端里可见。在终端里执行echo $TAOTOKEN_API_KEY如果为空说明环境变量没加载。.env.local不会自动被所有工具读取Claude Code 和 Cursor 读取环境变量的方式不同必要时在工具设置里手动填。API Keys 管理页可以重新生成 Keyhttps://taotoken.net/api-keys?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_content 。5.5 AGENTS.md 太长导致响应变慢控制在 200 行以内。完整 API 文档、数据库设计文档、PRD 不要直接贴进去而是写“这些文档在哪里需要时再去读”。AGENTS.md 的目标是帮 Agent 快速理解项目不是替代所有项目文档。6. 把说明书变成团队资产AGENTS.md 不是一次写完就锁死的文件。它应该随项目演进同步更新建议在 PR 模板里加一条“是否更新 AGENTS.md”的检查项。团队里每个人踩到的 Agent 坑都可以变成禁区里的一条新规则。如果你还在选工具或配通道可以从模型对话页面先试一下效果https://taotoken.net/chat?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_content 。长期编码和 Agent 场景用 Coding Plan 更省心https://taotoken.net/coding-plan?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_content 。接入细节看文档https://taotoken.net/doc?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_content 。Claude Code 用户直接参考专用接入页https://taotoken.net/claudecode-anthropic?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_content 。最后留一个我踩过的坑AGENTS.md 里写的命令一定要在干净终端里跑一遍。我有次写了npm run test:search但那个脚本只在 CI 里存在本地根本没定义Agent 跑失败后开始自己猜命令反而绕过了验证要求。说明书里的每个字Agent 都会当真。
