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

AGENTS.md — 长任务 Agent Harness 作业指令（可直接启动）

本文件用于“跨多次会话 / 跨 context window”的编码 Agent 接力。

核心原则：每次会话都像换班工程师——先验收当前状态，再做一个小增量，最后留下可复盘的工件并 git commit。

本模板面向在本机用 Codex CLI（codex） 驱动的工作流（可交互、也可 codex exec 非交互）。

0) 硬性规则（必须遵守）

1. 禁止“一次性做完”：每次会话只完成 1 个可验收的功能项（或 1 个小修复）。
2. 禁止“自我宣布完成”：只有在端到端验证后，才能把功能项标记为通过（passes: true）。
3. 会话结束必须是“可合并状态”： - git status 应保持干净（除非在 progress.md 明确记录原因） - 关键改动必须落到 commit（git 是可回滚记忆）
4. 相信工件，不相信记忆：下一次会话只以仓库文件与 git 历史为准。

1) Harness 工件（Artifacts）约定

建议把这些文件放在项目仓库根目录（如果放子目录，必须在本文件写清楚路径）：

• init.sh
• 一键：启动开发环境 + 冒烟测试

• 目标：任何新会话先跑它，快速判断“当前是否绿色”

• feature_list.json

• 端到端功能清单（JSON），每项含 passes: false/true

• 后续 coding agent 只允许改 passes 字段（必要时可追加新条目，但不要改旧条目的语义）

• progress.md（或 progress.log）

• 交接本：每次会话追加一段（只追加，不覆盖）

• 建议包含：日期时间、目标、做了什么、跑了哪些命令、结果、commit、下一步

• Git history

• 每次会话结束都 git commit：它是“可回滚、可追溯”的外置记忆

本仓库模板文件在：/srv/project/harness-engineering/templates/*

2) 每次会话的标准流程（Coding Agent 必走）

2.1 先“找状态”（目标：5 分钟内完成）

按顺序执行：

1) 确认位置与仓库状态

pwd
ls
git status

2) 阅读最近交接

test -f progress.md && sed -n '1,200p' progress.md || true

3) 看最近提交

git log --oneline -20

4) 读取功能清单并选择一个未通过的最高优先级条目

test -f feature_list.json && cat feature_list.json | head -n 120 || true

5) 启动并冒烟测试（必须）

bash ./init.sh

• 如果冒烟测试失败：先修到通过，不要直接开始新功能。

2.2 只做一个功能项（增量推进）

• 实现 → 测试（单测 + e2e/人工步骤）→ 修 bug → 再测试
• 通过验证后，在 feature_list.json 将对应条目的 passes 改为 true

2.3 会话收尾（交接 + 提交）

1) 追加 progress.md（至少包含） - 本次完成的功能项（引用 feature_list.json 的 description） - 关键文件变更摘要 - 运行过的命令（尤其是启动/测试命令） - 结果（通过/失败点） - 新增风险与 TODO - 下一步建议（下一位一上来应该做什么）

2) 确保工作区干净并提交

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

3) 最终确认

git status

3) Codex CLI：可直接复制的启动命令

下面命令中的 <REPO_DIR> 请替换为你的仓库目录（例如：/srv/project/repos/myapp）。

3.1 Initializer（第一次：只搭骨架，不做功能）

Initializer 的产物目标： - 生成 init.sh / feature_list.json / progress.md - 做一次初始 commit（形成可回滚基线）

推荐用 codex exec 非交互执行：

codex exec -m gpt-5.4 -C <REPO_DIR> --full-auto - <<'PROMPT'
你是 initializer agent。你的任务不是实现功能，而是为“长任务/多会话接力”建立 harness。

要求：
1) 在仓库根目录创建：init.sh、feature_list.json、progress.md。
2) init.sh 必须能：安装/检查依赖（按仓库实际情况）、启动开发环境、跑最小冒烟测试；失败要退出非 0。
3) feature_list.json：根据仓库 README/现有代码，整理端到端功能清单；所有 passes 初始为 false。
4) progress.md：写入第一条交接记录（你创建了哪些工件、如何运行 init.sh、下一步怎么做）。
5) 运行一次 bash ./init.sh 验证脚本可用（如果需要先安装依赖，请把命令写进 progress.md）。
6) 完成后执行 git add/commit，commit message："chore: initialize agent harness"。

注意：不要尝试“一次性做完项目”。你的产出是可持续接力的工程骨架。
PROMPT

如果你希望交互式（更像结对编程），可用：

codex -m gpt-5.4 -C <REPO_DIR>

3.2 Coding Agent（后续每次：只推进一个 passes=false）

同样建议用 codex exec，把流程写死到 prompt，强制它“先验收再推进”：

codex exec -m gpt-5.4 -C <REPO_DIR> --full-auto - <<'PROMPT'
你是 coding agent（换班工程师）。目标：只完成一个 passes=false 的功能项，并在会话结束留下干净状态。

流程（必须执行，并把关键命令/结果记录到 progress.md）：
1) git status；git log --oneline -20
2) 阅读 progress.md 与 feature_list.json
3) 运行 bash ./init.sh 做冒烟测试；如果失败先修复到通过
4) 选择一个 passes=false 的最高优先级功能项，只做这一个
5) 实现 + 测试（要求端到端验证）；验证后将该条 passes 改为 true
6) 更新 progress.md（做了什么、命令、结果、commit、下一步）
7) git add -A && git commit -m "feat: <功能项简短说明>"
8) 确保 git status 干净
PROMPT

3.3 续跑 / 恢复上次 Codex 会话（可选）

如果你之前用交互式 codex，想继续最近一次会话：

codex resume --last

4) 为什么功能清单用 JSON（很关键）

• Markdown 更容易被模型“顺手改写需求文本/排序/合并段落”
• JSON 结构更刚性，更利于约束“只改 passes”

5) 落地自检清单

• [ ] init.sh 在新环境可运行（至少能告诉我缺什么依赖）
• [ ] feature_list.json 是端到端行为清单，不是模块/文件列表
• [ ] progress.md 只追加，不覆盖
• [ ] 每次会话结束都有 commit，且能回滚到任意绿色状态