AI 编码工作流模板（Trae 专用）

只装四份 Markdown：一条规则、两个技能、一张地图，让 Trae 每次先查地图、再动手。

只面向 Trae。 规则写进 .trae/rules/，技能放进 .trae/skills/，都走 Trae 原生约定。 不生成 AGENTS.md、CLAUDE.md、.cursor/ 这类给其他工具的第二份配置。

装进项目的只有：

| 文件 | 作用 | 谁维护 | | ------------------------------- | -------------------------------------------- | -------------------------- | | .trae/rules/00-core.md | 每轮常驻的规则：技术栈、命令、固定动作、禁区 | 安装器生成一次，之后由你改 | | .trae/skills/codemap/SKILL.md | 按需加载：怎么读、怎么更新地图 | 安装器生成，一般不用改 | | .trae/skills/settle/SKILL.md | 按需加载：收尾时判断写进规则、地图还是技能 | 安装器生成，一般不用改 | | .trae/documents/CODE_MAP.md | 地图本体：模块职责、定位路由、关键文件、坑 | 人和模型一起改 |

没有脚本、没有 pre-commit 钩子、没有后台任务。装完就能提交。

安装

在项目根目录执行一条命令：

npx -y zt-ai-workflow@latest .

环境要求：Node ≥ 16.7，零依赖。git 不是必需的。

带 @latest 是为了绕过 npx 的本地缓存，确保拿到最新版。 安装器只写四份文件，不执行你的构建/测试命令，也不联网。

装完做什么

1. 打开 .trae/rules/00-core.md，核对「技术栈」和「命令」。没有测试或 lint 就明确写出来，否则模型会假装跑过。
2. 在 Trae 里问一个「改这个功能要动哪些文件」的问题。第一次地图是空的，模型会先搜索；收尾时让它按 settle 判断、按 codemap 落盘，把真实路径补进「定位路由」。
3. 提交这四份文件：

git add .trae
git commit -m "chore: 接入 ai-workflow"

之后每次改完代码，收尾时更新 .trae/documents/CODE_MAP.md 里受影响的行和顶部「最后更新」即可。

装完的项目结构就是这四份文件，加上你原来的代码：

your-project/
  .trae/
    rules/00-core.md
    skills/codemap/SKILL.md
    skills/settle/SKILL.md
    documents/CODE_MAP.md
  src/...

从 0.2.x 升级

0.3.0 起不再生成脚本、地图和钩子，settle 技能保留为必备。旧项目升级：

1. 先删掉旧版残留： scripts/、docs/routes.json、docs/CODE_MAP.auto.md、.trae/skills/conventions/、旧的 .trae/skills/settle/。
2. 在项目根目录重新跑一次 npx -y zt-ai-workflow@latest .：补齐四份文件，已有的规则和地图不会被覆盖。
3. 如果旧版有 docs/CODE_MAP.md，安装器会把内容复制到 .trae/documents/CODE_MAP.md；确认无误后删掉旧文件。
4. 删掉旧钩子：rm .git/hooks/pre-commit（确认里面只有本方案的内容）。
5. 提交：git add .trae && git commit -m "chore: 切换到四文件方案"。

安装器只提示、不自动删除，避免误删你改过的内容。

合并规则

• 没装过 → 新建四份文件。
• 装过 → 缺什么补什么；已存在的文件一律保留，不覆盖你改过的规则和地图。
• 项目里已经有别人的 .trae/rules/00-core.md → 不覆盖，只提示；其他规则文件原样并存。
• 旧版装过的 scripts/、docs/routes.json、docs/CODE_MAP.auto.md 等 → 只提示可清理，不擅自删除。
• 目标目录还是空项目（没有清单文件、源码很少）→ 不安装，只给一句提示。

为什么不是脚本

四份文件的方案把「地图新鲜度」交给规则和技能里的纪律：

• 规则要求：定位类回答第一行写依据——命中地图写 依据：CODE_MAP（最后更新：日期），地图未收录则写明搜索范围；没读地图不许回答。收尾先按 settle 分流，新增/移动/删除模块必须更新地图路径。
• codemap 技能要求：按 settle 的判定落盘，单次最多 3 条，全篇控制在 60 行内；地图与代码冲突时以代码为准。
• settle 技能要求：写之前先判断该进规则、地图还是技能；三条门槛都满足才写，路径变化属于必写项。

代价是：地图可能被忘记更新，而且没有提交前拦截。换来的是装进项目零脚本、零钩子、零依赖，升级和删除都只是四个 Markdown 文件。

如果你需要强制的过期检查，那属于另一套方案；这个模板刻意不做。

它不做什么

• 不生成代码地图、不做指纹校验、不装 pre-commit 钩子
• 不提供 adopt / draft / check 之类的子命令
• 不兼容 Cursor、Claude Code、Copilot 等其他编辑器
• 不批量处理多个项目，也不托管任何后台任务

只做一件事：把规则、两个技能、地图四份文件放进项目，其余交给 Trae 和你的纪律。

常见问题

地图会不会过期？ 会。它靠纪律维护，不靠指纹比对。发现过期时直接改，或让 Trae 按 codemap 技能重写对应段。

codemap 和 settle 怎么分工？ codemap 管地图本身：什么时候读、怎么写、写多少。settle 管一次任务结束后的归类：这条经验该进规则、地图、技能，还是根本不写。

多个项目怎么办？ 在每个项目根目录各跑一次 npx -y zt-ai-workflow@latest .。没有批量模式，也没有额外子命令。

以后模板升级了，已有项目怎么更新？ 重新跑安装命令只会补缺失文件，不会覆盖已有内容。想更新技能内容：先删掉 .trae/skills/codemap/ 或 .trae/skills/settle/ 再跑，或者对比仓库里的 template/ 手动替换。规则和地图按项目实际情况合并。

能卸载吗？ 删掉 .trae/rules/00-core.md、.trae/skills/codemap/、.trae/skills/settle/ 和 .trae/documents/CODE_MAP.md 即可，没有残留。

仓库结构

bin/
  aiw.mjs      CLI 入口：解析目录、--help、--version
  init.mjs     探测技术栈 → 渲染四份文件 → 已存在则保留
  lib.mjs      项目状态、清单目录、空项目判定
template/
  rules-00-core.md
  skills/codemap/SKILL.md
  skills/settle/SKILL.md
  CODE_MAP.md
test/smoke.mjs

开发：npm test。