AGENTS.md 实战：100 行规则文件让 AI 编程工具秒懂 monorepo 全栈项目

1. 为什么 monorepo 里 AI 编程工具总是“看不懂”项目如果你维护的是一个 monorepo 全栈项目前端在apps/web、后端在apps/api、共享类型在packages/shared那你大概率遇到过这种场景让 AI 编程工具加一个接口它把数据库查询直接写进了路由函数让它改前端组件它顺手把pnpm换成了npm让它补测试它回你一句“已实现功能”就收工了。问题不在于模型不会写代码而在于它每次会话开始时对你的项目一无所知。它不知道你们用 pnpm workspace 而不是 npm不知道 API 层只做参数校验、业务逻辑必须放services/不知道apps/legacy/是只读的历史包袱。这些约定平时靠口头提醒和 Code Review 兜着但 AI 工具不会参加你们的站会。AGENTS.md 就是为解决这件事而生的。它是一份放在仓库根目录的规则文件用自然语言把“团队约定”写清楚让每个支持该标准的 AI 编程工具在开工前自动读取。它不是什么新框架本质就是一份给 Agent 看的入职培训文档提交进 Git全团队共享。这篇内容会给你一份 100 行以内的 AGENTS.md 骨架、TaoToken 统一 Key 的配置片段以及用 Cline 验证规则是否真正生效的具体动作目标是一次配置让工具读懂你的 monorepo 结构。2. TaoToken 前置统一 Key 与 API 通道在写规则文件之前先把 AI 编程工具的接入通道理顺。monorepo 项目往往同时用多个工具——Cline 写业务代码、Claude Code 做重构、偶尔还要在网页端对话验证模型输出。如果每个工具各配一套 Key管理成本高切换模型也麻烦。TaoToken 的思路是提供一个统一的 API 通道一个 Key 覆盖多种模型工具侧只需要改baseURL和apiKey两个字段。官网地址是 https://taotoken.net/?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_content API 端点是 https://taotoken.net/api 注意 API 地址不带 UTM 参数配置时直接填这个。你需要先拿到 Key。进入控制台创建 API Key地址是 https://taotoken.net/console?utm_sourcetaotoken_aicg_blog_endutm_contentconsoleutm_campaignrewrite 创建后复制保存后面配置 Cline 和 Claude Code 都要用。如果你还没决定用哪个模型可以先在模型对话页面试一下输出质量地址是 https://taotoken.net/models?utm_sourcetaotoken_aicg_blog_endutm_contentmodel_chatutm_campaignrewrite 确认模型对 TypeScript 和 Python 的理解符合预期再接入编辑器。这一步的意义在于规则文件解决“AI 懂不懂项目”统一 Key 解决“AI 能不能稳定调用”。两件事都做完工具才真正可用。3. 可复制配置AGENTS.md 骨架 settings.json3.1 AGENTS.md 骨架控制在 100 行内规则文件的第一原则是短。Agent 每个会话都读它写太长会导致关键规则被淹没在中段。只写“与默认行为不同”的约定默认就会做对的事情不用写。# AGENTS.md ## 项目概览 - 前端Next.js 15App Router TypeScript位于 apps/web - 后端FastAPIPython 3.12 SQLAlchemy 2位于 apps/api - 共享类型packages/shared前后端都从这里导入 - 包管理根目录 pnpm workspace后端依赖用 uv禁止 pip 裸装 ## 编码规则只写与默认不同的约定 - 所有 TS 文件必须显式类型标注禁止 any - API 路由只做参数校验与转发业务逻辑一律放 services/ 层 - 数据库访问必须走 repositories/ 模式禁止路由里写裸 SQL - 新增接口必须配套 Pydantic 响应模型 - 前端组件默认服务端组件需要交互才加 use client ## 目录结构 - apps/web/src/app/ 页面路由薄层 - apps/web/src/components/ 展示组件 - apps/api/app/services/ 业务逻辑核心别绕过 - apps/api/app/repositories/ 数据访问唯一允许碰 ORM 的地方 - packages/shared/ 共享类型与工具函数 ## 测试与提交 - 改动必须补测试前端 vitest后端 pytest - 提交信息遵循 Conventional Commitsfeat/fix/docs/refactor - 提交前必须跑 pnpm lint 与 uv run pytest全绿才允许提交 - 禁止修改 apps/legacy/ 目录历史包袱只读 ## 任务执行约定 - 动手前先读本文件与目标目录现有代码保持风格一致 - 先写测试再实现TDD测试要覆盖异常分支 - 只改任务指定目录跨包改动需在回复中说明原因这份骨架大约 40 行覆盖了 monorepo 全栈项目最容易出错的几个点包管理器选择、分层边界、共享类型位置、只读目录。你可以按自己项目替换路径和框架名。3.2 Cline 的 settings.json 配置片段Cline 是 VS Code 里的 AI 编程插件支持自定义 API 通道。在 VS Code 设置里找到 Cline 配置或直接编辑settings.json填入以下内容{ cline.apiProvider: openai, cline.openAiBaseUrl: https://taotoken.net/api, cline.openAiApiKey: 你的_TaoToken_Key, cline.openAiModelId: claude-sonnet-4-20250514, cline.customInstructions: 始终先读取仓库根目录的 AGENTS.md严格遵守其中的分层规则与目录约定。 }关键在最后一行customInstructions它让 Cline 在每次会话启动时主动去读 AGENTS.md。不同工具对规则文件的自动读取支持程度不一样Cline 目前需要显式提示加上这一句能保证规则被注入上下文。如果你用的是 Claude Code配置在.claude/settings.json{ apiKeyHelper: echo 你的_TaoToken_Key, env: { ANTHROPIC_BASE_URL: https://taotoken.net/api } }Claude Code 会自动读取仓库根目录的CLAUDE.md你可以把 AGENTS.md 的内容软链接过去或者直接写一份CLAUDE.md引用 AGENTS.md# CLAUDE.md 本仓库规则以 AGENTS.md 为准请先完整阅读根目录 AGENTS.md 再执行任务。3.3 用 glob 让规则精准命中Cursor 用户如果你的团队用 Cursor可以在.cursor/rules/下按路径拆分规则避免一份文件管全局导致过长--- description: 后端服务层规则 globs: apps/api/**/*.py --- - 函数必须有类型注解与 docstring - 异步接口优先 async def - service 层禁止直接 import ORM 细节 - 抛出领域异常不裸抛 SQLAlchemyError这样后端规则只对 Python 文件生效前端规则只对 tsx 生效规则文件整体保持精简。4. 验证请求用 Cline 跑一个真实任务看规则是否生效配置写完不算完得验证规则真的被 Agent 读进去了。找一个边界清晰的小任务来测在apps/api里新增一个“查询订单详情”的接口。在 Cline 对话框里输入这样的任务描述请按 AGENTS.md 实现查询订单详情接口apps/api 1. 先读 AGENTS.md 与 services/ 现有代码保持分层与风格一致 2. 先写 pytest 测试再实现TDD测试要覆盖 404 分支 3. 完成后运行 uv run pytest 并汇报结果 4. 只改 apps/api禁止触碰 apps/legacy观察 Cline 的执行过程重点看三个信号第一它有没有主动读 AGENTS.md。如果配置正确Cline 会在第一步调用文件读取工具打开根目录的 AGENTS.md你可以在它的工具调用记录里看到。第二它把业务逻辑放在哪。规则生效的话它会创建apps/api/app/services/order_service.py和apps/api/app/repositories/order_repository.py而不是把 SQL 直接写进路由函数。第三它有没有先写测试。规则里写了 TDD生效的话它会先创建apps/api/tests/test_order_service.py再写实现代码。如果这三个信号都对了说明规则文件已经起作用。如果它还是把逻辑写进路由检查customInstructions是否配置、AGENTS.md 是否在仓库根目录、文件是否被.gitignore排除。验证通过后你可以把同样的任务丢给 Claude Code 或 Cursor对比不同工具对同一份 AGENTS.md 的遵守程度。实测下来规则写得越具体、越靠前遵守率越高。5. 本篇常见错排查规则文件写了但 Agent 不读。最常见的原因是工具不支持自动读取或者文件不在仓库根目录。Cline 需要customInstructions显式提示Claude Code 读的是CLAUDE.md而不是AGENTS.md。先确认工具读哪个文件名再决定是软链接还是写引用。规则太长导致中段被忽略。这是“lost in the middle”效应上下文越长模型对中后段内容的遵从度越低。对策是把最重要的规则放在文件开头整体控制在 100 行以内长任务拆成新会话执行。monorepo 里规则串扰。根目录的规则对apps/legacy/也生效导致 Agent 试图“修复”只读目录。Claude Code 可以用claudeMdExcludes排除{ claudeMdExcludes: { apps/legacy/**: [root], apps/web/**: [apps/api] } }API 调用报 401 或连接失败。检查baseURL是否填了https://taotoken.net/api不带 UTMKey 是否从控制台正确复制。如果 Key 没问题但模型返回异常去模型对话页面单独测一次确认是通道问题还是模型问题。规则和实际代码不一致。AGENTS.md 写了“禁止 any”但仓库里到处是 anyAgent 会认为规则是摆设。规则文件必须和代码现状一致要么先清理代码要么在规则里注明“存量代码暂不强制新增代码必须遵守”。提交前检查没跑。规则文件是软约束pre-commit 钩子是硬约束。在.githooks/pre-commit里加上 lint 和测试AI 生成的代码同样逃不过#!/usr/bin/env bash set -euo pipefail echo 前端检查 npx eslint apps/web/src --max-warnings 0 echo 后端检查 uv run ruff check apps/api echo 测试 uv run pytest apps/api/tests -q6. 把规则文件纳入日常流程规则文件不是写完就完事的文档它需要跟着项目演进。我的做法是每次 Code Review 发现 AI 反复犯同一个错就把这条约定补进 AGENTS.md而不是在评论里重复提醒。这样规则文件会越来越贴合项目实际Agent 的一次通过率也会逐步提升。如果你还在用多个工具各配一套 Key建议先去 https://taotoken.net/api-keys?utm_sourcetaotoken_aicg_blog_endutm_contentapi_keysutm_campaignrewrite 创建一个统一 Key把 Cline、Claude Code、Cursor 的接入通道统一到 https://taotoken.net/api 。接入文档在 https://taotoken.net/doc?utm_sourcetaotoken_aicg_blog_endutm_contentdocutm_campaignrewrite 里面有各工具的详细配置示例。长期做编码和 Agent 任务的团队可以看看 Coding Plan 的额度方案 https://taotoken.net/coding-plan?utm_sourcetaotoken_aicg_blog_endutm_contentcoding_planutm_campaignrewrite 比按量付费更适合高频使用场景。规则文件的价值不在于写得多漂亮而在于它让“团队约定”从口头知识变成每次会话都稳定注入的上下文。先写 30 行跑一个任务验证再逐步补全。这比一次性写 300 行然后没人维护要有效得多。