简介
说了很久，今天来聊点实际的——怎么让AI助手在你的代码库里不瞎折腾。怎么让它认认真真遵守你的编码规则，而不是三天两头给你写出风格迥异的代码，然后你得花大把时间修修补补。
这套方案实际上是在项目里建一个标准化的目录结构+一个全局入口文件，给AI一个严格遵循的说明书。不管是Cursor、Claude Code还是其他主流AI工具，都能自动识别并遵守这个体系。跨工具、跨项目，一套配置走天下，彻底终结每次换工具都要重新折腾规则的痛苦。
快速开始
有两个入口，看你的场景选一个就行。
如果你只是单个项目需要管理AI行为，用独立模式：
curl -sSL https://raw.githubusercontent.com/chentianming11/agent-friendly-structure/main/init-agent-structure-zh.sh | bash
如果团队里多个项目要共享同一套编码规范、测试标准、安全指南，那就走团队模式：
curl -sSL https://raw.githubusercontent.com/chentianming11/agent-friendly-structure/main/init-agent-structure-zh.sh | bash -s -- --team https://github.com/your-team/agent-rules.git
搞定。无需其他参数。
两种模式
独立模式
最简单直接的一种玩法。在项目里创建一个空模板，所有规则你自己填，一个人说了算。
团队模式
采用git subtree，把团队共享的规则仓库直接嵌入到.agents/目录下。好处很明显——多个项目同时维护一份编码规范、测试实践、安全指南，改一次，同步所有项目。和submodule不同，规则文件就是仓库里的真实文件，git clone下来直接就能用，无需额外操作。
创建后的目录结构长这样：
.├── AGENTS.md← 项目入口（Cursor/Copilot 自动加载；由你填写）├── CLAUDE.md← 一行桥接 `@AGENTS.md`，让 Claude Code 读取 AGENTS.md├── .agents/ ← 通过 git subtree 嵌入的团队共享规则（真实文件，不是指针）│ ├── rules/ ← 共享规则文件（改动应提交到团队仓库，然后 `subtree pull`）│ ├── skills/← 共享的可复用技能模板│ └── examples/← 共享的好/坏代码示例└── .agents-project/ ← 项目专属覆盖（保留在本仓库内）└── rules/└── domain-glossary.md ← 项目专属术语表（由你填写）
拉取最新规则也很简单：
git subtree pull --prefix=.agents <团队仓库 URL> <分支> --squash
做了什么
执行脚本后，它会构建出下面这个骨架：
.├── AGENTS.md← AI agent 的项目入口点（Cursor、Copilot 等会自动加载）├── CLAUDE.md← 仅一行的桥接文件：`@AGENTS.md`，供 Claude Code 使用├── .agents/ ← Agent 需要了解的项目信息全部放在这里│ ├── rules/ ← 项目权威规则（按需读取）│ │ ├── coding-style.md← 代码约定与风格│ │ ├── testing.md ← 测试标准与模式│ │ ├── security.md← 安全要求与检查清单│ │ ├── git-workflow.md← 分支、提交、PR 流程│ │ └── domain-glossary.md ← 项目特定术语│ ├── skills/← 可复用技能模板（任务匹配时按需加载）│ └── examples/← 项目中真实的代码示例│ ├── good/← 要遵循的模式│ └── bad/ ← 要避免的反模式
所有文件都是空模板，核心内容还是要由你来填写，但框架帮你搭好了。
核心概念
AGENTS.md
这是所有AI工具的单一入口点，跨工具统一标准。里面需要包含项目概述、构建命令、边界规则，以及指向.agents/rules/和.agents/skills/的引导。建议控制在200行以内。值得注意的是，它不会硬编码每个规则文件名——AI会按需去读.agents/rules/目录，所以新增或删除规则文件时，完全不需要修改AGENTS.md。
CLAUDE.md
内容只有一行：@AGENTS.md。为什么要多此一举？因为Claude Code默认不会自动加载AGENTS.md，需要通过CLAUDE.md里的@import语法在会话启动时引入。而Cursor、GitHub Copilot这类工具会直接读取AGENTS.md并忽略CLAUDE.md。一个文件解决所有工具的痛点。
.agents/rules/
五个空模板，涵盖团队规范最常见的维度：代码风格、测试标准、安全指南、Git工作流、项目术语。每个模板都命名清晰，AI拿到后能自然匹配到对应任务场景。
.agents/skills/
空目录，用于存放可复用的技能模板。比如某个特定技术栈下常见的操作模式，都可以写成技能，跨项目共享。
.agents/examples/
同样空目录，但至关重要——这里是放真实代码示例的地方。分成good/和bad/两个子目录，分别展示最佳实践和反模式。放的应该是真实的源代码文件（不是markdown），并在文件顶部加一句简短注释说明好在哪里、坏在哪里。
最佳实践
几个关键原则值得记住：
- AGENTS.md保持精简，200行以内，详细的规则通过链接指向其他文件。
- 每个规则文件聚焦一个主题，这样查找和理解都更高效。
- 技能目录随着项目推进逐步积累，不用一开始就塞满。
- 示例从实际代码库中提取，越贴近实战效果越好。
Agent 如何决定加载 .agents/rules/*.md
这里有个容易被忽略的细节：.agents/rules/下的文件不会在会话启动时自动加载到AI的上下文窗口里。Claude Code和Cursor都是按需读取，而AI是否决定打开某个文件，依赖两个信号：
- AGENTS.md中的引导语——脚本里写了"把
.agents/rules/视为项目权威规则"这样的明确说明，请不要削弱它。 - 文件名本身——AI会用当前任务和文件名做语义匹配，来判断要不要读这个文件。
实操含义：
- 使用自描述的文件名：
coding-style.md、testing.md、pr-review.md、kafka-conventions.md。像rules1.md、notes.md、misc.md这类泛化名字几乎不会被读取——模型猜不出它们什么时候适用。 - 领域专属规则放进主题命名的文件，不要堆进一个杂物篮。
- 想让某条规则每次会话都被加载？把它直接写进
AGENTS.md正文——那是两边工具唯一会自动加载的内容。
常见问题
Q: 我需要指定技术栈吗？
A: 不需要。模板是语言无关的——根据你的技术栈填写即可。
Q: 我可以删除不需要的规则文件吗？
A: 可以。直接删除文件即可。AGENTS.md整体引用.agents/rules/目录，无需修改。
Q: 我可以添加更多规则文件吗？
A: 可以。直接在.agents/rules/中创建新的.md文件。Agent会按需读取整个目录，AGENTS.md不需要逐个列举。
Q: 为什么有一个只包含@AGENTS.md的CLAUDE.md？
A: Claude Code默认不会自动加载AGENTS.md（官方文档）。@AGENTS.md这个import语法是官方推荐的桥接方式。Cursor、Copilot等Agent会直接读取AGENTS.md，不会用到CLAUDE.md。
简单。实用。AI友好。
