1. 项目概述为什么你的 AI 项目需要一个清晰的规则管理策略最近在折腾各种 AI 辅助编程和智能体项目时我发现一个挺普遍的问题很多开发者包括早期的我自己都喜欢把所有的指令、约束、偏好一股脑地塞进一个叫CLAUDE.md的文件里。这个文件最初可能只是几行简单的说明但随着项目迭代、功能增加它很快会膨胀成一个臃肿不堪、逻辑混乱的“规则垃圾场”。当你想让 AI 处理不同的任务比如代码审查、文档生成、或者作为特定领域的智能体运行时这个庞然大物反而成了绊脚石导致 AI 理解偏差、输出不稳定甚至直接忽略关键指令。这个项目要探讨的就是如何为你的 AI 赋能项目无论是使用 Cursor、Claude Code、GitHub Copilot 还是自建的 AI Agent 框架设计一套清晰、可维护、可扩展的规则体系。核心思想是“职责分离”和“上下文精准投放”。我们不能再把项目规范、代码风格、安全规则、Agent 行为准则、MCP 服务器配置等所有东西都混在一个上下文窗口里。这就像把建筑规范、室内设计手册、物业管理条例和住户公约全订成一本厚书交给一个顾问他很难快速找到当前需要的信息。一个好的规则设计应该像一套模块化的工具箱。CLAUDE.md可以保留但它应该是项目的“宪法”或“总纲”只定义最核心、最通用的原则。而具体的“法律”和“操作手册”则应该分门别类放到如AGENTS.md、RULES/目录、技能描述文件等更专门的位置。这样当你召唤一个代码审查 AI 时只给它看代码规范和安全规则当你启动一个文档生成 Agent 时只注入文档模板和风格指南。这不仅大幅提升了 AI 的理解和执行效率也使得规则的维护和更新变得异常轻松。2. 核心设计思路从“一锅炖”到“模块化拼盘”2.1 识别规则的不同维度与使用场景在设计规则体系之前首先要对你项目中所有需要 AI 遵守的“规则”进行一次彻底的梳理和分类。根据我的经验这些规则通常可以划分为以下几个维度每个维度对应不同的使用场景和生效范围项目级通用规则这是所有 AI 交互的基石。包括项目的基本介绍、核心技术栈、代码仓库结构、通用的代码风格如命名规范、缩进、以及最重要的“绝对禁止”事项例如严禁引入某个已知有安全漏洞的库严禁向代码中插入任何形式的追踪或后门代码。这部分内容精简后适合放在根目录的CLAUDE.md或AI_CONTEXT.md中。AI 智能体行为规则当你的项目涉及运行特定的 AI Agent比如一个自动化的测试生成 Agent或一个用户支持聊天机器人时需要定义它的角色、目标、沟通风格以及行动边界。例如“你是一个专注于 Java 单元测试的助手应以 JUnit 5 为准优先考虑测试边界条件和异常流。” 这类高度定制化的描述应该放在agents/目录下的独立AGENTS.md文件或每个 Agent 的配置文件中。工具/技能调用规则如果你通过 MCPModel Context Protocol或其他方式为 AI 集成了外部工具如数据库查询、调用 API、执行 Shell 命令你需要定义这些工具的使用规范、权限和风险提示。例如“调用‘执行数据库迁移’技能前必须确认当前环境是测试库并输出将要执行的 SQL 语句供用户确认。” 这类规则通常伴随技能定义一起存放。领域/模块特定规则大型项目不同模块可能有特殊要求。前端 Vue 组件有它的 Props 和 Events 规范后端 API 接口有统一的响应体格式和错误码定义。这些规则不应该污染全局上下文而应该放在对应模块的目录中例如frontend/README.md或api/RULES.md。临时/会话级指令这是最灵活的一层在每次与 AI 对话时通过系统提示词或用户消息动态注入。例如“本次会话请专注于修复内存泄漏问题忽略代码格式调整。” 它是对上述持久化规则的有效补充。2.2 设计分层与引用架构基于以上分类我们可以设计一个清晰的分层架构。我的推荐结构如下your-project/ ├── CLAUDE.md # 项目宪法核心原则、通用禁令、项目概览 ├── agents/ # 智能体相关规则 │ ├── AGENTS.md # 智能体总览与通用行为准则 │ ├── code-reviewer.md # 代码审查智能体专属规则 │ └── doc-generator.md # 文档生成智能体专属规则 ├── rules/ # 结构化规则库 │ ├── coding-standards.md # 详细的代码规范 │ ├── security-rules.md # 安全开发规范 │ ├── commit-convention.md # Git 提交规范 │ └── api-guidelines.md # API 设计指南 ├── skills/ # MCP 技能定义可选 │ └── database.mcp.json # 技能描述文件内含使用规则 └── frontend/ # 领域特定规则 └── VUE_RULES.md # Vue 项目特定规范这个架构的核心优势在于“按需加载”。当你在 Cursor 中打开一个后端 Java 文件时你的 AI 助手上下文可以自动或手动关联CLAUDE.md、rules/coding-standards.md和rules/security-rules.md而完全不需要加载前端的 Vue 规则。这极大地节约了宝贵的上下文令牌并提高了指令的针对性。实操心得上下文窗口是稀缺资源无论 Claude 100K 还是 GPT-4 128K上下文窗口都不是无限的。将无关规则塞进去不仅浪费令牌更会稀释关键指令的权重导致 AI“失焦”。我曾在一个项目中因为CLAUDE.md里塞了太多前端细节导致 AI 在写 Python 脚本时反复询问 React 组件的状态管理令人啼笑皆非。分层设计就是解决这个问题的钥匙。2.3 规则文件的语法与格式最佳实践规则文件不是文学创作它的核心是让 AI 清晰、无歧义地理解。以下是一些被验证有效的格式建议使用清晰的标题和层级用#、##、###组织内容。AI 对文档结构有很好的理解能力。多用列表少用长段落将规则条目化。使用-或1.列举具体要求比埋在段落里更容易被识别和遵循。## 代码风格 - **命名**变量使用 camelCase类名使用 PascalCase常量使用 UPPER_SNAKE_CASE。 - **缩进**统一使用 2 个空格禁止使用 Tab。 - **行宽**最大 120 个字符。使用关键词强调用加粗表示非常重要的概念或禁止项用代码字体表示具体的命令、代码或文件名。- **绝对禁止**在未经验证的情况下使用 eval() 函数或反序列化用户输入。 - 所有 API 响应必须包裹在标准格式中参见 utils/response.py 中的 StandardResponse 类。提供正面和反面例子这是最有效的方法之一。明确告诉 AI“什么是好的什么是不好的”。### 函数注释规范良好示例 python def calculate_price(quantity: int, unit_price: float) - float: \\\ 计算商品总价。 Args: quantity: 商品数量必须为正整数。 unit_price: 商品单价必须为非负浮点数。 Returns: 商品总价浮点数。 \\\ return quantity * unit_price应避免的写法反面示例def calc(q, up): # 命名不清晰无类型提示无文档 return q * up定义清晰的角色和边界在AGENTS.md中开篇就明确定义。# 代码审查智能体 - CodeGuard **角色**你是项目 CodeGuard一个严格、细致、专注于代码质量和安全性的审查员。 **核心目标**发现代码中的潜在 bug、安全漏洞、性能问题以及违反项目规范的写法。 **工作流程** 1. 首先检查代码是否满足基本规范命名、格式。 2. 其次分析逻辑正确性和异常处理。 3. 最后评估安全性和潜在性能影响。 **输出格式**使用 Markdown 表格列明问题级别、位置、描述和建议修复。3. 关键组件详解与实现方案3.1 CLAUDE.md 的精简与重构CLAUDE.md应该瘦身成为一份“元规则”文件。它的核心内容应包括项目简介一两句话说明项目是做什么的。核心技术栈列出主要语言、框架、数据库。例如Python 3.11, FastAPI, PostgreSQL, Redis。核心开发原则3-5 条最高级别的指导方针。例如“优先考虑代码可读性”、“所有外部数据输入必须验证”、“错误处理要明确且提供有用信息”。绝对禁令用最醒目的方式列出绝对不能做的事情。这是安全底线。规则索引与引用这是最关键的一步——不再展开具体规则而是告诉 AI 去哪里找。## 详细规则索引 本项目遵循模块化规则管理。请根据当前任务上下文参考以下相关文件 - **通用编码规范**请参阅 ./rules/coding-standards.md - **安全开发要求**请参阅 ./rules/security-rules.md - **Git 提交规范**请参阅 ./rules/commit-convention.md - **前端开发 (Vue 3)**请参阅 ./frontend/VUE_RULES.md - **智能体行为准则**请参阅 ./agents/AGENTS.md如何更新本文件简要说明修改此文件的流程防止被随意更改。这样CLAUDE.md就从一个臃肿的规则集变成了一个轻量级的目录和调度中心。3.2 AGENTS.md 与智能体专属规则的编写AGENTS.md是智能体的“入职培训手册”。它应该为每个智能体定义清晰的“人设”和“工作流”。一个优秀的AGENTS.md结构# 项目智能体总览 本文档定义了在本项目中活跃的各类 AI 智能体的角色、职责和行为规范。 ## 通用智能体守则 - 所有智能体必须遵守 ../CLAUDE.md 中定义的**绝对禁令**。 - 与用户交互时应保持专业、友善、乐于助人的态度。 - 如果对任务要求不明确应主动询问澄清而非猜测执行。 ## 智能体目录 ### 1. CodeReviewer - 代码审查专家 **定位**专注于静态代码分析提升代码质量。 **触发场景**当用户提交 Pull Request 或主动要求进行代码审查时。 **核心规则** - 审查范围语法错误、潜在 bug、代码风格违规、安全漏洞、性能问题。 - 审查依据优先依据 ../rules/coding-standards.md 和 ../rules/security-rules.md。 - 输出要求发现的问题必须按 **严重、警告、建议** 三级分类并给出具体的代码行号和修改建议。 - **禁止行为**不得直接修改代码仅提供评论和建议。 ### 2. DocGenius - 文档生成助手 **定位**根据代码和注释自动生成或更新项目文档。 **触发场景**当代码中新增模块、函数或用户要求更新 API 文档时。 **核心规则** - 输入分析指定的源代码文件、函数注释和类型提示。 - 输出生成符合 ../rules/api-guidelines.md 中定义的 API 文档格式如 OpenAPI Spec。 - 风格文档语言需简洁、准确面向开发者。 - **特殊指令**对于复杂逻辑可以建议在文档中添加流程图或序列图使用 Mermaid 语法描述。你可以为每个智能体创建单独的文件如agents/code-reviewer.md然后在AGENTS.md中引用。这样结构更清晰。3.3 结构化规则库rules/的构建rules/目录是你规则体系的“法律条文库”。每个文件应聚焦一个特定领域。以rules/security-rules.md为例# 安全开发规范 ## 1. 数据验证与消毒 **原则**所有来自外部的数据用户输入、API 响应、文件内容都不可信必须经过验证和消毒。 - **SQL 操作**必须使用参数化查询或 ORM 提供的方法**严禁**使用字符串拼接生成 SQL。 - 正面示例Python with SQLAlchemysession.query(User).filter(User.id user_id) - 反面示例fSELECT * FROM users WHERE id {user_id} // **严禁** - **命令执行**避免将用户输入直接传递给 os.system、subprocess.run 等。如必须需对输入进行严格的白名单过滤。 - **反序列化**对 JSON、YAML 等数据的反序列化需在可信环境进行并对结果进行类型检查。 ## 2. 依赖管理 - 所有引入的第三方库必须经过审查优先选择活跃维护、知名度高的项目。 - 定期运行 npm audit、pip-audit 或 snyk 等工具检查已知漏洞。 - **禁止**引入来源不明或文档极少的库。 ## 3. 敏感信息处理 - **绝对禁止**将密码、API Keys、私钥等硬编码在源代码中。 - 必须使用环境变量或安全的配置管理服务如 Vault。 - 配置文件示例.env.example中只能包含占位符真实值必须在 .env已加入 .gitignore中设置。注意事项规则的优先级与冲突解决当规则之间可能存在冲突时比如一个规则要求性能优先而另一个要求可读性优先必须在文件中明确说明优先级。通常的惯例是安全规则 功能正确性规则 性能规则 代码风格规则。可以在CLAUDE.md或每个规则文件的顶部进行声明。3.4 与开发工具链的集成设计好的规则需要融入开发流程才能发挥作用。IDE/编辑器集成Cursor / VSCode在项目设置中可以指定项目级的 AI 上下文文件。你可以配置为默认加载CLAUDE.md。当打开特定类型文件时通过插件或脚本动态注入相关规则例如打开.vue文件时自动将frontend/VUE_RULES.md加入会话上下文。JetBrains IDE可以通过自定义文件模板或插件在创建新文件时自动插入符合规则的注释头。版本控制钩子利用 Gitpre-commit钩子运行脚本检查代码是否违反rules/coding-standards.md中的关键规则例如使用grep检查是否含有禁止的函数调用。这可以将 AI 辅助编程和自动化检查结合起来形成双重保障。CI/CD 管道在持续集成中可以加入一个检查步骤使用简单的脚本或 NLP 工具成本较高来分析 AI 生成的代码注释、提交信息看是否符合rules/commit-convention.md和文档规范。这更多是作为一种事后审计和团队规范培养的手段。4. 维护、迭代与团队协作策略4.1 规则的版本化与变更管理规则不是一成不变的。随着项目发展、技术栈更新、团队认知统一规则需要迭代。将规则文件纳入版本控制CLAUDE.md、rules/、agents/都应该在 Git 管理之下。任何修改都有迹可循。关联规则与 Issue/PR当需要修改或新增一条规则时应该创建一个 Issue 进行讨论说明修改原因、背景和预期影响。通过 Pull Request 来实施修改并邀请团队成员进行评审。这确保了规则变更的透明度和共识。添加版本或修订历史在重要规则文件的末尾可以维护一个简单的Changelog记录重大变更。## 修订历史 - **2024-05-20**新增“关于使用 AI 生成代码的版权与注释声明要求”。 - **2024-04-15**更新 Python 代码规范将行宽从 80 字符调整为 120 字符。 - **2024-03-01**首次创建本安全规范文档。4.2 新成员上手与规则教育一套复杂的规则体系如果只有你一个人知道那就失去了意义。如何让新加入的团队成员包括人类和未来新配置的 AI Agent快速上手编写一份简明的ONBOARDING.md这份文档告诉新人项目如何使用 AI 辅助以及最重要的规则在哪里。可以把它放在项目根目录。# AI 辅助开发入门指南 欢迎本项目深度集成了 AI 助手如 Cursor、Copilot来提升开发效率。为了保持代码质量和一致性请务必了解以下规则 1. **起点**请先阅读 CLAUDE.md了解项目核心原则和禁令。 2. **编码时**请确保你的 AI 助手上下文包含了 rules/coding-standards.md。 3. **提交代码前**请运行 scripts/pre-commit-check.sh 进行基础规则校验。 4. **创建新智能体**请参考 agents/AGENTS.md 的模板和规范。定期进行规则回顾在团队周会或迭代回顾会上可以花 10 分钟讨论一条规则的实际应用案例或者对某条有争议的规则进行修订。这能保持规则的生命力和团队的认同感。4.3 衡量规则的有效性与优化如何知道你的规则设计是有效的可以从以下几个维度观察AI 输出的一致性不同的团队成员或同一团队成员在不同时间让 AI 执行相似任务时产生的代码风格、解决方案是否趋于一致如果差异很大可能相关规则不够明确或未被有效加载。问题发现率代码审查中由 AI 智能体CodeReviewer发现的、且被人类开发者认可的真实问题比例是否在提高误报率是否在下降这反映了规则描述的准确性。上下文使用效率通过监控或估算AI 在处理任务时用于理解规则和背景的令牌数占比是否合理一个臃肿的CLAUDE.md会导致这个比例畸高。团队满意度通过简单的问卷或口头询问了解团队成员是否觉得现有的 AI 规则有助于提升效率而不是制造障碍。基于这些反馈持续地优化你的规则文件合并重复条目拆分过于复杂的章节补充缺失的示例修正模糊的描述。5. 常见问题与实战排坑记录在实际推行这套规则体系的过程中我踩过不少坑也总结出一些常见问题的解法。5.1 问题AI 似乎忽略了我某个规则文件里的指令排查思路 1上下文是否包含这是最常见的原因。确认你当前的 AI 会话或智能体配置中是否确实加载了该规则文件。在 Cursor 中你可以检查“项目设置”里的上下文文件列表。排查思路 2规则描述是否模糊AI 不擅长理解模糊的、充满“应该”、“最好”等词汇的指令。将“你应该写出高质量的代码”改为“函数长度不应超过 50 行必须包含文档字符串并使用类型注解”。排查思路 3规则冲突检查其他已加载的规则文件是否存在与之矛盾的指令。AI 可能会感到困惑并选择忽略其中一部分。确保规则优先级清晰。解决方案在规则文件的开头使用非常明确的指令如“在处理任何与用户输入相关的操作前你必须首先阅读并严格遵守本文件security-rules.md的所有条目。”5.2 问题规则文件太多管理起来麻烦解决方案建立“核心-扩展”结构。将最通用、最稳定的规则放在CLAUDE.md和rules/核心文件中。将为特定子项目、实验性功能或临时需求制定的规则放在experimental/或legacy/目录下并通过注释说明其适用范围和有效期。定期如每季度回顾和清理这些扩展规则。5.3 问题如何为不同的 AI 模型Claude, GPT, 本地模型适配规则实战心得不同模型对指令的敏感度和理解能力有差异。一个通用的策略是编写“模型无关”的核心规则专注于描述“要做什么”和“不要做什么”使用清晰的结构和示例。在CLAUDE.md顶部添加“模型适配说明”这是一个小技巧。你可以写# 模型特定提示 - **对于 Claude 系列模型**你非常擅长遵循结构化指令请特别注意本文件中的列表和代码示例。 - **对于 GPT 系列模型**你具有较强的推理能力如果规则未涵盖请基于核心原则进行合理推断并在输出中说明你的推理过程。 - **对于本地 CodeLLaMA 等模型**你的上下文长度有限请优先关注标记为 **绝对禁止** 和 **重要** 的条目。进行小规模测试在将新规则应用于整个项目前创建一个测试文件或分支用不同的模型执行几个标准任务如“修复这个函数的错误”、“为这个类添加注释”观察输出是否符合预期据此微调规则表述。5.4 问题动态规则如根据当前分支名决定行为如何实现高级技巧这需要结合外部脚本。例如你可以编写一个prepare_context.py脚本它运行在 AI 会话开始前。脚本读取当前 Git 分支名。如果分支名包含feat/则自动将frontend/VUE_RULES.md的内容拼接到本次要发送的上下文里。如果分支名包含hotfix-则额外注入一条临时指令“本次修改范围应严格局限于修复问题避免重构。”然后将最终生成的上下文发送给 AI。这可以实现非常精细化的规则调度但对工具链的集成度要求较高。最后我想分享一点个人体会设计 AI 项目规则本质上是在为你的“数字员工”编写清晰的工作手册和流程规范。初期投入时间进行良好的设计看似增加了开销实则是在为项目的长期质量、团队协作效率和 AI 辅助的确定性进行投资。一个好的规则体系能让 AI 从一名偶尔发挥超常但也经常闯祸的“实习生”成长为一名可靠、稳定、可预测的“资深工程师”。别再让CLAUDE.md独自承受一切了是时候为你的项目打造一个专业、有序的规则生态系统了。 AI项目规则管理：从CLAUDE.md臃肿到模块化架构设计
1. 项目概述为什么你的 AI 项目需要一个清晰的规则管理策略最近在折腾各种 AI 辅助编程和智能体项目时我发现一个挺普遍的问题很多开发者包括早期的我自己都喜欢把所有的指令、约束、偏好一股脑地塞进一个叫CLAUDE.md的文件里。这个文件最初可能只是几行简单的说明但随着项目迭代、功能增加它很快会膨胀成一个臃肿不堪、逻辑混乱的“规则垃圾场”。当你想让 AI 处理不同的任务比如代码审查、文档生成、或者作为特定领域的智能体运行时这个庞然大物反而成了绊脚石导致 AI 理解偏差、输出不稳定甚至直接忽略关键指令。这个项目要探讨的就是如何为你的 AI 赋能项目无论是使用 Cursor、Claude Code、GitHub Copilot 还是自建的 AI Agent 框架设计一套清晰、可维护、可扩展的规则体系。核心思想是“职责分离”和“上下文精准投放”。我们不能再把项目规范、代码风格、安全规则、Agent 行为准则、MCP 服务器配置等所有东西都混在一个上下文窗口里。这就像把建筑规范、室内设计手册、物业管理条例和住户公约全订成一本厚书交给一个顾问他很难快速找到当前需要的信息。一个好的规则设计应该像一套模块化的工具箱。CLAUDE.md可以保留但它应该是项目的“宪法”或“总纲”只定义最核心、最通用的原则。而具体的“法律”和“操作手册”则应该分门别类放到如AGENTS.md、RULES/目录、技能描述文件等更专门的位置。这样当你召唤一个代码审查 AI 时只给它看代码规范和安全规则当你启动一个文档生成 Agent 时只注入文档模板和风格指南。这不仅大幅提升了 AI 的理解和执行效率也使得规则的维护和更新变得异常轻松。2. 核心设计思路从“一锅炖”到“模块化拼盘”2.1 识别规则的不同维度与使用场景在设计规则体系之前首先要对你项目中所有需要 AI 遵守的“规则”进行一次彻底的梳理和分类。根据我的经验这些规则通常可以划分为以下几个维度每个维度对应不同的使用场景和生效范围项目级通用规则这是所有 AI 交互的基石。包括项目的基本介绍、核心技术栈、代码仓库结构、通用的代码风格如命名规范、缩进、以及最重要的“绝对禁止”事项例如严禁引入某个已知有安全漏洞的库严禁向代码中插入任何形式的追踪或后门代码。这部分内容精简后适合放在根目录的CLAUDE.md或AI_CONTEXT.md中。AI 智能体行为规则当你的项目涉及运行特定的 AI Agent比如一个自动化的测试生成 Agent或一个用户支持聊天机器人时需要定义它的角色、目标、沟通风格以及行动边界。例如“你是一个专注于 Java 单元测试的助手应以 JUnit 5 为准优先考虑测试边界条件和异常流。” 这类高度定制化的描述应该放在agents/目录下的独立AGENTS.md文件或每个 Agent 的配置文件中。工具/技能调用规则如果你通过 MCPModel Context Protocol或其他方式为 AI 集成了外部工具如数据库查询、调用 API、执行 Shell 命令你需要定义这些工具的使用规范、权限和风险提示。例如“调用‘执行数据库迁移’技能前必须确认当前环境是测试库并输出将要执行的 SQL 语句供用户确认。” 这类规则通常伴随技能定义一起存放。领域/模块特定规则大型项目不同模块可能有特殊要求。前端 Vue 组件有它的 Props 和 Events 规范后端 API 接口有统一的响应体格式和错误码定义。这些规则不应该污染全局上下文而应该放在对应模块的目录中例如frontend/README.md或api/RULES.md。临时/会话级指令这是最灵活的一层在每次与 AI 对话时通过系统提示词或用户消息动态注入。例如“本次会话请专注于修复内存泄漏问题忽略代码格式调整。” 它是对上述持久化规则的有效补充。2.2 设计分层与引用架构基于以上分类我们可以设计一个清晰的分层架构。我的推荐结构如下your-project/ ├── CLAUDE.md # 项目宪法核心原则、通用禁令、项目概览 ├── agents/ # 智能体相关规则 │ ├── AGENTS.md # 智能体总览与通用行为准则 │ ├── code-reviewer.md # 代码审查智能体专属规则 │ └── doc-generator.md # 文档生成智能体专属规则 ├── rules/ # 结构化规则库 │ ├── coding-standards.md # 详细的代码规范 │ ├── security-rules.md # 安全开发规范 │ ├── commit-convention.md # Git 提交规范 │ └── api-guidelines.md # API 设计指南 ├── skills/ # MCP 技能定义可选 │ └── database.mcp.json # 技能描述文件内含使用规则 └── frontend/ # 领域特定规则 └── VUE_RULES.md # Vue 项目特定规范这个架构的核心优势在于“按需加载”。当你在 Cursor 中打开一个后端 Java 文件时你的 AI 助手上下文可以自动或手动关联CLAUDE.md、rules/coding-standards.md和rules/security-rules.md而完全不需要加载前端的 Vue 规则。这极大地节约了宝贵的上下文令牌并提高了指令的针对性。实操心得上下文窗口是稀缺资源无论 Claude 100K 还是 GPT-4 128K上下文窗口都不是无限的。将无关规则塞进去不仅浪费令牌更会稀释关键指令的权重导致 AI“失焦”。我曾在一个项目中因为CLAUDE.md里塞了太多前端细节导致 AI 在写 Python 脚本时反复询问 React 组件的状态管理令人啼笑皆非。分层设计就是解决这个问题的钥匙。2.3 规则文件的语法与格式最佳实践规则文件不是文学创作它的核心是让 AI 清晰、无歧义地理解。以下是一些被验证有效的格式建议使用清晰的标题和层级用#、##、###组织内容。AI 对文档结构有很好的理解能力。多用列表少用长段落将规则条目化。使用-或1.列举具体要求比埋在段落里更容易被识别和遵循。## 代码风格 - **命名**变量使用 camelCase类名使用 PascalCase常量使用 UPPER_SNAKE_CASE。 - **缩进**统一使用 2 个空格禁止使用 Tab。 - **行宽**最大 120 个字符。使用关键词强调用加粗表示非常重要的概念或禁止项用代码字体表示具体的命令、代码或文件名。- **绝对禁止**在未经验证的情况下使用 eval() 函数或反序列化用户输入。 - 所有 API 响应必须包裹在标准格式中参见 utils/response.py 中的 StandardResponse 类。提供正面和反面例子这是最有效的方法之一。明确告诉 AI“什么是好的什么是不好的”。### 函数注释规范良好示例 python def calculate_price(quantity: int, unit_price: float) - float: \\\ 计算商品总价。 Args: quantity: 商品数量必须为正整数。 unit_price: 商品单价必须为非负浮点数。 Returns: 商品总价浮点数。 \\\ return quantity * unit_price应避免的写法反面示例def calc(q, up): # 命名不清晰无类型提示无文档 return q * up定义清晰的角色和边界在AGENTS.md中开篇就明确定义。# 代码审查智能体 - CodeGuard **角色**你是项目 CodeGuard一个严格、细致、专注于代码质量和安全性的审查员。 **核心目标**发现代码中的潜在 bug、安全漏洞、性能问题以及违反项目规范的写法。 **工作流程** 1. 首先检查代码是否满足基本规范命名、格式。 2. 其次分析逻辑正确性和异常处理。 3. 最后评估安全性和潜在性能影响。 **输出格式**使用 Markdown 表格列明问题级别、位置、描述和建议修复。3. 关键组件详解与实现方案3.1 CLAUDE.md 的精简与重构CLAUDE.md应该瘦身成为一份“元规则”文件。它的核心内容应包括项目简介一两句话说明项目是做什么的。核心技术栈列出主要语言、框架、数据库。例如Python 3.11, FastAPI, PostgreSQL, Redis。核心开发原则3-5 条最高级别的指导方针。例如“优先考虑代码可读性”、“所有外部数据输入必须验证”、“错误处理要明确且提供有用信息”。绝对禁令用最醒目的方式列出绝对不能做的事情。这是安全底线。规则索引与引用这是最关键的一步——不再展开具体规则而是告诉 AI 去哪里找。## 详细规则索引 本项目遵循模块化规则管理。请根据当前任务上下文参考以下相关文件 - **通用编码规范**请参阅 ./rules/coding-standards.md - **安全开发要求**请参阅 ./rules/security-rules.md - **Git 提交规范**请参阅 ./rules/commit-convention.md - **前端开发 (Vue 3)**请参阅 ./frontend/VUE_RULES.md - **智能体行为准则**请参阅 ./agents/AGENTS.md如何更新本文件简要说明修改此文件的流程防止被随意更改。这样CLAUDE.md就从一个臃肿的规则集变成了一个轻量级的目录和调度中心。3.2 AGENTS.md 与智能体专属规则的编写AGENTS.md是智能体的“入职培训手册”。它应该为每个智能体定义清晰的“人设”和“工作流”。一个优秀的AGENTS.md结构# 项目智能体总览 本文档定义了在本项目中活跃的各类 AI 智能体的角色、职责和行为规范。 ## 通用智能体守则 - 所有智能体必须遵守 ../CLAUDE.md 中定义的**绝对禁令**。 - 与用户交互时应保持专业、友善、乐于助人的态度。 - 如果对任务要求不明确应主动询问澄清而非猜测执行。 ## 智能体目录 ### 1. CodeReviewer - 代码审查专家 **定位**专注于静态代码分析提升代码质量。 **触发场景**当用户提交 Pull Request 或主动要求进行代码审查时。 **核心规则** - 审查范围语法错误、潜在 bug、代码风格违规、安全漏洞、性能问题。 - 审查依据优先依据 ../rules/coding-standards.md 和 ../rules/security-rules.md。 - 输出要求发现的问题必须按 **严重、警告、建议** 三级分类并给出具体的代码行号和修改建议。 - **禁止行为**不得直接修改代码仅提供评论和建议。 ### 2. DocGenius - 文档生成助手 **定位**根据代码和注释自动生成或更新项目文档。 **触发场景**当代码中新增模块、函数或用户要求更新 API 文档时。 **核心规则** - 输入分析指定的源代码文件、函数注释和类型提示。 - 输出生成符合 ../rules/api-guidelines.md 中定义的 API 文档格式如 OpenAPI Spec。 - 风格文档语言需简洁、准确面向开发者。 - **特殊指令**对于复杂逻辑可以建议在文档中添加流程图或序列图使用 Mermaid 语法描述。你可以为每个智能体创建单独的文件如agents/code-reviewer.md然后在AGENTS.md中引用。这样结构更清晰。3.3 结构化规则库rules/的构建rules/目录是你规则体系的“法律条文库”。每个文件应聚焦一个特定领域。以rules/security-rules.md为例# 安全开发规范 ## 1. 数据验证与消毒 **原则**所有来自外部的数据用户输入、API 响应、文件内容都不可信必须经过验证和消毒。 - **SQL 操作**必须使用参数化查询或 ORM 提供的方法**严禁**使用字符串拼接生成 SQL。 - 正面示例Python with SQLAlchemysession.query(User).filter(User.id user_id) - 反面示例fSELECT * FROM users WHERE id {user_id} // **严禁** - **命令执行**避免将用户输入直接传递给 os.system、subprocess.run 等。如必须需对输入进行严格的白名单过滤。 - **反序列化**对 JSON、YAML 等数据的反序列化需在可信环境进行并对结果进行类型检查。 ## 2. 依赖管理 - 所有引入的第三方库必须经过审查优先选择活跃维护、知名度高的项目。 - 定期运行 npm audit、pip-audit 或 snyk 等工具检查已知漏洞。 - **禁止**引入来源不明或文档极少的库。 ## 3. 敏感信息处理 - **绝对禁止**将密码、API Keys、私钥等硬编码在源代码中。 - 必须使用环境变量或安全的配置管理服务如 Vault。 - 配置文件示例.env.example中只能包含占位符真实值必须在 .env已加入 .gitignore中设置。注意事项规则的优先级与冲突解决当规则之间可能存在冲突时比如一个规则要求性能优先而另一个要求可读性优先必须在文件中明确说明优先级。通常的惯例是安全规则 功能正确性规则 性能规则 代码风格规则。可以在CLAUDE.md或每个规则文件的顶部进行声明。3.4 与开发工具链的集成设计好的规则需要融入开发流程才能发挥作用。IDE/编辑器集成Cursor / VSCode在项目设置中可以指定项目级的 AI 上下文文件。你可以配置为默认加载CLAUDE.md。当打开特定类型文件时通过插件或脚本动态注入相关规则例如打开.vue文件时自动将frontend/VUE_RULES.md加入会话上下文。JetBrains IDE可以通过自定义文件模板或插件在创建新文件时自动插入符合规则的注释头。版本控制钩子利用 Gitpre-commit钩子运行脚本检查代码是否违反rules/coding-standards.md中的关键规则例如使用grep检查是否含有禁止的函数调用。这可以将 AI 辅助编程和自动化检查结合起来形成双重保障。CI/CD 管道在持续集成中可以加入一个检查步骤使用简单的脚本或 NLP 工具成本较高来分析 AI 生成的代码注释、提交信息看是否符合rules/commit-convention.md和文档规范。这更多是作为一种事后审计和团队规范培养的手段。4. 维护、迭代与团队协作策略4.1 规则的版本化与变更管理规则不是一成不变的。随着项目发展、技术栈更新、团队认知统一规则需要迭代。将规则文件纳入版本控制CLAUDE.md、rules/、agents/都应该在 Git 管理之下。任何修改都有迹可循。关联规则与 Issue/PR当需要修改或新增一条规则时应该创建一个 Issue 进行讨论说明修改原因、背景和预期影响。通过 Pull Request 来实施修改并邀请团队成员进行评审。这确保了规则变更的透明度和共识。添加版本或修订历史在重要规则文件的末尾可以维护一个简单的Changelog记录重大变更。## 修订历史 - **2024-05-20**新增“关于使用 AI 生成代码的版权与注释声明要求”。 - **2024-04-15**更新 Python 代码规范将行宽从 80 字符调整为 120 字符。 - **2024-03-01**首次创建本安全规范文档。4.2 新成员上手与规则教育一套复杂的规则体系如果只有你一个人知道那就失去了意义。如何让新加入的团队成员包括人类和未来新配置的 AI Agent快速上手编写一份简明的ONBOARDING.md这份文档告诉新人项目如何使用 AI 辅助以及最重要的规则在哪里。可以把它放在项目根目录。# AI 辅助开发入门指南 欢迎本项目深度集成了 AI 助手如 Cursor、Copilot来提升开发效率。为了保持代码质量和一致性请务必了解以下规则 1. **起点**请先阅读 CLAUDE.md了解项目核心原则和禁令。 2. **编码时**请确保你的 AI 助手上下文包含了 rules/coding-standards.md。 3. **提交代码前**请运行 scripts/pre-commit-check.sh 进行基础规则校验。 4. **创建新智能体**请参考 agents/AGENTS.md 的模板和规范。定期进行规则回顾在团队周会或迭代回顾会上可以花 10 分钟讨论一条规则的实际应用案例或者对某条有争议的规则进行修订。这能保持规则的生命力和团队的认同感。4.3 衡量规则的有效性与优化如何知道你的规则设计是有效的可以从以下几个维度观察AI 输出的一致性不同的团队成员或同一团队成员在不同时间让 AI 执行相似任务时产生的代码风格、解决方案是否趋于一致如果差异很大可能相关规则不够明确或未被有效加载。问题发现率代码审查中由 AI 智能体CodeReviewer发现的、且被人类开发者认可的真实问题比例是否在提高误报率是否在下降这反映了规则描述的准确性。上下文使用效率通过监控或估算AI 在处理任务时用于理解规则和背景的令牌数占比是否合理一个臃肿的CLAUDE.md会导致这个比例畸高。团队满意度通过简单的问卷或口头询问了解团队成员是否觉得现有的 AI 规则有助于提升效率而不是制造障碍。基于这些反馈持续地优化你的规则文件合并重复条目拆分过于复杂的章节补充缺失的示例修正模糊的描述。5. 常见问题与实战排坑记录在实际推行这套规则体系的过程中我踩过不少坑也总结出一些常见问题的解法。5.1 问题AI 似乎忽略了我某个规则文件里的指令排查思路 1上下文是否包含这是最常见的原因。确认你当前的 AI 会话或智能体配置中是否确实加载了该规则文件。在 Cursor 中你可以检查“项目设置”里的上下文文件列表。排查思路 2规则描述是否模糊AI 不擅长理解模糊的、充满“应该”、“最好”等词汇的指令。将“你应该写出高质量的代码”改为“函数长度不应超过 50 行必须包含文档字符串并使用类型注解”。排查思路 3规则冲突检查其他已加载的规则文件是否存在与之矛盾的指令。AI 可能会感到困惑并选择忽略其中一部分。确保规则优先级清晰。解决方案在规则文件的开头使用非常明确的指令如“在处理任何与用户输入相关的操作前你必须首先阅读并严格遵守本文件security-rules.md的所有条目。”5.2 问题规则文件太多管理起来麻烦解决方案建立“核心-扩展”结构。将最通用、最稳定的规则放在CLAUDE.md和rules/核心文件中。将为特定子项目、实验性功能或临时需求制定的规则放在experimental/或legacy/目录下并通过注释说明其适用范围和有效期。定期如每季度回顾和清理这些扩展规则。5.3 问题如何为不同的 AI 模型Claude, GPT, 本地模型适配规则实战心得不同模型对指令的敏感度和理解能力有差异。一个通用的策略是编写“模型无关”的核心规则专注于描述“要做什么”和“不要做什么”使用清晰的结构和示例。在CLAUDE.md顶部添加“模型适配说明”这是一个小技巧。你可以写# 模型特定提示 - **对于 Claude 系列模型**你非常擅长遵循结构化指令请特别注意本文件中的列表和代码示例。 - **对于 GPT 系列模型**你具有较强的推理能力如果规则未涵盖请基于核心原则进行合理推断并在输出中说明你的推理过程。 - **对于本地 CodeLLaMA 等模型**你的上下文长度有限请优先关注标记为 **绝对禁止** 和 **重要** 的条目。进行小规模测试在将新规则应用于整个项目前创建一个测试文件或分支用不同的模型执行几个标准任务如“修复这个函数的错误”、“为这个类添加注释”观察输出是否符合预期据此微调规则表述。5.4 问题动态规则如根据当前分支名决定行为如何实现高级技巧这需要结合外部脚本。例如你可以编写一个prepare_context.py脚本它运行在 AI 会话开始前。脚本读取当前 Git 分支名。如果分支名包含feat/则自动将frontend/VUE_RULES.md的内容拼接到本次要发送的上下文里。如果分支名包含hotfix-则额外注入一条临时指令“本次修改范围应严格局限于修复问题避免重构。”然后将最终生成的上下文发送给 AI。这可以实现非常精细化的规则调度但对工具链的集成度要求较高。最后我想分享一点个人体会设计 AI 项目规则本质上是在为你的“数字员工”编写清晰的工作手册和流程规范。初期投入时间进行良好的设计看似增加了开销实则是在为项目的长期质量、团队协作效率和 AI 辅助的确定性进行投资。一个好的规则体系能让 AI 从一名偶尔发挥超常但也经常闯祸的“实习生”成长为一名可靠、稳定、可预测的“资深工程师”。别再让CLAUDE.md独自承受一切了是时候为你的项目打造一个专业、有序的规则生态系统了。