一套 main-agent / sub-agent 协作约定，从一个实验驱动的研究仓库里长出来、抽掉项目特有内容后的通用版。
main-agent = Claude Code（和用户对话的那层）；sub-agent 载体可换——Claude Code 的
Agent 工具，或一个跑在 tmux 里的常驻 Codex。规矩是同一套，只是坐在那个位置上的换了人。
main-agent 要克制。 别自己扎进 code 和大文件——一深入细节就迷失，还污染主线。重活下放， 只读 report，自己待在沟通高度。判断该不该下放，成本轴是上下文污染，不是任务时长。
活文档和日志分开。 CONTEXT.md 是对齐的出发点：user / main-agent / sub-agent 都从这里
拿到同一个起点，保持精简、会被反复压缩。PROGRESS.md / RESULTS.md 是 append-only 的日志。
稳定的规矩两个都不放——放宪法或独立契约文件，否则早晚在某次压缩里被当成过期内容清掉。
sub-agent 没有 commit 权。 它只写文件 + 汇报，由 main-agent review 后提交。这不是不信任， 是逼它别闷头跑完、而是多次回来对齐；也逼 main-agent 真的看过 diff 才签字。
sub-agent 不碰别的分支。 连"调查 / 侦察"也不例外——别的分支常有相似或竞争的实现，一读就 被带偏。没有 control 就没有 context。
thread 会死，CONTEXT.md 不会。 别指望 sub-agent 的会话长命；持久的记忆落在它维护的活文档里。
规矩别写两遍。 一条规矩写在两个文件里，就一定会漂——这不是纪律问题，是结构问题。 镜像文件要如实写明「我可能落后于源」，并规定发现冲突时报告而不是默默照旧执行。
中途插话能进去，但边界不由你定。 直接打字是排队，会在轮中送达——不用等整轮结束；
但送达点是「控制权回到模型」那一刻，模型常把多条命令打成一批发出，那就得等整批回来。
esc 是真打断（当前轮作废、在跑的活丢掉），不是温和插入。所以长跑的活派出去时仍要把话说全。
派活是异步的，而且必须按轮次绑定。 派出去就走，用完成通知把自己叫醒，别循环轮询——前台 阻塞等待意味着它跑多久你卡多久。等结果要绑定到「这一轮」（turn id），不能按「日志里下一个 完成事件」：延迟刷盘、resume、用户中途插话都会让你拿到上一轮的答复——一个看着完全合理的 错答案。认不出自己那一轮就报错，一个字都别返回。
plan 不是固定流程，是 main-agent 买信息。 要不要先让 sub-agent 交 plan，取决于 main-agent 对这活的上下文有多少把握——它知道而你不知道的时候才值钱。刚聊完的追问、 边界清楚的补充，走 plan 是纯开销。
| 文件 | 是什么 | 谁读 |
|---|---|---|
CLAUDE.md |
宪法 = 这套规矩的源。用户所有 | main-agent（Claude），常驻上下文 |
AGENTS.md |
同一套规矩的 codex 侧镜像。两层：通用层原样可搬，本仓库层换仓库时替换 | codex，起会话自动读 |
.claude/skills/codex_as_subagent/ |
怎么操作 codex sub-agent：异步模型 + 读事件 + 踩过的坑。零规矩 | main-agent，按需加载 |
docs/WORKFLOW.md |
worktree / 分支合并配方（并发时才用） | 需要时 |
三者的关系是有向的：宪法是源 → AGENTS.md 是它对 codex 的投影 → skill 完全不碰规矩。
同一条规矩别写两遍——两处都写必然漂移。
CLAUDE.md拷进你的仓库根目录，按需增删。AGENTS.md拷进去，通用层原样保留，把<!-- 本仓库层 -->那节整个换成你自己项目的 内容（项目是什么、目录约定、活文档入口、临时区、领域契约）。- skill 拷进
.claude/skills/。要用 codex 当 sub-agent 时它才会被加载。 - 两边规矩改动必须同步，冲突以
CLAUDE.md为准。注意这是给人看的约定： codex 启动只加载AGENTS.md链、不会自动读CLAUDE.md，所以「以源为准」没有运行时效力 ——真正管用的是AGENTS.md里那条「发现冲突就报告 main-agent」。
skill 里有全部机制，这里只说形状：tmux 里常驻一个真 codex TUI（用户随时 tmux attach
进去看、直接打字，跟 main-agent 共用同一个它）；main-agent 把消息送进 tmux，然后读 codex
自己落在 ~/.codex/sessions/.../rollout-*.jsonl 的结构化事件，用 task_complete /
last_agent_message 精确判定和取答复——不抓屏、不拿中间文件传话。
会话断了用 codex resume <session-id> 接回来（它续写同一个 rollout 文件，所以绑定不用重认）。
规矩不用在消息里交代：AGENTS.md 在仓库里，codex 自己读。在提示词里再抄一遍规则 = 第二份
真相，必然漂移——这个坑我们真踩过。
