如何用项目规则给 AI 划定编码边界

文章目录

• • [📌 技术名片](#📌 技术名片)
  • • [💡 一句话理解](#💡 一句话理解)
  • [一、 主流 AI 编程工具如何定义项目规则](#一、 主流 AI 编程工具如何定义项目规则)
  • [二、 如何编写一份高约束力的 Python 规则文件](#二、 如何编写一份高约束力的 Python 规则文件)
  • • [示例：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	工作区 / 路径级规则
通用 Agent	AGENTS.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 写入源码或日志
- 谨慎使用 `shell=True`、`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，测试检查工具确保边界没有被突破。

---

🪐祝您好运🪐