1. 项目缘起与核心价值去年年中当AI编程助手开始从简单的代码补全向更复杂的“代理”模式演进时我像很多开发者一样一头扎进了Cursor的怀抱。它当时集成的Claude Code模型配合其独特的“Agent”模式确实让人眼前一亮——你不再仅仅是和它一问一答而是可以给它设定一个目标比如“重构这个模块”或“修复这个测试”然后看着它自己打开文件、分析、修改、甚至运行测试。这种体验仿佛身边多了一个不知疲倦的初级工程师。然而兴奋劲没过多久我就遇到了一个普遍且棘手的问题这个“代理”太有主见了或者说太“放飞自我”了。我让它优化一个函数它可能把整个类的结构都改了我让它修复一个空指针异常它可能引入了一堆不相关的依赖。它的每一次“自主行动”都像一次冒险结果难以预测代码评审的工作量不降反增。这让我意识到要让AI代理真正成为得力的助手而不是一个需要被时刻盯防的“熊孩子”就必须给它立规矩。这就是agent-rules这个项目诞生的背景。它不是什么复杂的框架而是一套我在实践中总结、提炼出来的“规则集”专门用于约束和引导像Cursor Agent这类工具的“行为”确保它的产出是可预测、可审查、且符合团队规范的。简单来说agent-rules解决的核心痛点是在赋予AI代理自主权的同时如何防止它“好心办坏事”或“过度发挥”从而将AI的自动化能力安全、可控地集成到真实的生产和开发流程中。它适合所有正在或打算深度使用Cursor、Claude Code、乃至其他具备类似“代理”能力的LLM工具的开发者、技术负责人和团队。无论你是想提升个人开发效率还是为团队制定AI协作规范这里面的经验和“规矩”都能提供直接的参考。2. 规则集的设计哲学与架构思路设计一套给AI用的规则和给人写代码规范有相似之处但逻辑截然不同。人的规则可以理解“精神”比如“写出可读的代码”但AI需要的是明确、无歧义、可被其文本处理逻辑直接匹配和执行的指令。我的设计哲学基于以下三个核心原则2.1 原则一指令必须原子化与场景化你不能对AI说“请写出健壮的代码”。这太模糊了。你必须拆解在什么场景下例如处理用户输入什么是“健壮”例如进行非空校验、类型检查、长度限制。因此agent-rules中的每一条规则都绑定一个具体的开发场景或任务类型。例如针对“创建新的API端点”这个场景规则集里会包含文件结构规则必须在src/api/v1/目录下创建。命名规则文件名为[resource]_controller.py类名为[Resource]Controller。导入规则必须从core.schemas和core.database导入基类和会话。方法规则必须包含GET(列表/详情) 和POST方法的最小实现模板。文档规则必须使用特定的apidoc格式注释。这样当AI代理接到“创建用户管理端点”的任务时它拿到的不是模糊的创意要求而是一份可以逐步勾选的、明确的施工图纸。2.2 原则二规则应具备强制性与可验证性规则不能是建议而应是强制性的约束。这通过两种方式实现前置约束在给AI的提示词Prompt中直接写入“你必须遵守以下规则...”利用LLM本身的指令遵循Instruction Following能力。后置验证规则本身描述的结果应该是可被自动化工具如linter、测试、脚本快速验证的。例如“所有数据库查询必须使用参数化查询”这条规则可以通过一个简单的代码扫描脚本来检查是否存在字符串拼接的SQL。在我的实践中我会将关键规则同时用于前置提示和后置验证形成一个闭环。AI在过程中被约束而最终的产出物又能被快速检查确保规则没有被无意或有意地绕过。2.3 原则三规则需分层与可扩展不是所有规则都同等重要。我将其分为三个层级L1 安全与正确性规则涉及安全、数据完整性、系统稳定性的规则。例如“禁止执行未经审查的外部脚本”、“所有金额计算必须使用Decimal类型”。这些是红线绝对不允许违反。L2 架构与一致性规则涉及项目结构、设计模式、公共约定的规则。例如“服务层类必须继承自BaseService”、“DTO命名必须以Request/Response结尾”。这些保证了项目长期的可维护性。L3 风格与质量规则代码格式、命名风格、注释要求等。例如“函数长度不超过50行”、“使用Black格式化代码”。这些可以通过工具自动修复重要性相对较低但能提升协作效率。agent-rules的架构就是基于这些原则以YAML或JSON等结构化格式组织每个规则包含id唯一标识、scope适用范围如python/api、description描述、constraint给AI的约束文本和verification验证方法或脚本片段。这种结构化的设计使得规则集本身也易于被其他自动化工具管理和应用。3. 核心规则详解与实操配置下面我挑选几类最具代表性的规则拆解其设计细节和如何在Cursor等工具中实际配置。你可以把这些看作是一个可直接复用的“规则包”。3.1 代码修改类任务的“黄金规则”这是最常用也最容易出问题的场景。AI代理经常过于“积极”地重构它认为需要改进的代码。规则CR-01变更范围隔离描述任何代码修改必须严格局限在指定的函数、方法或类内除非任务明确要求分析模块间影响。给AI的约束文本“你本次的修改范围仅限于文件[file_path]中的[function_name]函数。禁止修改此函数之外的任何代码包括其所属类的其他方法、导入语句、文件顶部的注释等。如果你的修改方案需要变动外部代码请先停止并向我说明原因请求授权。”实操心得这条规则极大地减少了“惊吓”。我会在给Cursor Agent的任务描述里把文件路径和函数名用反引号明确标出并把这条约束放在提示词的最前面。实测下来它能将AI的“扩散式修改”概率降低80%以上。3.2 数据库与API操作的安全规则涉及数据持久化和对外接口安全是重中之重。规则SEC-01SQL注入防护描述所有数据库查询必须使用参数化查询或ORM提供的方法绝对禁止使用字符串拼接。给AI的约束文本“当你需要编写数据库查询代码时必须使用SQLAlchemy的session.execute(text(“SELECT * FROM table WHERE id :id”), {“id”: value})参数化形式或使用ORM的查询方法如session.query(User).filter_by(idid)。在任何情况下都不得将变量值通过f-string或运算符直接拼接到SQL字符串中。请在你的回答中确认你使用了安全的方式。”验证脚本片段Pythonimport ast import re def check_sql_string_interpolation(file_path): with open(file_path, ‘r’) as f: tree ast.parse(f.read()) for node in ast.walk(tree): if isinstance(node, ast.JoinedStr): # f-string # 简单检查如果f-string中包含‘SELECT‘, ‘INSERT‘等关键词则报警告需人工复核 if re.search(r‘\b(SELECT|INSERT|UPDATE|DELETE|FROM|WHERE)\b‘, ast.unparse(node), re.IGNORECASE): print(f“警告文件 {file_path} 第 {node.lineno} 行可能存在SQL字符串拼接: {ast.unparse(node)[:100]}...”)3.3 项目结构与命名的一致性规则保持项目整洁让任何团队成员包括未来的你都能快速理解。规则ARCH-01分层架构约束描述严格遵守controllers-services-repositories-models的调用链禁止跨层或反向依赖。给AI的约束文本“本项目采用严格的分层架构。controllers层负责处理HTTP请求和响应只能调用services层的方法。services层包含业务逻辑只能调用repositories层或其它services。repositories层负责数据访问直接操作models。请确保你新增或修改的代码遵守此依赖方向。例如controller中不应出现session.query(...)语句。”配置方法对于Cursor你可以在项目根目录创建一个.cursorrules文件这是一个自定义的实践并非Cursor原生功能但可以通过提示词工程实现类似效果在里面用注释的形式写明这些架构规则。然后在每次开启Agent任务时通过指令/rules假设的自定义指令或直接在对话中粘贴这些规则让AI加载上下文。3.4 与AI模型交互的“元规则”这类规则用于管理AI代理自身的行为模式非常关键。规则META-01分步确认与人工检查点描述对于复杂任务AI必须将解决方案分解为步骤并在关键步骤前请求确认。给AI的约束文本“在开始执行这个任务前请先将其分解为不超过4个清晰的步骤并向我概述你的计划。在涉及以下操作前必须暂停并等待我的明确‘批准’指令1. 创建新的数据库表或修改现有表结构。2. 删除任何现有的文件或代码块。3. 安装新的第三方依赖包。4. 修改项目的核心配置文件如settings.py,package.json。现在请先给出你的步骤计划。”实操心得这条规则把“自动驾驶”模式变成了“领航员”模式。AI先给出路线图你在关键路口握着方向盘。这虽然增加了一点交互成本但完全避免了AI一头扎进你不想让它改的领域所带来的灾难性后果。在Cursor中你可以把这条规则保存为一个代码片段或笔记每次启动复杂任务前先发给它。4. 规则集的实施、集成与迭代流程有了规则如何让它真正用起来而不是躺在文档里睡大觉我摸索出了一套从个人到团队的落地流程。4.1 个人工作流集成对于个人开发者轻量级集成是关键。我的做法是结合Cursor的自定义指令Custom Instructions和简单的Shell脚本。初始化规则库在项目根目录创建docs/agent_rules.md文件用Markdown表格清晰分类列出所有规则L1, L2, L3。配置Cursor全局指令在Cursor的设置中找到Custom Instructions或类似功能不同版本位置可能不同。在“关于我/我的项目”部分插入以下内容我的项目遵循一套严格的开发规则Agent Rules旨在保证代码安全、一致性和可维护性。在开始任何编码、重构或分析任务前请务必首先阅读并理解项目根目录下 docs/agent_rules.md 文件中的全部内容。你的所有输出必须严格遵守这些规则尤其是L1和L2级别的规则。如果任务要求与规则冲突请向我指出冲突点并询问处理方式。任务级提示词模板对于特定类型的任务我准备了更具体的提示词模板。例如创建新API的模板任务创建关于[资源名]的RESTful API端点包含列表、详情、创建功能。 约束请严格遵循 docs/agent_rules.md 中“场景创建新API端点”章节的所有规则规则ID: API-01至API-05。 请先输出你将遵守的规则清单和实现步骤概要经我确认后再开始编写代码。后置验证脚本编写一个简单的Python脚本scripts/verify_rules.py利用正则表达式或AST抽象语法树对SEC-01SQL注入等关键规则进行快速扫描。在提交代码前运行一下。4.2 团队协作与知识共享当在团队中推广时重点在于降低采纳门槛和建立共识。规则库作为活文档将agent-rules仓库或项目内的规则文档作为团队的技术规范之一。利用Git的版本控制来管理规则的变更每次修改都需要提交Pull Request并经过团队成员评审。开发环境标准化在团队的项目模板Cookiecutter或自定义脚手架中内置.cursorrules文件和验证脚本。新项目一经创建规则就自动就位。Code Review清单在团队的Pull Request模板中增加一个“AI生成代码检查”部分列出几条最重要的L1规则作为必查项。例如[ ] 确认无SQL字符串拼接。[ ] 确认本次修改未超出指定范围链接到相关Issue。[ ] 确认新增API符合分层架构。定期规则评审会每月花15-30分钟回顾规则的有效性。哪些规则被频繁违反哪些规则已经过时是否有新的“AI迷惑行为”需要立规矩让规则集随着项目和AI工具的能力共同进化。4.3 规则的迭代与反模式规则不是一成不变的。在实践过程中我总结出几个需要避免的“反模式”规则过细扼杀创造性如果你把“函数必须用动宾短语命名”这种风格细节也作为L1规则强制要求AI会变得束手束脚产出僵化。应对将L3规则定位为“建议”或通过Pre-commit Hook如black,isort在提交时自动格式化而不是让AI在创作时分心。规则冲突让AI困惑如果规则A说“所有错误必须被日志记录”规则B说“控制器层代码应保持简洁不超过50行”AI在处理错误日志时可能陷入两难。应对建立规则的优先级和例外机制。在规则文档中明确“当L1规则与L2/L3规则冲突时优先满足L1规则。若L2规则间冲突请向人类请求澄清。”“纸面规则”无法验证制定了一条“代码必须高性能”的规则但无法在AI生成时或生成后有效评估。应对要么将规则具体化为可衡量的指标如“时间复杂度不应超过O(n log n)”要么将其降级为“设计原则”而非“代理规则”在人工评审时考量。5. 从Rules到Scripts自动化能力的演进随着使用深入我发现仅仅用自然语言规则去约束AI效率仍有瓶颈。AI可能会“理解”规则但在执行复杂、多步骤的任务时依然可能出错或需要大量人工交互。于是我的工作重心从制定静态的agent-rules转向了开发动态的agent-scripts即我新项目的工作。5.1 Rules的局限性规则本质上是“禁止性”或“描述性”的它告诉AI“不要做什么”或“应该做成什么样”。但对于“如何一步步做到”这个动态过程控制力较弱。例如规则可以要求“最终生成的API需要包含Swagger文档”但无法精确控制AI先写代码、再写测试、最后生成文档的顺序和方式。这个过程仍然依赖AI自身的“规划”能力而这是当前LLMs的薄弱环节。5.2 Scripts的设计理念agent-scripts的核心思想是将复杂任务分解为一系列原子化的、可预测的步骤并用脚本或结构化的指令集来驱动AI按顺序执行每一步的输入和输出都被严格定义。举个例子以前的任务是“在用户模块添加一个根据邮箱查找用户的服务方法”。现在这个任务被一个脚本定义步骤1分析- 输入UserService现有代码。输出确认方法签名位置和依赖。步骤2实现- 输入方法签名、规则约束SEC-01等。输出find_by_email方法实现代码。步骤3测试- 输入新方法代码、测试文件模板。输出对应的单元测试代码。步骤4集成- 输入所有生成代码。输出在__init__.py中导出新方法如果需要的修改建议。每个步骤都是一个独立的、上下文清晰的子任务AI只需要专注于当前这一步。脚本引擎可以是一个简单的Python脚本或者利用Cursor的自动化特性负责串联这些步骤并将上一步的输出作为下一步的输入。这样整个流程就变得像流水线一样可靠。5.3 一个简单的脚本实例假设我们有一个用来自动创建标准化CRUD接口的脚本。它不是一个可执行程序而是一个给AI的“超级提示词”模板。# script: generate_crud_api.yaml name: “生成标准CRUD API” target: “FastAPI项目” steps: - step: 1 action: “collect_info” prompt: | 请为我创建名为 {resource} 的资源的完整CRUD API。首先请向我询问并确认以下信息 1. 资源的主要属性字段名和类型例如id: int, name: str, email: str。 2. 数据库表名如果与资源名不同。 3. 希望API放置在哪个模块下例如app/api/v1。 请逐个提问在我回答完一个问题后再问下一个。 output: 一个收集好的信息字典。 - step: 2 action: “generate_pydantic_schemas” prompt: | 基于上一步收集的信息创建Pydantic模型Schemas。 规则 1. 创建 {Resource}Create、{Resource}Update、{Resource}InDB 三个Schema。 2. 所有字段使用Python类型提示。 3. {Resource}Create 和 {Resource}Update 中id字段应为Optional且默认None。 请只输出代码块不要解释。 input: “step1.output” output: “schemas_code” - step: 3 action: “generate_crud_service” prompt: | 基于Schemas和资源名生成一个CRUD服务类 {Resource}Service。 规则 1. 类必须继承自 BaseService[Model, CreateSchema, UpdateSchema]。 2. 必须包含 get, get_multi, create, update, delete 方法的最小实现。 3. 所有数据库操作必须通过 BaseRepository 进行。 请只输出代码块。 input: [“step1.output”, “step2.output”] output: “service_code” # ... 后续步骤生成Controller、路由、单元测试等在实际操作中我会在Cursor中手动启动这个“脚本”即按照这个YAML结构一步步给AI发送提示词并粘贴上一步的输出。未来这完全可以由一个外部的自动化工具来驱动Cursor的API完成。5.4 Rules与Scripts的关系你可以将agent-rules看作是交通法规限速、禁止逆行而agent-scripts则是具体的导航路线和驾驶操作指南前方300米右转进入辅路。规则确保了行为的安全与合规是底线脚本则提供了高效、可靠的达成目标的路径是效率工具。二者结合才能让AI代理在正确的道路上安全、快速地行驶。6. 常见问题与实战排坑记录在实际推行AI代理规则的过程中我遇到了不少坑。这里记录一些典型问题和我的解决方案希望能帮你绕开这些弯路。6.1 AI“忘记”或“忽略”规则怎么办这是最常见的问题。你明明在提示词开头写了规则AI却在输出时违反了。原因分析LLM的上下文窗口有注意力限制。如果提示词过长或者任务描述过于复杂后面的规则可能会被“稀释”。此外如果规则表述模糊AI可能无法准确理解。解决方案规则前置与精简把最重要的L1规则放在系统提示词如Cursor的Custom Instructions或用户消息的最开头并用加粗或“规则”这样的前缀强调。规则描述务必简洁、无歧义。分步激活规则不要一次性抛出所有规则。对于多步骤任务在每一步开始前重申与该步骤最相关的1-3条核心规则。例如在AI要写数据库代码前再次强调“记住使用参数化查询规则SEC-01”。要求复述与确认在给出复杂任务后追加一句“请先复述你将遵循的核心规则以确保你已理解。”这能强制AI“思考”一遍规则提高遵循率。6.2 规则与任务目标发生冲突时AI如何处理有时AI会死板地遵守某条规则导致任务无法完成。例如规则要求“函数不超过30行”但一个复杂的算法逻辑确实需要35行。解决方案在规则体系中建立例外沟通机制。在给AI的指令中加入“如果你认为严格遵守某条规则将导致无法实现任务核心目标或产生更糟糕的代码请明确指出冲突的规则ID并提出你的修改建议及理由等待我的决策。” 这赋予了AI“申诉”的权利将决策权交回给人类。6.3 如何验证AI生成的代码真的遵守了规则人眼逐行检查低效且容易遗漏。解决方案投资编写自动化验证脚本。从最简单的开始正则表达式扫描针对“禁止print调试语句”、“必须使用logging”等规则非常有效。AST分析对于检查代码结构、导入依赖、函数复杂度等更复杂的规则必不可少。Python的ast库、JavaScript的babel/parser等工具可以帮你。集成到CI/CD将关键规则的验证脚本设置为Git预提交钩子pre-commit hook或CI流水线中的一个环节。任何违反L1规则的代码都无法合并从流程上保障安全。实操工具推荐对于Python项目pre-commit框架是管理这类钩子的神器。你可以轻松集成black格式化、flake8风格检查和你自定义的规则检查脚本。6.4 团队成员对规则接受度不高觉得麻烦推行任何新规范都会遇到阻力。解决方案价值先行通过一次“事故复盘”来展示规则的价值。例如展示一段因没有参数化查询而导致SQL注入漏洞的AI生成代码再对比遵守规则后的安全代码。渐进式推行不要一开始就抛出50条规则。先挑选3-5条最能立竿见影提升代码质量或减少Review工作量的核心规则如“修改范围隔离”、“SQL安全”让大家先用起来看到好处。工具赋能尽可能让工具去承担检查规则的工作而不是靠人脑记忆和人眼检查。当团队成员发现大部分规则检查是自动完成、无需他们额外费心时抵触情绪会大大降低。共同维护鼓励团队成员提出修改或新增规则的建议。让规则集成为团队共同智慧的产物而不是自上而下的命令。6.5 面对不同的AI模型Claude、GPT等规则需要调整吗需要。不同模型的理解能力、指令遵循能力和“性格”有差异。实战观察Claude系列模型如Claude Code通常对长上下文和复杂指令的理解更稳定更“守规矩”适合执行严谨、多步骤的任务。GPT系列模型可能更具“创造性”但有时也会更“叛逆”需要更明确的约束。调整策略为不同的主力模型准备略微不同的规则表述。对于“叛逆”一点的模型规则要写得更绝对、更不容置疑使用“必须”、“禁止”、“绝对不可以”等强语气词。同时可以准备一个“规则兼容层”即一套核心的、所有模型都必须遵守的规则L1和一套可选的、针对模型特性调整的补充规则。7. 个人体会与未来展望回顾从杂乱无章地使用AI编码到系统化地制定agent-rules再到探索agent-scripts的自动化这个过程让我深刻认识到将AI融入开发工作流不是一个简单的工具替换而是一次工作范式的升级。它要求我们从“如何写代码”转向“如何设计任务、制定规则、并验证结果”。最大的体会是信任源于可控效率生于规范。早期对AI的恐惧和不信任很大程度上源于其输出的不可预测性。而一套好的规则集就像给一匹千里马套上了缰绳和鞍具你不再担心它狂奔乱跑而是可以驾驭它去往你想去的地方。规则越清晰AI的行为就越可预测你才敢把更重要的任务交给它。目前agent-scripts的方向让我更加兴奋。它意味着我们可以将常见的开发模式如搭建CRUD脚手架、实现特定设计模式、进行依赖升级封装成可重复执行的“剧本”。未来我设想能有一个轻量级的“脚本运行器”它可以读取一个YAML格式的脚本定义然后自动与Cursor、Claude等工具的API交互一步步驱动AI完成从需求分析到代码生成、测试乃至提交的全过程。这将把开发者的角色进一步推向“架构师”和“质检员”专注于更高层次的设计和决策。当然这条路没有终点。AI模型在快速进化我们的方法和工具也需要持续迭代。但无论如何从制定几条简单的规则开始有意识地去管理和引导你的AI助手这绝对是当前投入回报比最高的实践。它不仅能立刻提升你当下的开发体验和代码质量更是在为未来更高程度的人机协同打下坚实的基础。不妨就从为你当前的项目定义前三条最重要的“L1安全规则”开始吧。