企业官网建设流程全解析

先说一个我踩过很多次的坑：同一个项目，在 Cursor 里写得顺风顺水，AI 对代码风格、目录结构的理解都很到位，切到命令行用 Claude Code 跑个批量重构，结果它像失忆一样，把项目里约定好的命名规范全忘了，甚至开始往src里塞测试文件。

后来我花时间把各端的规则文件捋了一遍，才发现问题不在 AI 模型本身，而在我们喂给 AI 的“上下文规则”一直是各管各的。Cursor 看的是.cursor/rules，Claude Code 读的是CLAUDE.md，GitHub Copilot 认的是copilot-instructions.md，再加上 Codex、Cline、Augment 这类工具，每个都有自己的一套配置文件。一个项目维护五六份规则文件，改一处漏一处，AI 的行为自然就乱。

这篇文章就聊聊我是怎么用一套“统一 Agent Rules 架构”解决这个问题的。核心思路是：不维护多份规则，而是维护一份规则源，再用脚本按各工具的要求生成对应格式。这样无论你在哪个编辑器、哪个 CLI、哪台机器上跑 AI 编程，它拿到的规则都是同一套，并且是最新的。

1. 碎片化到底碎在哪：先看清问题全貌

很多人没意识到，AI 编程工具链的碎片化，不是“工具太多”的问题，而是“同一份知识被重复维护了太多次”的问题。只要团队的 AI 辅助开发涉及两个以上工具，这种碎片化就必然出现。

1.1 一份规则，N 个配置文件

我先盘一下目前主流 AI 编程工具的规则机制。这里的“规则”指的不是模型权重，而是我们通过配置文件给模型注入的项目级指令，用来约束它理解项目结构、代码风格、接口约定、禁止事项等。

表面上只是文件名不同，实际上加载逻辑差异很大。Cursor 的规则可以按目录匹配，比如frontend/*.mdc只在改前端代码时加载；Claude Code 的CLAUDE.md则是整个会话的全局背景，无论你改哪块代码它都在上下文里；Copilot 的 instructions 又是另一套条件触发逻辑。

这就导致一个很尴尬的局面：你在 Cursor 里精调好的规则，换到 Claude Code 里要么不生效，要么需要手动复制一份，而复制过去的文件一旦忘了同步，两边行为就开始分叉。团队里如果有人用 Cursor、有人用 JetBrains 系的 AI 插件、有人直接用终端 CLI，规则文件的管理成本直接变成灾难。

1.2 工具切换时的“规则失忆”

碎片化最直接的体感，就是 AI 换了个工具之后就“失忆”了。

我举个例子。之前做一个包含apps/web、apps/api、packages/shared的 monorepo，我们希望 AI 在改代码时遵守几个约定：新增 API 路由必须写 Zod 校验、修改 shared 包必须跑全量测试、前端组件不允许出现内联样式。这些约定写在了 Cursor 的规则文件里，开发时挺好用。

后来因为 CI 里要用自动化脚本调用 Claude Code 做代码审查，我临时写了一份精简版规则放在CLAUDE.md。结果 Claude Code 在审查时完全不理会“修改 shared 包必须跑全量测试”这个约束，因为它根本不知道这条规则的存在——Cursor 的规则文件它不读。而我在CLAUDE.md里写的规则又不完整，导致同一段代码在不同工具下的审查结论竟然不一样。

这个问题的本质是：规则与工具绑定，而不是与项目绑定。每个工具都尝试构建自己的“项目上下文”，但上下文源文件不同，AI 的行为自然不统一。

1.3 碎片的隐性成本：团队协作时的“提示词漂移”

还有一层隐性成本，团队协作时才会暴露。

假设团队有 5 个人，分别用不同的 AI 工具。每个人为了让自己手头的工具好用，都往项目里加了规则文件。有人加了.cursor/rules/backend.mdc，有人补了CLAUDE.md，有人更新了.github/copilot-instructions.md。这些文件互相之间没有引用关系，甚至内容有冲突——比如一个人规定“接口返回格式统一为{ code, data, message }”，另一个人在不同文件里写的是“接口返回{ success, data, error }”。

当 AI 工具读取规则时，它只认自己对应的文件，所以每个人看到的 AI 行为都是“对的”。可一旦两个人交换任务，或者 CI 里跑自动化任务，AI 的行为就出现漂移。这就是典型的“提示词漂移”问题——规则没有单一真实源，每个人维护的数据是不同步的副本。

我在团队里做过一次统计：一个中型项目，规则相关文件有 7 份，内容重叠率超过 60%，其中有 3 处直接冲突。修复冲突的过程比写规则本身还累。

2. 统一 Agent Rules 架构：从“规则文件”到“规则体系”

既然问题出在“多份规则副本”，解决思路就清楚了：把副本收敛成一份源头，其余文件全部由源头自动生成。这就是我所说的“统一 Agent Rules 架构”。

2.1 核心设计思想：单一真实源 + 分层引用 + 格式转换

这套架构的核心就三句话：

• 单一真实源：所有规则内容只在一个地方编写，即agents/rules/目录下的 Markdown 文件。
• 分层引用：规则按作用范围分层，全局规则、项目规则、子模块规则各自独立，再通过引用机制组装到各工具需要的文件里。
• 格式转换：用脚本把源头文件转换成CLAUDE.md、.cursor/rules/*.mdc、AGENTS.md等各工具要求的格式。

这个思路借鉴了软件工程里的 DRY（Don't Repeat Yourself）原则。规则本质上是“配置”，配置应该有唯一来源，而不是靠复制粘贴维护。

有人可能会问：为什么不直接统一用AGENTS.md？毕竟 OpenAI 在推这个标准，部分工具也开始支持。我的回答是：现状还远没到“一个文件走天下”的阶段。我用过的工具里，有的只认AGENTS.md，有的一直优先读CLAUDE.md，有的对.cursor/rules的 glob 匹配支持最好。指望全行业短期内统一不现实，更稳妥的做法是保留源头，各自适配。

2.2 规则内容怎么写才“跨端兼容”

架构搭好了，规则内容本身的写法也要调整。直接复用之前写给单个工具的文风，换一个端表现就会打折。

我总结了几条跨端兼容的内容编写原则：

• 目标导向，不写工具绑定指令。比如“用pnpm test跑测试”比“在终端执行 pnpm test 并将结果输出到上下文”更通用。前者是目标，后者是某个 CLI 工具特有的交互方式。
• 明确优先级和约束条件。规则之间如果存在冲突，要写明“当 A 与 B 冲突时，以 A 为准”。很多工具加载规则时是按文件顺序拼接的，优先级不写清楚，AI 就容易自相矛盾。
• 采用绝对的项目路径描述，而不是相对路径。比如规则里写“/api/users的接口定义在apps/api/src/routes/users.ts”，这样无论哪个端，只要项目根一致，AI 都能定位。
• 避免在规则里放大量内联示例。示例太长会挤占上下文窗口。更好的做法是让规则引用独立文档，比如“接口约定见docs/api-conventions.md”。
• 善用“禁止”语义，但要给出替代方案。比如“禁止重复封装 HTTP 请求，统一使用packages/shared/http.ts里的request()”。

这些原则看着简单，实际写的时候容易踩坑。我见过有人把整个项目的 API 文档都塞进规则文件，结果每次对话光规则就占了一两千 token，留给真正代码生成的上下文空间被严重压缩。规则要薄，细节靠引用。

2.3 分层目录设计：把规则拆成可组合的模块

我目前使用的规则目录结构长这样：

agents/ ├── rules/ │ ├── global/ │ │ ├── coding-style.md │ │ ├── commit-conventions.md │ │ └── security-practices.md │ ├── project/ │ │ ├── architecture.md │ │ ├── testing-strategy.md │ │ └── api-conventions.md │ ├── modules/ │ │ ├── frontend.md │ │ ├── backend.md │ │ └── shared-packages.md │ └── build/ │ └── generate.mjs ├── generated/ │ ├── CLAUDE.md │ ├── AGENTS.md │ ├── .cursor/ │ │ └── rules/ │ │ ├── global.mdc │ │ ├── project.mdc │ │ └── modules.mdc │ └── .github/ │ └── copilot-instructions.md

global/里的规则对任何项目都适用，属于“通用底线”；project/里的规则针对当前项目的特点；modules/按模块划分，只在该模块相关工作被触发时加载。

各工具最终读取的文件，全部由generate.mjs从rules/目录组装生成。手工不维护generated/下的任何文件，改内容只改rules/，然后跑一次脚本。

这套设计的直接收益是：规则的文件数量和内容总量都减少了，但每个端拿到的规则都是完整且最新的。想加一条“不允许直接用any”的约束，只需要改coding-style.md，然后重新生成一次，所有工具同步更新。

3. 实操落地：从零搭建一套可复用的规则体系

理论说完了，下面进入实操。我会从目录结构、生成脚本、内容样例、版本管理四个维度展开，完整还原我现在在项目里跑通的方案。

3.1 先定目录：规则仓库的四种组织风格

不是所有项目都适合把规则放在agents/下。我试过几种组织方式，各有适用场景。

• 单仓库集中式：规则放在当前仓库的agents/目录下。适合中小型项目，规则和代码绑定，跟随仓库一起走。
• 独立规则仓库：专门建一个agents-rules仓库，通过 git submodule 或 npm 包引入到各项目。适合大型组织，统一维护一套规则，被多个项目复用。
• 配置文件分离式：规则源头放在docs/agents/下，生成脚本放在scripts/下。适合对目录结构有强规范、不想在根目录新增顶层目录的团队。
• 原生格式优先式：如果团队只用一个工具（比如全员 Cursor），可以不引入生成脚本，直接写.cursor/rules/*.mdc作为源头。这种方式最轻，但牺牲了切换工具的灵活性。

我个人的推荐是：一开始就按“独立规则仓库”的方式组织，哪怕暂时只有一个项目在使用。因为规则一旦沉淀下来，跨项目复用的概率非常高。我自己就从单仓库方式迁移到了独立仓库方式，迁移成本比想象中低——无非是把agents/目录整个搬到新仓库，再在项目里引用。

3.2 生成脚本：一次编写，全端同步

生成脚本是整个架构的发动机。核心逻辑很简单：读取源头文件，按规则做格式转换，输出到对应位置。

我用 Node.js 写脚本，因为项目本身是前端栈，团队都熟悉 JS。如果你用 Python 栈，用 Python 写也是一样的思路。

先把源头文件定义成如下结构：

// generate.mjs import { readdir, readFile, mkdir, writeFile } from 'node:fs/promises' import path from 'node:path' import { fileURLToPath } from 'node:url' const __dirname = path.dirname(fileURLToPath(import.meta.url)) const rulesDir = path.join(__dirname, '..') const globalDir = path.join(rulesDir, 'global') const projectDir = path.join(rulesDir, 'project') const modulesDir = path.join(rulesDir, 'modules') async function loadRules(dir) { const files = (await readdir(dir)).filter((f) => f.endsWith('.md')).sort() const contents = await Promise.all( files.map(async (f) => { const raw = await readFile(path.join(dir, f), 'utf-8') return `## ${f.replace('.md', '')}\n\n${raw.trim()}` }) ) return contents.join('\n\n') } const [globalRules, projectRules, moduleRules] = await Promise.all([ loadRules(globalDir), loadRules(projectDir), loadRules(modulesDir), ])

这段代码做的事情很朴素：把每个目录下的所有 Markdown 文件读出来，按文件名排序，拼成带标题的文本块。排序很重要，因为规则顺序会影响 AI 的优先级判断，越靠前的规则优先级越高。我一般把“安全红线”和“强制规范”放在前面。

接下来按各工具的格式生成：

const generatedDir = path.join(rulesDir, 'generated') await mkdir(path.join(generatedDir, '.cursor', 'rules'), { recursive: true }) await mkdir(path.join(generatedDir, '.github'), { recursive: true }) // Claude Code: 一个 CLAUDE.md 包含全部规则，层级引用 const claudeMD = [ '# Project Agent Rules', '', '> 本文件由 agents/rules 自动生成，禁止手工编辑。', '> 修改源头：agents/rules/ 下的 Markdown 文件。', '', '## 全局规则', '', globalRules, '', '## 项目规则', '', projectRules, '', '## 模块规则', '', moduleRules, '', ].join('\n') await writeFile(path.join(generatedDir, 'CLAUDE.md'), claudeMD)

注意我在文件顶部写了一段“自动生成”的说明。这个小细节很重要，后面会展开说。

Cursor 的mdc格式略有不同，需要支持 frontmatter 形式的 metadata：

const cursorGlobal = `---\ndescription: 全局编码规范\n globs: **/*\n---\n\n${globalRules}` const cursorProject = `---\ndescription: 项目架构与测试策略\n globs: src/**/*\n---\n\n${projectRules}` await writeFile(path.join(generatedDir, '.cursor', 'rules', 'global.mdc'), cursorGlobal) await writeFile(path.join(generatedDir, '.cursor', 'rules', 'project.mdc'), cursorProject)

这里globs字段用来控制规则在哪些文件被操作时自动生效。**/*表示全局，src/**/*表示只处理src目录下的文件时加载。Cursor 的规则触发是基于 glob 匹配的，匹配越精确，AI 的上下文越干净。

最后生成 AGENTS.md 和 SQL 不用了，然后做一次完整性检查：

console.log('generated files:') const generatedFiles = await readdir(generatedDir, { recursive: true }) for (const file of generatedFiles) { const stats = await stat(path.join(generatedDir, file)) if (stats.isFile()) { console.log(` - ${file} (${stats.size} bytes)`) } }

跑一次node agents/rules/build/generate.mjs，就能看到各端规则文件全部更新。我把这个脚本挂在package.json的scripts里，命名成agents:sync，一条命令搞定全端同步。

3.3 规则内容样例：一份源头，三种表达

光有目录和脚本还不够，关键还得看规则怎么写。下面分享一个实际样例，展示同一份源头如何适配 CLI 工具和编辑器插件。

假设我们的global/security-practices.md写的是：

# 安全实践 - 禁止在代码中硬编码密钥、Token、数据库连接串，必须通过环境变量注入，并在 README 中说明需要配置的变量。 - 所有涉及用户输入的地方，必须做输入校验，不能直接信任前端传参。 - 依赖包禁止使用已知存在高危漏洞的版本，升级前先查变更日志。

生成到CLAUDE.md时，它作为整体文本直接拼入，Claude Code 会把它们当作全局指令读取。生成到.cursor/rules/global.mdc时，由于带globs: **/*，用户只要在编辑器里打开任意文件，Cursor 就会自动把这条规则注入会话上下文。

有趣的是，不同工具对“安全实践”这类约束的执行力度不同。Claude Code 对这类指令有较强的遵循倾向，只要不冲突，基本都会遵守；Cursor 依赖用户在对话里继续追问，所以规则写得越具体，效果越好。比如“必须通过环境变量注入”这种，如果在规则里不带“并在 README 中说明需要配置的变量”，Cursor 生成代码时可能只做了环境变量注入，但忘了补文档。加上了半句，它 Completer 的行为就明显不一样了。

所以我写规则时坚持一个原则：每条规则都要带上“做完这件事之后还要做什么”的补充说明。比如“升级依赖前先查变更日志”比“禁止使用有漏洞的依赖”更可执行。

3.4 版本管理与团队协作：让规则像代码一样走流程

规则文件也是代码，应该走版本管理。我在规则仓库里定义了几条团队协作规范，实践下来效果不错。

• 规则变更必须走 Pull Request，不能直接推到主分支。至少一人 review，确认规则变动不会影响已有代码逻辑。
• 每次变更，必须同时跑agents:sync，并且把generated/目录下的变更一起提交。这样其他人拉下来时，看到的是已经同步好的全端文件，而不是需要自己再跑一遍脚本的半成品。
• 规则文件头部写清“自动生成”标注。这样即使有人误改了generated/目录，下次跑脚本时冲突也会暴露出来，促使他回到源头修改。
• 接口如果发生变更，规则里的相关描述也应同步更新。比如 API 返回格式变了，api-conventions.md里的示例就要跟着改，否则 AI 生成的代码参考的是旧规范。

还有一个小技巧：在 CI 流程加一个检查任务，跑node agents/rules/build/generate.mjs，然后git diff --exit-code，如果发现生成的目录有变动，说明有人改了源头没跑同步脚本，CI 直接报错。这是我用过最有效的“规则同步检查”手段。

# .github/workflows/agents-rules-check.yml name: Check Agent Rules Sync on: pull_request: jobs: check: runs-on: ubuntu-latest steps: - uses: actions/checkout@v4 - uses: actions/setup-node@v4 with: node-version: '20' - run: node agents/rules/build/generate.mjs - run: git diff --exit-code agents/rules/generated/

这个流程跑起来之后，团队里再也没有出现过“有人改了规则但别人不知道”的情况。

4. 常见问题与排查技巧实录

这套架构我自己跑了半年多，也帮朋友团队搭过几次，过程中遇到了不少问题。挑几个典型的分享一下，都是文档里不会写的那种。

4.1 规则没生效？先查这四件事

规则文件生成了，AI 却不按规则执行，是最容易让人血压上升的场景。我的排查顺序是固定的：

• 文件是否放对了位置。快捷键、软链接、大小写不一致都可能导致文件路径识别失败。比如Cursor同时支持.cursor/rules和.cursor/rules.mdc两种位置，但它们的读取优先级不同，放错了就不生效。
• 文件名是否匹配工具要求。CLAUDE.md、AGENTS.md、GEMINI.md这些文件名是大小写敏感的，写成claude.md就不读。
• glob 规则是否过于严格。Cursor 里如果globs写得太窄，打开的文件匹配不上，规则就不会注入。我习惯将globs写成相对路径，比如src/**/*，必要时加一行**/*兜底。
• 输出里是否能看到规则内容。在对话中直接问 AI：“你当前的项目规则里，对 API 路由有什么要求？”它能复述出来，说明规则已注入；复述不出来，说明规则压根没进上下文。

大部分“规则不生效”的问题，都能在前两步解决。

4.2 上下文被规则吃掉了：优先级的取舍

规则文件一多，合并进上下文的内容也会膨胀。有一次我看到 Claude Code 的上下文占用里，整整 18% 全是规则文件的内容。规则写得再精确，占用了上下文窗口，留给真正的代码分析和生成的 token 就不够了。

解决思路是控制总规则体量，模块化按需加载。对支持按目录加载的工具（比如 Cursor），把模块规则拆细，不要一股脑全放全局规则里。对只能读一个文件无法按需加载的工具（比如部分 CLI），把非核心的内容用“引用”代替“内联”。比如规则里只写一句“接口约定见docs/api-conventions.md”，AI 需要时自己去读文件，比把整个文档塞进上下文高效得多。

我给自己定了一个红绿指标：generated/CLAUDE.md的体积控制在 3KB 以内，超过 5KB 就要考虑拆分或引用化。

4.3 多端行为还是不一致：差异可能来自模型，而不是规则

即使同一个项目、同一套规则，不同工具下的 AI 行为仍可能有细微差异。这种现象很容易让人误以为是规则没同步，其实根源在于各工具背后的模型版本和温度参数不同。

我遇到过的情况是：Cursor 里写代码，AI 会主动补充 JSDoc 注释；同样的代码在 Claude Code 里跑，AI 生成的注释明显少了很多。规则里明明写了“公共方法必须写 JSDoc”，但 Claude Code 的模型倾向于少写注释。

这类问题不全是规则体系的锅。规则能约束的是“该不该做”，如果模型的默认行为模式和规则期望差距较大，就要在规则里加强调程度。比如把“公共方法必须写 JSDoc”改成“任何导出成员，都必须有 JSDoc 注释，包含 @param 和 @returns”。规则描述越具体，模型遵循的确定性越高。

4.4 问题排查速查表

还有一个隐藏问题：规则文件里的中文和特殊符号。部分工具读取 Markdown 时对特殊字符处理存在兼容性问题。我遇到过 Cursor 的mdc文件里包含 emoji 时解析异常的案例，统一改成纯文本后就正常了。所以规则文件里我尽量不用 emoji、特殊符号和太多 Markdown 表格，保持纯文本为主，最多用列表。

5. 从“能用”到“好用”：规则质量的迭代方法

架构跑通之后，还有一个持续迭代的问题。规则体系不是一次写完就完事，它需要随着项目演进不断打磨。

5.1 建立规则评估反馈循环

我每个月会抽一个下午，做一次“规则质量复查”。方法是拿几个典型的开发任务——新增一个 CRUD 接口、重构一个模块、写一段新组件——分别让 AI 在配置了规则的环境下执行，再对照检查 AI 是否遵守了关键规则。哪些规则被稳定遵守，哪些时灵时不灵，哪些完全没被遵守，心里有数之后，再针对性调整规则的表达方式。

这个反馈循环很重要。没有评估就没有改进方向，规则会慢慢腐烂——内容过时、覆盖度不足、和项目实际脱节。

5.2 规则描述与项目演进的同步机制

规则最怕和项目脱节。项目做了架构调整，比如从 REST 换成 GraphQL，如果规则里还写着“新增 REST 路由必须校验参数”，AI 生成的代码就会和新的架构风格冲突。

我的做法是用文档驱动规则更新：项目里的架构决策记录（ADR）一旦更新，顺手检查是否有对应的规则文件需要修改。把“更新规则”放进架构变更的完成定义（Definition of Done）里，而不是事后想起再去补。

另外，新成员加入团队时，我也会让他们先通读一遍规则目录，读不懂的地方当场提问。他们的反馈往往能暴露规则里表述模糊的部分——写规则的人因为太熟悉项目，往往意识不到哪些地方写得不清楚。

这套统一 Agent Rules 架构不是银弹，但它确实帮我解决了多工具协作下规则失忆、提示词漂移、维护成本高等一堆实际问题。从一个单一源头生成所有端配置，配合 CI 检查强制同步，团队里关于“AI 为什么不听话”的抱怨明显少了。如果你也在同时用多个 AI 编程工具，值得照着这套思路试一遍。