文章目录 技术名片 一句话理解一、 主流 AI 编程工具如何定义项目规则二、 如何编写一份高约束力的 Python 规则文件示例Python 项目规则文件三、项目规则是护栏不是编译器结语上一篇我们讨论了一个核心原则先定义边界和规则再让 AI 在边界内发挥能力。那么问题来了这些架构规则怎样才能真正交给 AI答案就是本文的主题——Project Rules项目规则。 技术名片项目规则Project Rules指通过项目级规则文件将项目的技术栈、架构边界、编码规范和安全要求持续提供给 AI。不同 AI 编程工具可能将其称为 Rules、Instructions、Custom Instructions 等但核心目的相同告诉 AI 这个项目应该怎么写以及哪些边界不能突破。 一句话理解项目规则就像放在施工现场入口处的《施工规范》。AI 是施工队架构是图纸而 Rules 则明确告诉它哪些墙能拆、哪些层不能跨、材料用什么标准、完工后必须通过什么验收。这些规则会作为持久化的项目上下文或指令参与 AI 编码过程持续影响代码生成、修改和 Agent 行为一、 主流 AI 编程工具如何定义项目规则不同工具的文件名和规则机制有所不同但本质是一致的把原本依赖工程师记忆的规范变成 AI 可以持续读取的项目约束。以下是当前最主流的配置方式工具常见项目规则文件主要作用Cursor.cursor/rules/*.mdc项目级 / 路径级规则GitHub Copilot.github/copilot-instructions.md仓库级规则GitHub Copilot.github/instructions/*.instructions.md路径级规则Windsurf.windsurf/rules/*.md工作区 / 路径级规则通用 AgentAGENTS.md项目或目录级规则二、 如何编写一份高约束力的 Python 规则文件AI 需要的是具体、明确、可判断是否违反的规则。❌ 模糊规则 - 请保持代码优雅、低耦合。 ✅ 明确规则 - routers/ 只负责 HTTP 请求与响应不得直接访问数据库。一份标准的 Python 工程规则文件建议包含以下 4 个核心模块模块回答的问题项目上下文Project Context这是一个什么项目架构边界Architecture Boundaries什么代码应该放在哪里编码规范Coding Standards代码应该怎么写校验与安全Validation Safety哪些事情不能做示例Python 项目规则文件生成或修改代码时应遵循以下项目规则。 ## 1. 项目上下文 技术栈 - Python 3.11 - FastAPI - Pydantic v2 - SQLAlchemy 2.x - Pytest 优先保证 - 职责清晰 - 类型安全 - 可测试 - 低耦合 除非明确需要不要引入新的第三方依赖。 ## 2. 架构边界 项目采用 Router → Service → Repository → Database 职责 - routers/处理 HTTP 请求、参数校验和响应 - services/处理业务逻辑 - repositories/负责数据库访问 - schemas/定义 Pydantic 输入输出模型 - models/定义数据库 ORM Model 禁止 - Router 直接访问数据库 - Service 直接执行 SQL - Repository 包含业务逻辑 - Repository 反向调用 Service - Service 依赖 Router ## 3. 编码规范 - 公共函数提供完整 Type Hints - API 输入输出使用 Pydantic 校验 - 数据库、HTTP Client 等外部依赖通过参数或依赖注入提供 - I/O 操作优先使用 async / await - 禁止硬编码 API Key、密码等敏感配置 - 优先复用现有组件避免重复代码 - 不要为了“以后可能需要”而过度设计 ## 4. 校验与安全 - 所有外部输入必须进行校验 - 禁止使用 except Exception: pass 静默吞掉异常 - 数据库使用 ORM 或参数化查询 - 禁止将密码、Token、API Key 写入源码或日志 - 谨慎使用 shellTrue、eval()、exec() 等高风险操作 ## AI 修改代码时 修改代码前 1. 先判断代码属于哪一层 2. 检查项目中是否已有可复用实现 3. 只修改完成当前任务所必需的代码 如果用户要求与现有架构冲突 **先指出冲突和风险再给出符合现有架构的实现方案。**很多先进的Agent已经内置强化了项目规则在实际使用时请酌情删减。三、项目规则是护栏不是编译器需要特别注意项目规则可以提高 AI 输出的一致性但不能保证 AI 100% 遵守。真正可靠的工程约束应该是AI 生成代码 ↓ Lint代码规范检查 ↓ Type Check类型检查 ↓ Unit Tests单元测试 ↓ Security Check安全检查 ↓ CI自动执行上述检查 ↓ 通过 → 允许合并 失败 → 拒绝合并项目规则负责告诉 AI 应该怎么做测试检查工具负责检查它到底有没有做到。不同 AI 编程工具已经内置了不同程度的代码规范、上下文管理和安全机制因此实际项目不必机械照搬模板。只保留真正需要 AI 长期遵守的规则即可。项目规则不是越多越好而是越明确、越稳定、越贴合项目越好。结语项目规则 / Project Rules 的价值不是让 AI “写得更漂亮”而是让它持续按照同一套工程规则工作。它把原本存在于架构师脑中的约定项目上下文、架构边界、编码规范、校验与安全转化成 AI 可以持续读取的项目上下文。架构负责定义边界项目规则负责把边界告诉 AI测试检查工具确保边界没有被突破。祝您好运
