与 AI 编程工具协作：项目说明书与规则配置详解

前言：

本节聚焦如何与 AI 编程工具（如 TRAE）实现高效协作，重点介绍项目说明书与规则两大项目级配置机制。我们将首先讲解项目说明书的编写方法及其在主流 AI 编程工具中的配置方式，随后深入解析规则的分类、应用场景及规则文件的生效方式。

1. 写给 AI 的项目说明书

1.1 什么是 AI 项目说明书

前面几节介绍的提示词写作技巧，都是针对单次对话的。但在实际项目开发中，尤其是在维护和扩展已有代码库时，开发者每日需要与 AI 进行大量对话：修复缺陷、编写新接口、重构函数……若每次都要在提示词开头重新说明项目背景，既烦琐又容易遗漏。更关键的是，如果 AI 不了解存量项目的架构约定和编码规范，那么它生成的代码很容易与现有代码风格不一致，引入“风格碎片化”问题。

当前主流的 AI 编程工具提供了一种高效的解决方案——项目说明书（AGENTS.md）。项目说明书是放置在项目根目录下的一个 Markdown 格式文件，专门用于向 AI 介绍项目的基本信息、架构背景和协作规范。当 AI 编程工具打开项目时，它会自动将项目说明书的内容注入每次对话的上下文中，使 AI 在每次对话时都“记得”你的项目是什么样的。

这意味着，只需维护一份项目说明书，即可在每次对话中避免重复说明项目背景，同时可保证 AI 生成的代码始终与存量项目的架构和风格一致。

AGENTS.md是一个被广泛支持的事实标准，主流 AI 编程工具均支持这一文件格式，如 Cursor 支持AGENTS.md，TRAE 支持AGENTS.md，Claude Code 支持CLAUDE.md，GitHub Copilot 支持.github/copilot-instructions.md。虽然文件名略有不同，但它们的作用机制和内容格式是完全相同的。需要注意的是，在 TRAE 中，还需要在设置中手动开启“Include AGENTS.md in the context”开关，这样才能使AGENTS.md自动生效。

1.2 项目说明书里要写什么

一份有效的项目说明书，需要在两个目标之间取得平衡。①足够完整。AI 能够理解项目背景，从而不需要在每次对话中补充基础信息。②足够简洁。不要让项目说明书变成一本“百科全书”，将有限的上下文窗口浪费在冗余信息上。

一份有效的项目说明书通常包含以下内容：

1. 项目简介：用两三句话说明这是什么系统、服务什么业务目标、覆盖哪些主要功能模块。
2. 技术栈与版本：列出核心依赖及其精确版本。这对于避免 AI 使用过期 API 至关重要。AI 的训练数据涵盖各个历史版本，如果不指明版本，它可能使用已废弃的 API。
3. 目录结构：简要说明各主要目录和文件的职责，帮助 AI 在被要求修改某个功能时，快速定位到正确的文件。
4. 架构约定：说明项目遵循的架构模式（如分层架构、DDD 等）以及关键的设计决策，如“API 层不得直接访问数据库”“所有异常必须继承自AppException”。
5. 编码规范：命名方式、注释要求、错误处理方式等，这些在没有明确说明规范的情况下，AI 会使用自己认为合理的默认处理方式，与团队规范可能不符。
6. 常用命令：如运行测试、启动本地服务、生成数据库迁移文件等命令的准确写法。当 AI 在建议执行某些命令时，它会参考项目说明书中的内容，而不是猜测。
7. 重要约束（可选）：项目中特别需要 AI 注意的硬性约束，如“禁止直接修改core/目录下的文件”“所有对外接口必须保持向后兼容”。

下面是一个完整的AGENTS.md示例：

1# 极客书城 API 服务 (GeekBooks Backend) 2 3## 项目简介 4本项目是极客书城在线书店的后端 API 服务，负责用户管理、图书目录、 5订单处理和支付集成。服务以 REST API 形式对外提供，供 Web 前端和移动端消费。 6## 技术栈 7- **语言**: Python 3.12。 8- **框架**: FastAPI 0.115。 9- **ORM**: SQLAlchemy 2.0 (异步模式, 使用 asyncpg 驱动)。 10- **数据库**: PostgreSQL 15 (主库) + Redis 7 (缓存 / 消息队列)。 11- **任务队列**: Celery 5.3 + Redis (Broker)。 12- **测试**: pytest + pytest-asyncio + httpx (AsyncClient)。 13- **代码质量**: Ruff (lint + format) + mypy (类型检查)。 14 15## 目录结构 16src/ 17├── api/ # 路由层: 仅做请求参数校验和响应组装, 不含业务逻辑 18├── services/ # 业务逻辑层: 所有业务规则在此实现 19├── repositories/ # 数据访问层: 封装所有数据库和缓存操作 20├── models/ # SQLAlchemy 数据模型 (只定义结构, 不含逻辑) 21├── schemas/ # Pydantic 输入/输出模型 (请求体/响应体) 22├── core/ # 全局配置、异常定义、依赖注入、中间件 23└── tasks/ # Celery 异步任务 24 25## 架构约定 (AI 必须遵守) 26- 严格遵循 3 层架构: api -> service -> repository。 27- API 层不得直接访问数据库 (禁止在 api/ 目录下 import Session)。 28- 数据库操作必须封装在 repository 层。 29- 所有业务异常继承自 AppException。 30- ...... (其他架构约束) 31 32## 编码规范 33- 所有公共函数和类方法必须有中文 docstring。 34- 使用 Python 3.12 的类型注解语法。 35- 函数长度不超过 50 行。 36- 金额字段使用 Decimal 类型, 禁止 float。 37- ...... (其他编码规范) 38 39## 常用命令 40- 启动开发服务器: uvicorn src.main:app --reload --port 8000。 41- 运行全部测试: pytest tests/ -v --asyncio-mode=auto。 42- 代码检查和格式化: ruff check src/ && ruff format src/。

1.3 项目说明书写给谁看

项目说明书的主要读者是 AI，但它对人类同样有巨大的价值。例如，一名新加入团队的工程师，阅读项目说明书后能够快速了解项目的技术选型、架构决策和协作规范，不需要花大量时间阅读代码或询问老同事。因此，维护一份高质量的项目说明书，既是对 AI 协作效率的投资，也是团队知识传承的重要手段。特别在团队成员变动频繁的项目中，项目说明书成为一份常驻的“项目入职手册”。

1.4 在 TRAE 中启用项目说明书

在 TRAE 中启用项目说明书的操作步骤如下：

1. 在项目根目录下创建AGENTS.md文件，填写项目信息。
2. 打开 TRAE 设置中心（单击界面右上角的齿轮图标）。
3. 在左侧导航栏中单击“Rules”，进入规则配置页面。
4. 在“导入设置”区域，找到“将 AGENTS.md 包含在上下文中”开关，确保其处于开启状态，如图 1 所示。

启用后，TRAE 会在每次的 AI 对话中自动将项目根目录下的项目说明书内容注入上下文，无须用户手动引用，AI 会始终在了解项目背景的前提下工作。

TRAE 还支持多层级项目说明书。对于大型项目，TRAE 支持在子目录中放置独立的项目说明书，用于为特定模块配置专属的 AI 行为指导。例如，前端模块的frontend/AGENTS.md描述前端技术栈和约定，后端模块的backend/AGENTS.md描述后端部分。子目录的项目说明书在处理该目录下的文件时会叠加生效，与根目录的项目说明书形成互补。

---

2. 限制 AI 行为的编码规则

2.1 规则是什么

项目说明书描述“项目是什么”，而规则（Rule）告诉 AI “在这个项目中，你应该怎么做”。二者互为补充：项目说明书提供背景知识，规则约束行为模式。在存量项目维护场景中，规则的作用尤为关键，它是将项目长期积累的工程标准“固化”为 AI 可执行约束的核心机制。

如果把项目说明书比作“项目介绍手册”，那么规则就是“行为准则”或“编码公约”。规则的核心价值在于：将存量项目的工程标准转化为 AI 可以执行的硬性约束，防止 AI 在每次生成代码时“自由发挥”而破坏已有代码的一致性。

在没有规则的情况下，AI 会根据训练数据中的“统计平均”来决定代码风格、错误处理方式和测试写法，这通常意味着每次生成的代码风格都会有细微差异，与存量项目长期积累的编码惯例不一致。规则的作用，就是把这种“自由发挥”收束到项目已有的规范范围内。

规则常见的应用场景如下：

1. 编码规范约束：要求 AI 生成的代码遵循团队的命名规范、格式要求和注释风格，确保 AI 生成的代码与人类写的代码风格一致，降低代码审查（Code Review）的“摩擦”成本。
2. 技术选型约束：禁止使用已被团队废弃的库或 API。例如，若要从 Requests 库迁移到 HTTPX 库，可以在规则中写“禁止使用 Requests 库，所有 HTTP 请求必须使用 HTTPX 库”。
3. 文档与注释规范：规定函数 docstring 的格式、语言（中文/英文）和必须包含的信息，确保 AI 生成的代码与团队现有代码风格一致。
4. 测试规范：规定测试文件的命名规则 (test_<模块名>.py)、测试函数的命名格式 (test_<功能>_<场景>) 以及测试的组织方式，使 AI 生成的测试代码与手写测试代码结构一致。
5. 安全规范：禁止生成包含敏感信息硬编码（如把密码、密钥写在代码里）、SQL 字符串拼接等危险模式的代码。

2.2 在 TRAE 中使用规则

TRAE 支持两种类型的规则，适用于不同的使用场景：

1. 全局规则（Global Rules）：在所有项目中均生效，适合存放个人习惯偏好，如“回答时使用中文”“解释代码时先给出整体思路再展示细节”“不要在未经询问的情况下修改测试文件”等。全局规则可在 TRAE 设置中的规则页面直接编写，存储在本地配置中，不属于代码仓库的一部分。
2. 项目规则（Project Rules）：仅在当前项目内生效，以 Markdown 文件形式存放在项目目录的.trae/rules/下，可以纳入 Git 版本管理，供团队成员共享。每名团队成员只需克隆代码仓库，就能获得完整的 AI 行为规范，无须单独配置。

在 TRAE 中创建项目规则的完整步骤如下（见图 2）：

1. 打开 TRAE 的“设置”，选择“规则”，单击“+创建”按钮，在打开的下拉列表中选择“项目”。
2. 输入规则名称（如python-style）后，单击确认，TRAE 会在.trae/rules/目录下创建同名的.md文件并自动打开。
3. 打开规则文件，在 TRAE 窗口顶部选择生效方式，再在正文中用 Markdown 格式编写规则内容。

(注：截图展示了规则列表界面)

规则文件支持 4 种生效方式，如表 1 所示。

表 1：规则文件的生效方式

生效方式	YAML 配置	说明	适用场景
始终生效	alwaysApply: true	每次对话均自动生效	全局编码规范
指定文件生效	globs: "src/**/*.py"	仅对匹配文件生效	特定语言或模块的规范
智能生效	设置description字段	AI 根据description字段自动判断是否应用	场景化规范
手动触发生效	（无特殊配置）	在对话中用“@规则名”手动触发	偶尔用到的特殊规范

下面是一个完整的项目规则文件示例：

1--- 2alwaysApply: true 3--- 4 5# Python 编码规范 (极客书城项目) 6 7## 命名规范 8- 变量名和函数名: snake_case (如 get_user_by_id)。 9- 类名: PascalCase (如 UserService)。 10- 常量: UPPER_SNAKE_CASE (如 MAX_RETRY_COUNT)。 11- 私有方法/属性: 前缀下画线 (如 _validate_password)。 12 13## 类型注解 14- 所有函数参数和返回值必须有类型注解。 15- 使用 Python 3.12 内置泛型语法 (list[str], dict[str, int])。 16- Optional 类型写成 "str | None", 不使用 "Optional[str]"。 17 18## 错误处理 19- 禁止裸 "except:" 或 "except Exception:"。 20- 必须捕获具体异常类型。 21- 业务错误使用自定义异常 (继承 AppException)。 22 23## 安全规范 24- 禁止字符串拼接构造 SQL。 25- 禁止在代码中硬编码密码、API Key 等敏感信息。 26- 用户输入必须经过 Pydantic 校验。 27- ...... (其他规则)

规则的长期维护同样重要。随着项目的演进，某些规则可能变得过时或不再适用；随着团队在 AI 协作中积累经验，团队会发现新的需要约束的模式。建议将规则文件的更新纳入常规的代码审查流程，与代码一起演进。

此外，建议将.trae/rules/目录（及项目说明书）纳入 Git 版本管理，并在项目的 README 或 CONTRIBUTING.md 中说明 AI 协作规范的使用方式。这样，任何新加入的团队成员只需克隆代码库，就能获得完整的 AI 协作环境配置，不必重新摸索。