如何用项目规则给 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 需要的是具体、明确、可判断是否违反的规则。

markdown 复制代码
❌ 模糊规则:

- 请保持代码优雅、低耦合。

✅ 明确规则:

- `routers/` 只负责 HTTP 请求与响应,不得直接访问数据库。

一份标准的 Python 工程规则文件建议包含以下 4 个核心模块:

模块 回答的问题
项目上下文(Project Context) 这是一个什么项目?
架构边界(Architecture Boundaries) 什么代码应该放在哪里?
编码规范(Coding Standards) 代码应该怎么写?
校验与安全(Validation & Safety) 哪些事情不能做?

示例:Python 项目规则文件

markdown 复制代码
生成或修改代码时,应遵循以下项目规则。


## 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% 遵守。

真正可靠的工程约束应该是:

text 复制代码
AI 生成代码
     ↓
Lint(代码规范检查)
     ↓
Type Check(类型检查)
     ↓
Unit Tests(单元测试)
     ↓
Security Check(安全检查)
     ↓
CI(自动执行上述检查)
     ↓
通过 → 允许合并
失败 → 拒绝合并

项目规则负责告诉 AI 应该怎么做,测试检查工具负责检查它到底有没有做到。

不同 AI 编程工具已经内置了不同程度的代码规范、上下文管理和安全机制,因此实际项目不必机械照搬模板。只保留真正需要 AI 长期遵守的规则即可。

项目规则不是越多越好,而是越明确、越稳定、越贴合项目越好。


结语

项目规则 / Project Rules 的价值,不是让 AI "写得更漂亮",而是让它持续按照同一套工程规则工作。

它把原本存在于架构师脑中的约定:项目上下文、架构边界、编码规范、校验与安全

转化成 AI 可以持续读取的项目上下文。

架构负责定义边界,项目规则负责把边界告诉 AI,测试检查工具确保边界没有被突破。


🪐祝您好运🪐

相关推荐
百度Geek说14 小时前
从代码生成到需求交付:DarkFactory 的工程实践
人工智能
Baihai_IDP14 小时前
使用场景不同,模型“推理速度慢”的原因也不同
人工智能·面试·llm
挖掘狂人14 小时前
AI 三分钟写完的代码,你凭什么敢直接上线?
人工智能·程序员·ai编程
codigger15 小时前
AI 三分钟写完的代码,你凭什么敢直接上线?
ai·程序员·编程·ai编程·#人工智能
沉默王二15 小时前
腾讯这波上大分,Hy4-flash值得你猛蹬。
openai·agent·vibecoding
回家路上绕了弯15 小时前
让错误活不过 N 步
ai编程
墨林陌15 小时前
AI 热点日报(2026-11-20):苹果自研 AI 智能体曝光,Anthropic 上市首日大涨,智能体支付落地
人工智能
AAA修煤气灶刘哥15 小时前
32 GB 内存跑起 1800 亿参数模型,代价是什么?
人工智能·后端·架构
玩美数据15 小时前
海外市场数据分析驱动下的产业趋势演变与竞争格局深度解读
大数据·人工智能
oil欧哟15 小时前
Oil Studio 的产品思路与日常使用方式:在 Mac 上录口播演示,并接入 AI Agent 精剪与自动录屏
人工智能·macos