这篇能做出什么
跟着做完，你会得到一个「一个目录、一个智能体、两类活」的工作区：
- 项目根目录同时放代码和文档，智能体不用在两个入口之间搬上下文；
- 你能用同一套「派活模板」描述编码任务（改接口、补测试）和日常事务任务（整理周报、把零散笔记变成待办）；
- 你知道权限开在哪一档：读、写、跑命令分别怎么放；
- 你能用三个可观测的指标，量出「切任务」到底花了多少成本，而不是凭感觉说"合并以后方便了"。
下面这套流程不依赖具体版本号。界面上按钮叫什么，以官方文档当前版本为准；如果措辞和本文不同，按功能对应即可。
前置条件清单
- TRAE 桌面客户端，登录可用账号（版本以官方文档当前版本为准）；
- 一份本地项目目录，建议是你能随便改、可回滚的小项目，别拿生产仓库练手；
- Git 会用基本命令（
status/diff/restore），这是你的安全网； - 一份可以公开的示例文档，用来跑日常事务类任务；
- 半小时到一小时的不被打断时间。
先建一个练习用的目录结构，后面的例子都基于它：
```text
my-workspace/
├── AI 词典：AGENTS.md">AGENTS.md
├── apps/
│ └── demo-api/
│ └── src/
└── docs/
├── notes.md
└── weekly.md
```
分步骤
第 1 步：确认合并后的入口，只打开项目根目录
Code 与 Work 合并之后，实际操作上最大的变化是：不再需要为「写代码」和「写文档」分别进不同的入口，而是先有工作区，再在工作区里下任务。你要做的第一件事，是把工作区绑定到一个明确的项目根目录。
两个原则：
1. 打开的是项目根，不是用户主目录，更不是整个磁盘。 目录越大，索引越慢，智能体越容易被无关文件带偏。
2. 代码和文档放同一个根下。 合并的意义就在这里——智能体能同时看到 apps/ 和 docs/。
打开后确认一下：文件树里能同时看到代码目录和文档目录。看不到，说明你打开的是子目录，退回去重开。
第 2 步：写一份项目规则文件，当作智能体的员工手册
合并之后，两类任务共用一个工作区，规则文件就成了唯一的"公共约束"。放在项目根，命名常见的是 AGENTS.md，具体读哪个文件名以官方文档当前版本为准。
```markdown
项目约定
技术栈
- 运行时与依赖版本以 package.json 为准
- 包管理器：npm
常用命令
- 安装依赖：npm ci
- 跑测试：npm test
- 启动本地服务：npm run dev
边界
- 不要修改 .env、密钥文件、CI 配置
- 不要执行 git push、git reset --hard、rm -rf
- 不要新增第三方依赖，除非在计划里说明并获得确认
- 改动前先给出计划，改动后给出验收证据
文档约定
- 周报放 docs/weekly.md，按「本周完成 / 进行中 / 阻塞 / 下周计划」分段
- 结论写进 docs/decision-log.md，不要在对话里口头结论
```
这份文件的价值在于：它把"每次都要重复交代的背景"变成了一次性投入。合并后任务类型变多，重复交代的成本会被放大，所以这一步值得认真写。
第 3 步：派一个编码任务
给智能体派活，最省事的写法是四段式：目标、范围、验收、约束。
```text
目标：在 apps/demo-api 里增加一个 GET /healthz 接口，返回 {"status":"ok"}
范围：只修改 apps/demo-api/src 下的文件，不要动依赖清单
验收：npm test 通过；本地启动后 curl 该路径返回 200 且响应体为上述 JSON
约束：不新增依赖；先给计划，等我确认再动手；改完贴出 git diff 摘要
```
执行顺序建议固定成：先要计划 → 确认 → 让它改 → 你看 diff → 跑验收命令。
```bash
你自己在终端跑一遍，不要只听它说
git status
git diff
npm test
```
如果一次改了太多文件，用 git restore 退回，然后把任务再拆小。拆到"一次改动能在 5 分钟内看完 diff"是比较舒服的粒度。
第 4 步：在同一个工作区派一个日常事务任务
这是合并之后比较有意思的部分：不用出工作区，直接让它处理文档。
```text
目标：读取 docs/notes.md，整理成一份周报写入 docs/weekly.md
要求：
- 按「本周完成 / 进行中 / 阻塞 / 下周计划」四段组织
- 每条不超过两行，保留原文里的日期
- 原文没有的信息标注「待确认」，不要自行补充或推测
- 写完只输出改动摘要，不要把全文贴回对话
```
关键差异在于：编码任务要的是"能跑的代码"，事务任务要的是"可追溯的文本"。所以在事务任务里，"不要编造"要比"写得漂亮"更重要，把它明确写进约束里。
反过来也一样好用——你可以在编码任务里引用文档：
```text
按 docs/decision-log.md 里 3 月那条决定，把接口命名统一成复数形式，只改 apps/demo-api/src 下的路由定义，先列出会被改到的文件清单。
```
这就是合并带来的实际收益：上下文不用在两个入口之间手工搬运。
第 5 步：把权限分三档，别一刀切
派活之前先决定权限。建议按三档处理：
| 能力 | 建议档位 | 说明 |
|---|---|---|
| 读工作区内文件 | 允许 | 只读，风险低 |
| 写工作区内文件 | 每次确认，或限定目录 | 配合 Git 使用 |
| 执行终端命令 | 白名单 + 每次确认 | 只放 npm test、git status 这类 |
| 访问网络 | 需要装依赖时临时打开 | 用完关掉 |
| 写工作区外路径 | 关闭 | 包括家目录、系统目录 |
| 推送代码 / 改 CI | 关闭 | 需要时人工做 |
判断标准很简单：这条能力如果被误用，你能不能在五分钟内恢复？ 能，就适度放开；不能，就保持确认。
第 6 步：量一下上下文切换的实际成本
"合并以后更顺手"这句话要用数字支撑。挑三个可观测指标，在同一工作区里连续跑三个任务（编码 → 文档 → 编码），记录：
1. 启动成本：从上一条任务结束，到新任务开始产出，你手动操作了几次、花了多久；
2. 补背景量：新任务开始前，你额外打了多少字交代背景；
3. 回滚成本：出错后恢复到干净状态花了几分钟。
然后做一次对照：同样的三个任务，一次全部在同一个长会话里做，一次每个任务开一个新会话（保留项目规则文件）。
多数情况下你会看到这样的规律：任务之间共享文件、且单个任务不长时，开新会话 + 规则文件 + 结论文件的组合，补背景量更低；而把一个长任务硬塞进同一会话，才是上下文变脏的主因。
对应的习惯是：任务结束时让它把结论落盘，而不是留在对话里。
```text
把这一轮的结论写入 docs/decision-log.md，包含三部分：
1) 改了什么文件和原因 2) 验收方式与结果 3) 还没做完的事和下一步
不要重复贴代码，只写文件路径和一句话说明。
```
下一次开新会话，你只需要一句：
```text
读 docs/decision-log.md，从「还没做完的事」这一节继续。
```
第 7 步：多个任务并行时，用文件当看板
如果同时派多个任务，先在根目录建一个 TASKS.md，把"谁改哪个文件"写清楚，避免两个任务同时写同一个文件。
```markdown
TASKS
- [ ] T1 增加 /healthz 接口 —— 负责：agent-a —— 涉及：apps/demo-api/src/routes*
- [ ] T2 整理 docs/notes.md 为周报 —— 负责：agent-b —— 涉及：docs/weekly.md
- [ ] T3 为 T1 补测试 —— 依赖 T1 完成 —— 涉及：apps/demo-api/test*
```
规则只有两条：一个文件同时只被一个任务写；有依赖关系的任务串行做。
常见坑与排错
坑 1：把主目录或整个磁盘当工作区。
表现是索引慢、回答里混进无关文件。排错：只打开项目根，重启工作区重新索引。
坑 2：智能体改了不该改的文件。
多数是因为规则文件没写禁区，同时写权限放得太宽。排错：git status 看清单，git restore <file> 回滚，然后把禁区补进 AGENTS.md。
坑 3：它说"已完成"，其实没跑通。
原因是任务里没有可验证的验收标准。排错：把"验收"写成一条具体命令加预期输出，并要求贴出命令结果。
坑 4：编码任务里混进文档内容，回答开始跑偏。
这是长会话的典型症状。排错：开新会话，用 decision-log.md 交接，不要靠"接着上面说"。
坑 5：命令跑不起来。
常见是依赖没装或环境变量缺失。排错：先明确包管理器（npm / pnpm / yarn 只用一种），让它按规则文件里的命令执行安装；.env 缺失的部分由你手工补，别让它猜。
坑 6：权限弹窗点到手酸，索性全放开。
更好的做法是把反复出现的、只读的命令加进允许列表，写操作保持确认。放开的是"高频低危"，不是"全部"。
坑 7：合并后找不到以前习惯的入口。
功能合并会带来位置变化，去哪里找以实现官方文档当前版本为准。不建议为了"找回旧入口"去装第三方插件或改配置。
坑 8：路径带空格或中文导致命令失败。
命令里给路径加引号，或者一开始就把项目放在纯英文、无空格的路径下。
下一步建议
1. 把 AGENTS.md 当团队资产维护。 每次踩坑就往里加一条，这份文件的回报是复利的。
2. 坚持"结论落盘"。 把 decision-log.md 用起来，任务之间的交接靠文件，不靠对话记忆。
3. 权限按最小必要给。 新任务从只读开始，需要写再逐档放开。
4. 先跑一个真实但可回滚的小任务。 比如给内部小工具加一个健康检查接口，同时把本周会议记录整理成文档，两类任务各跑一遍，你就能感受到合并后上下文切换的实际手感。
5. 任务拆到小。 派活的难度不在描述得漂亮，而在把任务切到"一次能验收"的粒度。
具体的入口位置、模式命名、能力开关清单，不同版本会调整，以官方文档当前版本为准；本文给出的方法不依赖这些细节，换版本也能照用。