这是一篇由原始材料转换而来的阅读页，保留了源文件的主要结构，并补充了可追溯的来源说明与链接。

AGENTS.md — OpenAI 风格的 Codex 工程 Harness（中文版）

这个文件应当 刻意保持简短。 它是 地图，不是百科全书。

目标：让编码 agent 进入一个仓库后，能快速找到正确上下文、安全推进，并在离开时把系统整理得比来时更好。

0）核心理念

1. 仓库才是事实来源 没写进仓库的知识，默认 agent 不能可靠依赖。

2. AGENTS.md 是目录，不是手册 这个文件保持短小稳定；详细知识放在 docs/ 和 plans/。

3. 计划是一等工件 复杂任务必须写成版本化计划文件，不能只留在 prompt 或聊天记录里。

4. 把重要约束机械化 架构边界、质量要求、命名规范、依赖方向等，应尽量交给脚本、lint、CI、结构测试来执行。

5. 反馈回路比直觉更可靠 优先让 agent 能通过脚本、浏览器自动化、日志、指标、追踪、冒烟测试来验证行为。

1）仓库最小结构要求

至少暴露这些入口：

• AGENTS.md
• init.sh
• progress.md
• feature_list.json
• docs/
• plans/
• scripts/ 或 tools/

建议文档布局：

• docs/index.md — 总地图
• docs/architecture/ — 分层、领域、约束
• docs/product/ — 用户行为与需求
• docs/runbooks/ — 启动、调试、部署、回滚
• docs/quality/ — lint / test / CI 规则
• docs/debt/ — 技术债与清理目标

建议计划布局：

• plans/active/
• plans/done/
• plans/templates/

2）每次会话的启动流程

每次编码会话，必须先做：

1. 确认位置与当前健康状态

pwd
ls
git status
git log --oneline -20

2. 阅读地图与最近交接

sed -n '1,200p' AGENTS.md
sed -n '1,200p' progress.md || true
sed -n '1,200p' docs/index.md || true

3. 查看活跃计划与未完成功能

find plans/active -maxdepth 2 -type f 2>/dev/null | sort
head -n 160 feature_list.json 2>/dev/null || true

4. 运行环境启动与冒烟测试

bash ./init.sh

如果 init.sh 失败，先把基线修绿，再开始新功能。

3）如何选择工作

小任务

当改动： - 范围小 - 好验证 - 不太可能跨多会话

可以只在 progress.md 里记录轻量计划。

复杂任务

当改动涉及： - 多子系统 - 架构调整 - 迁移 - UI 与后端联动 - 回滚 / 验证逻辑复杂

必须在 plans/active/ 新建或更新执行计划。

计划至少应写清： - 目标 - 范围 / 非目标 - 假设 - 约束 - 执行步骤 - 验证步骤 - 回滚路径 - 决策日志 - 当前状态

4）实施规则

1. 每次会话只做一个连贯增量
2. 不验证，不算完成
3. 不要依赖未落库的人类知识；如果某条规则/决策重要，就写进仓库
4. 优先复用已有脚本，而不是临时命令；如果某命令会反复用，就把它做成脚本
5. 发现重复故障模式时，优先修 harness，而不只修症状

5）验证层级

优先使用更强的验证闭环：

1. 静态检查 / lint
2. 单测与集成测试
3. init.sh 冒烟测试
4. 浏览器 / UI 验证
5. 日志 / 指标 / traces 运行时确认

只有走完合适的端到端验证，某个功能才能改成 passes: true。

6）会话收尾与交接

会话结束前：

1. 更新 progress.md，至少写： - 本次目标 - 改了哪些文件 - 跑了哪些命令 - 结果如何 - 已知问题 / 风险 - 下一步建议

2. 更新相关的 plans/active/ 计划

3. 只有在验证充分时才更新 feature_list.json
4. 干净提交

git add -A
git commit -m "feat: <简短说明>"
git status

7）Codex CLI 启动模板

给新仓库补 harness

codex exec -m gpt-5.4 -C <REPO_DIR> --full-auto - <<'PROMPT'
你要为这个仓库初始化一套 OpenAI 风格的 Codex harness。

创建或完善以下工件：
- AGENTS.md（只做短地图）
- docs/index.md
- init.sh
- progress.md
- feature_list.json
- plans/active/
- plans/done/
- plans/templates/exec-plan.md

不要实现产品功能。
运行一次 init.sh；如果前置条件缺失，准确写入文档。
最后提交：
"chore: initialize codex harness"
PROMPT

执行一个计划内增量

codex exec -m gpt-5.4 -C <REPO_DIR> --full-auto - <<'PROMPT'
你是 coding agent。

流程：
1) 读 AGENTS.md、progress.md、docs/index.md
2) 查看 plans/active 与 feature_list.json
3) 运行 bash ./init.sh
4) 选择一个连贯增量
5) 实现并验证
6) 更新 progress.md 和相关计划
7) 只有验证通过后才把 feature_list.json 的 passes 设为 true
8) 干净提交

如果发现仓库知识缺失，把知识补进 docs，而不是留在隐性上下文里。
PROMPT

跑一轮文档花园整理

codex exec -m gpt-5.4 -C <REPO_DIR> --full-auto - <<'PROMPT'
你是 doc-gardening agent。

审计文档：
- 是否过时
- 是否缺交叉链接
- 是否与代码不一致
- 高频变更区域是否缺 runbook / architecture note

只做文档 / harness / lint 相关改进。
提交信息：
"docs: garden repository knowledge"
PROMPT