Imported from HK-AI-Security-Lab/cc_codex_collab (AGENTS.md). Install upstream with npx skills add HK-AI-Security-Lab/cc_codex_collab. Copyright stays with the author.

AGENTS.md

本文件是所有 AI Agent（Claude Code、Codex 等）在本仓库工作时的唯一真源（SSOT）。CLAUDE.md 通过 @AGENTS.md 引用本文件，确保两边工具看到完全一致的协作规则。

项目概览

TODO(项目维护者)：用 2-4 句话描述本项目的目标、主要产物与边界。

常用命令

开发环境配置

# TODO(项目维护者)：填写本项目的环境安装命令

测试

# TODO(项目维护者)：填写本项目的测试命令

Lint / Format / Type Check

# TODO(项目维护者)：填写本项目的检查命令

运行 / 构建 / 发布

# TODO(项目维护者)：填写本项目的关键运行或构建命令

代码架构

TODO(项目维护者)：列出本项目最重要的模块、目录、执行流与设计约束。

代码风格

基本要求

• 使用项目既有的代码风格与目录结构，不擅自重排模块边界。
• 导入、命名、注释、测试风格优先遵循仓库现状，而不是 agent 自己的偏好。
• 若项目已有 lint / formatter / type checker，以仓库配置为准。

改动原则

• 优先做最小可验证改动，不做无关重构。
• 涉及非显然的技术选择时，必须在 .agent/decisions.md 记录 ADR。

多 Agent 协作

可能会有多个 AI Agent（Claude Code、Codex 等）在本仓库并发或交替工作。为保持协调，所有 agent 必须读写 .agent/ 目录 —— 这是入 git 的共享工作记忆。

语言约定： .agent/ 下的所有文件统一使用中文撰写。若团队决定改成英文，请一次性全局修改，不要在同一项目中混用。

项目蓝图： .agent/blueprint.md 是本项目的方法蓝图 / PRD / 实施说明入口。首次进入仓库、任务涉及方法选择 / 阶段设计、或实现偏离现有方案时，务必阅读相关章节；其余情况按需回查。任何偏离必须在 decisions.md 中记录原因。

上下文节流原则： .agent/ 只保留会被多轮复用的共享记忆，避免文档膨胀影响模型上下文。能写进现有文件的内容不要新开文件；新增文件默认应是“按需查阅”，而不是“每轮必读”。

目录分层约定： .agent/ 根目录只放热入口与少量稳定参考；冷材料按类别进入一层子目录。当前允许的分类目录为：notes/（调研 / 设计笔记）、reports/（实验 / 结果报告）、archive/（归档历史）。不要继续做两层以上嵌套。

会话开始最小必读

1. .agent/state.md —— 热状态板：当前阶段、进行中、下一步、最近完成。
2. .agent/handoff.md —— 最近交接（热日志，只保留最近 4–6 条；先看最新 1–3 条）。
3. .agent/open-questions.md —— 仅看等待用户输入的阻塞项。

按需查阅

1. .agent/index.md —— 首次进入仓库、或 .agent/ 新增文件时再看。
2. .agent/progress.md —— 阶段计划、长期 TODO、完整完成记录（冷文档，不是热状态板）。
3. .agent/goals.md —— 任务涉及范围、成功标准、里程碑时再看。
4. .agent/metrics.md —— 任务涉及 benchmark、eval、KPI、retro 写作时再看。
5. .agent/review-workflow.md —— 任务涉及 review gate、插件协作、阶段边界 commit 时再看。
6. .agent/notes/ —— 任务涉及历史摸底、设计推导、实现前调研时再看。
7. .agent/reports/ —— 任务涉及实验结果、smoke/full run 分析、结果快照时再看。
8. .agent/blueprint.md —— 任务涉及方法选择、阶段设计、或偏离蓝图时再回查相关章节。

回合结束写入规则

1. 若本回合改变了共享状态（任务归属、阶段推进、实验结果、关键结论），更新 state.md。只保留热信息，不把长历史再写回热文件。
2. 若本回合产出了值得下一位 agent 接续的信息，追加 handoff.md。当 handoff.md 超过 6 条时，将旧条目归档到 .agent/archive/handoff-YYYY-MM.md。
3. 若做了非显然的决策，在 decisions.md 追加一条 ADR（背景、决策、影响）。
4. 若卡住或需要用户澄清，记录到 open-questions.md。
5. 纯问答、只读分析、或未改变共享状态时，不强制更新 .agent/。

并发协作规约

• 在 state.md 中用 [in-progress: claude] / [in-progress: codex] 标注正在做的事，避免另一个 agent 重复劳动。
• 频繁提交（即使是 WIP），让另一个 agent 通过 git pull / 重新读取看到最新变更。
• 若发现某项已被另一个 agent 标为 [in-progress]，请挑别的任务，或通过 handoff.md 协调。

Claude Code + Codex 插件协作建议

• 在 Claude Code 中工作时，默认将 Codex 插件视为review / rescue 辅助层，而不是长期编排器；.agent/ 仍是跨回合 SSOT。
• 首次在该仓库启用 Claude Code 协作时，执行一次：

/codex:setup --enable-review-gate

• review gate 与 /codex:review / /codex:adversarial-review 只负责 review，不替代 .agent/ 的共享记忆、任务认领、handoff、ADR 与热状态维护。
• 只要任务涉及长程并行实现、多轮接力、复杂调试、跨回合上下文维护，优先保留独立 Codex terminal，与 Claude Code 通过 AGENTS.md + .agent/ 协同。
• 详细的 commit / review / rescue 编排规则移到 .agent/review-workflow.md，需要时再查，避免每轮把 workflow 细则灌进主上下文。

内容归属

不要把协作文件放到公开文档目录（如 docs/）下，除非你明确希望它们进入外部发布链路。