协作规则要入 Git 才算项目资产

更新于 2026-07-25

**写给 agent 的协作规则（`AGENTS.md`、`.codex/`、`.agents/`、rules 等）如果被 `.gitignore` 挡在外面，就只在自己本机有效，不是项目资产 —— 换机器、换协作者、换 agent、换 worktree 都会丢。**

配套判断

  • 规则文件要像代码一样入 Git，才能被版本化、被他人复用。
  • 规则里少写「会变的事实」：写死的「当前分支是 2.0」在主线变成 main 后就过期，反而误导。多写稳定的硬规则，少写随时漂移的现状快照。

症状：新 worktree 里 hook 不生效

在独立 worktree 里测 hook 完全没反应，不是「分支禁用了 hook」，而是未跟踪的文件不会随 worktree 出现：

  • 主工作区有 .qoder/settings.json 和 hook 脚本，两个 worktree 里连 .qoder/ 目录都没有。
  • 根 .gitignore 的规则挡住了 .qoder/，git ls-files -- .qoder 为空 —— 配置从未被跟踪。
  • 新建 worktree 只检出该分支已提交的文件，被忽略的配置自然不在，平台也就没有可注册的 hook。

修法：.gitignore 放行（!/.qoder/）→ 提交配置与 hooks → 合入或 cherry-pick 到需要的分支；已有 worktree 更新到该提交后才生效。同理 .trellis/ 等平台目录若希望所有 worktree 行为一致，也必须是 Git 跟踪的项目文件。

相关