前言本节聚焦如何与 AI 编程工具如 TRAE实现高效协作重点介绍项目说明书与规则两大项目级配置机制。我们将首先讲解项目说明书的编写方法及其在主流 AI 编程工具中的配置方式随后深入解析规则的分类、应用场景及规则文件的生效方式。1. 写给 AI 的项目说明书1.1 什么是 AI 项目说明书前面几节介绍的提示词写作技巧都是针对单次对话的。但在实际项目开发中尤其是在维护和扩展已有代码库时开发者每日需要与 AI 进行大量对话修复缺陷、编写新接口、重构函数……若每次都要在提示词开头重新说明项目背景既烦琐又容易遗漏。更关键的是如果 AI 不了解存量项目的架构约定和编码规范那么它生成的代码很容易与现有代码风格不一致引入“风格碎片化”问题。当前主流的 AI 编程工具提供了一种高效的解决方案——项目说明书AGENTS.md。项目说明书是放置在项目根目录下的一个 Markdown 格式文件专门用于向 AI 介绍项目的基本信息、架构背景和协作规范。当 AI 编程工具打开项目时它会自动将项目说明书的内容注入每次对话的上下文中使 AI 在每次对话时都“记得”你的项目是什么样的。这意味着只需维护一份项目说明书即可在每次对话中避免重复说明项目背景同时可保证 AI 生成的代码始终与存量项目的架构和风格一致。AGENTS.md是一个被广泛支持的事实标准主流 AI 编程工具均支持这一文件格式如 Cursor 支持AGENTS.mdTRAE 支持AGENTS.mdClaude Code 支持CLAUDE.mdGitHub Copilot 支持.github/copilot-instructions.md。虽然文件名略有不同但它们的作用机制和内容格式是完全相同的。需要注意的是在 TRAE 中还需要在设置中手动开启“Include AGENTS.md in the context”开关这样才能使AGENTS.md自动生效。1.2 项目说明书里要写什么一份有效的项目说明书需要在两个目标之间取得平衡。①足够完整。AI 能够理解项目背景从而不需要在每次对话中补充基础信息。②足够简洁。不要让项目说明书变成一本“百科全书”将有限的上下文窗口浪费在冗余信息上。一份有效的项目说明书通常包含以下内容项目简介用两三句话说明这是什么系统、服务什么业务目标、覆盖哪些主要功能模块。技术栈与版本列出核心依赖及其精确版本。这对于避免 AI 使用过期 API 至关重要。AI 的训练数据涵盖各个历史版本如果不指明版本它可能使用已废弃的 API。目录结构简要说明各主要目录和文件的职责帮助 AI 在被要求修改某个功能时快速定位到正确的文件。架构约定说明项目遵循的架构模式如分层架构、DDD 等以及关键的设计决策如“API 层不得直接访问数据库”“所有异常必须继承自AppException”。编码规范命名方式、注释要求、错误处理方式等这些在没有明确说明规范的情况下AI 会使用自己认为合理的默认处理方式与团队规范可能不符。常用命令如运行测试、启动本地服务、生成数据库迁移文件等命令的准确写法。当 AI 在建议执行某些命令时它会参考项目说明书中的内容而不是猜测。重要约束可选项目中特别需要 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-modeauto。 42- 代码检查和格式化: ruff check src/ ruff format src/。1.3 项目说明书写给谁看项目说明书的主要读者是 AI但它对人类同样有巨大的价值。例如一名新加入团队的工程师阅读项目说明书后能够快速了解项目的技术选型、架构决策和协作规范不需要花大量时间阅读代码或询问老同事。因此维护一份高质量的项目说明书既是对 AI 协作效率的投资也是团队知识传承的重要手段。特别在团队成员变动频繁的项目中项目说明书成为一份常驻的“项目入职手册”。1.4 在 TRAE 中启用项目说明书在 TRAE 中启用项目说明书的操作步骤如下在项目根目录下创建AGENTS.md文件填写项目信息。打开 TRAE 设置中心单击界面右上角的齿轮图标。在左侧导航栏中单击“Rules”进入规则配置页面。在“导入设置”区域找到“将 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 会根据训练数据中的“统计平均”来决定代码风格、错误处理方式和测试写法这通常意味着每次生成的代码风格都会有细微差异与存量项目长期积累的编码惯例不一致。规则的作用就是把这种“自由发挥”收束到项目已有的规范范围内。规则常见的应用场景如下编码规范约束要求 AI 生成的代码遵循团队的命名规范、格式要求和注释风格确保 AI 生成的代码与人类写的代码风格一致降低代码审查Code Review的“摩擦”成本。技术选型约束禁止使用已被团队废弃的库或 API。例如若要从 Requests 库迁移到 HTTPX 库可以在规则中写“禁止使用 Requests 库所有 HTTP 请求必须使用 HTTPX 库”。文档与注释规范规定函数 docstring 的格式、语言中文/英文和必须包含的信息确保 AI 生成的代码与团队现有代码风格一致。测试规范规定测试文件的命名规则 (test_模块名.py)、测试函数的命名格式 (test_功能_场景) 以及测试的组织方式使 AI 生成的测试代码与手写测试代码结构一致。安全规范禁止生成包含敏感信息硬编码如把密码、密钥写在代码里、SQL 字符串拼接等危险模式的代码。2.2 在 TRAE 中使用规则TRAE 支持两种类型的规则适用于不同的使用场景全局规则Global Rules在所有项目中均生效适合存放个人习惯偏好如“回答时使用中文”“解释代码时先给出整体思路再展示细节”“不要在未经询问的情况下修改测试文件”等。全局规则可在 TRAE 设置中的规则页面直接编写存储在本地配置中不属于代码仓库的一部分。项目规则Project Rules仅在当前项目内生效以 Markdown 文件形式存放在项目目录的.trae/rules/下可以纳入 Git 版本管理供团队成员共享。每名团队成员只需克隆代码仓库就能获得完整的 AI 行为规范无须单独配置。在 TRAE 中创建项目规则的完整步骤如下见图 2打开 TRAE 的“设置”选择“规则”单击“创建”按钮在打开的下拉列表中选择“项目”。输入规则名称如python-style后单击确认TRAE 会在.trae/rules/目录下创建同名的.md文件并自动打开。打开规则文件在 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 协作环境配置不必重新摸索。