AI 编程入门指南
讲解如何高效使用 AI 辅助编程，从 AGENTS.md 编写到工作流实践，涵盖核心概念、计划模式、规则与技能等关键环节。
本文所有实践均基于 Trae IDE，它是字节跳动推出的一款内置 AI 能力的编程工具，支持 AGENTS.md、项目规则、计划模式等 AI 编程机制。如果你使用其他 AI 编程工具（如 Cursor、Windsurf 等），核心思路相通，但具体操作会有所差异。
AI 编程不是”让 AI 写完所有代码”，而是你负责决策，AI 负责执行。关键在于给 AI 提供足够的上下文，让它理解你的项目，然后在你的指导下完成编码。
Trae 中有几个核心机制：
| 机制 | 文件/位置 | 作用 |
|---|---|---|
| AGENTS.md | 项目根目录 | 项目上下文文件，AI 每次对话都会读取 |
| 项目规则 | .trae/rules/ | 持久化的项目规范，自动注入 AI 上下文 |
| 计划模式 | /plan 命令 | 先规划再执行，AI 产出方案文档供你审批 |
| 规格说明 | /spec 命令 | 生成完整的技术规格文档（PRD + 技术方案 + 实现清单） |
| 技能 | .trae/skills/ | 可复用的提示词模板，针对特定任务 |
AGENTS.md 是 AI 的”项目说明书”。AI 每次对话开始时都会读取这个文件，了解项目的整体情况。写好 AGENTS.md 是 AI 编程最重要的一步。
AGENTS.md 有两种编写方式：
- 人工编写：如果你对项目非常熟悉，直接手写是最快的。你最清楚哪些信息对 AI 重要、哪些是项目特有的约定。
- 让 AI 生成：让 AI 先浏览项目代码和配置，然后生成初稿，你再审查修改。适合接手一个新项目时使用。
两种方式都可以，关键是你必须审查和精简。AI 生成的初稿通常太长，需要按下面的原则精简。
一份好的 AGENTS.md 只需要覆盖以下内容：
# 项目名称（一句话描述）
## 技术栈 ← 一行列出核心技术，不要用列表逐条展开## 构建与运行 ← 关键命令## 项目结构 ← 精简的目录树，只到包级别## 架构要点 ← 最核心的设计模式（3~6 条）## 编码规范 ← AI 必须遵守的代码风格（6 条以内）## 核心业务 ← 关键实体和业务流程## 运行环境 ← 语言版本、数据库等要求AGENTS.md 的第一原则：精简。
-
控制在 100 行以内。AI 的上下文窗口是有限的，AGENTS.md 越长，AI 能用于实际编码的”记忆空间”就越少。内容太多反而会降低 AI 的理解能力。
-
写 AI 需要知道的，不是给新人看的文档。例如”JavaScript 使用 camelCase 命名”这种通用知识不需要写，但”路由必须用
@Controller('beanName')显式命名”这种项目特有的约定必须写。 -
不要复制代码到 AGENTS.md。AI 可以直接读取源文件，不需要在 AGENTS.md 中嵌入代码片段。
-
不要写可以推断出来的信息。比如每个实体有哪些字段、每个接口有哪些方法——AI 读代码就能知道。
-
定期精简。随着项目发展，AGENTS.md 会逐渐膨胀。每隔一段时间审查一次，删除过时的内容。
直接让 AI 写代码，很容易出现：
- 方案不合理，改完才发现要重做
- 改动范围失控，涉及太多文件
- 忽略了边界情况
先用 /plan 让 AI 输出方案，你审批通过后再执行。
假设你发现项目中某个模块存在性能问题，需要优化：
你：分析一下当前的查询性能瓶颈在哪里AI：（分析完整的数据流，从视图层 → 控制层 → 服务层 → 数据访问层） 结论：使用了内存分页，数据量大时存在性能隐患。
你：/plan 在尽量小改动的情况下，实现数据库层面的物理分页AI：（产出详细方案文档，保存到 .trae/documents/） - 引入分页插件 - 修改数据访问层相关文件 - 预估改动量和风险一个好的计划应该包含：
- 背景与目标：为什么要做这件事
- 改动范围：精确到文件列表和改动说明
- 设计决策：为什么选择这个方案，而非其他方案
- 风险评估：可能出问题的地方
- 验证方式：如何确认改动是正确的
计划不是最终方案。你应该：
- 质疑合理性：为什么要改这么多文件？能不能更少？
- 提出约束：我希望控制层零改动，你看看行不行
- 要求解释：为什么选这个方案而不是其他？
AI 会根据你的反馈修改方案，直到你满意为止。
| 命令 | 适用场景 | 产出物 | 复杂度 |
|---|---|---|---|
/plan | 单一功能改动、Bug 修复、性能优化 | 方案文档（保存到 .trae/documents/） | 轻量 |
/spec | 复杂功能、新模块开发、需要完整技术规格 | PRD + 技术方案 + 实现清单 + 审查清单 | 重量 |
简单说：小改动用 /plan，大功能用 /spec。/spec 会生成更完整的文档链，包括产品需求、技术方案、实现任务拆分和验收清单。
计划审批通过后，AI 会按照计划逐步实施：
AI 开始执行：1. 添加必要依赖 ✓2. 修改配置文件 ✓3. 逐个修改受影响的模块 ✓4. 清理无用代码 ✓不要盲目信任 AI 的执行结果。 你需要：
- 检查遗漏：确认 AI 是否真的改完了所有需要改的文件
- 运行构建：确保项目编译/构建通过
- 运行测试：确保测试通过
- 检查诊断：查看 IDE 中的错误提示
AI 在执行过程中经常会出现遗漏或错误，这是正常现象：
你：你确定改完了？再检查看看AI：（重新搜索所有文件，发现遗漏） → 补全遗漏的修改 → 清理残留的无用代码这说明 AI 可能犯错，你的审查不可替代。
项目规则存放在 .trae/rules/ 目录下，会在每次对话时自动注入 AI 上下文。适合放强制性的、反复需要遵守的约定。
规则和 AGENTS.md 的区别：
- AGENTS.md：项目全貌（概述、结构、架构）
- Rules：具体的强制约束（“必须怎么做”）
什么时候创建规则：
- 当你发现 AI 反复犯同样的错误时
- 当你有绝对不能违反的约束时
- 当某些规范需要在所有对话中都被遵守时
技能存放在 .trae/skills/ 目录下，是可复用的提示词模板。适合放特定任务的完整流程。
什么时候创建技能：
- 当一个任务有固定的执行步骤时
- 当你想让 AI 按照特定模式完成某类工作时
使用 AI 编程后，项目中会出现一些 AI 辅助生成的文件。哪些该提交到 Git，哪些不该？
| 文件 | 说明 |
|---|---|
AGENTS.md | 项目上下文文件，团队成员和 AI 都需要它 |
.trae/rules/ | 项目规则，确保团队 AI 编程规范一致 |
.trae/skills/ | 可复用技能，团队共享 |
| 业务代码改动 | AI 生成或修改的代码文件 |
| 文件 | 说明 |
|---|---|
.trae/documents/ | /plan 生成的方案文档（一次性参考用） |
.trae/ 下的临时会话文件 | AI 对话的中间状态，无长期价值 |
# AI 编程临时文件.trae/documents/原则：提交对后续开发有参考价值的文件，丢弃一次性的中间产物。
| 做法 | 示例 |
|---|---|
| 先问再做 | ”帮我分析一下查询性能” → 确认方案 → 再执行 |
| 明确约束 | ”在尽量小改动的情况下…” “控制层零改动” |
| 质疑结果 | ”你确定改完了？再检查看看” |
| 分步验证 | ”改完了吗？帮我检查一下是否还有遗漏” |
| 原则 | 说明 |
|---|---|
| 精简至上 | 控制在 100 行以内，AI 的上下文窗口很宝贵 |
| 写特异性 | 只写这个项目特有的约定，通用知识不用写 |
| 定期审查 | 每隔一段时间清理过时内容 |
1. 提问分析 → 让 AI 先理解问题2. /plan → AI 产出方案，你审批（简单改动） /spec → AI 产出完整规格，你审批（复杂功能）3. 执行 → AI 按计划实施4. 验证 → 你检查结果，发现问题就指出5. 记录 → 必要时更新 AGENTS.md / Rules- 直接让 AI 写代码 → 应该先分析，再计划，再执行
- AGENTS.md 写得太长 → AI 理解力反而下降，精简才是王道
- 大功能只用 /plan → 复杂功能应该用
/spec生成完整规格，避免遗漏 - 不验证就提交 → AI 可能遗漏、写错，你必须检查
- 把 AI 当全能 → AI 擅长模式匹配和代码生成，但架构决策需要你来做
以一次完整的迭代为例：
# 阶段 1：初始化（只需一次）你：生成项目的 AGENTS.md 文件你：AGENTS.md 再精简！只保留 AI 需要知道的信息→ 产出：精简的 AGENTS.md
# 阶段 2：分析与计划你：分析一下当前的性能瓶颈你：/plan 在尽量小改动的情况下优化查询→ 产出：优化方案文档
# 阶段 3：执行与纠错AI：修改相关文件...你：你确定改完了？再检查看看AI：补全遗漏的修改，清理残留代码→ 产出：所有文件修改完成
# 阶段 4：验证与提交你：帮我构建一下，看看有没有问题你：没问题的话帮我 commit→ 产出：构建通过，git commit 完成这就是一个完整的 AI 编程迭代周期。记住：你是导演，AI 是演员。好的导演懂得先写剧本（AGENTS.md + Rules），再分镜（/plan），然后才开拍（执行），最后还要审片（验证）。