Harness Step 3: 建立跨 Session 状态管理

目标

创建三个文件，让 agent 在任何新 session 开始时能在 30 秒内恢复工作状态：

• init.sh：环境初始化脚本，验证项目可以正常启动
• tasks.json：当前任务清单，agent 的工作指令来源
• progress.md：人类可读的进度摘要，记录每次 session 的关键信息

核心原则：状态靠文件传递，不靠 agent 的记忆。git log 是主记录，这三个文件是辅助。

---

执行步骤

Step 1：扫描项目启动方式

在写 init.sh 之前，先确认项目如何启动和测试：

# 读 package.json 的 scripts（Node.js 项目）
cat package.json 2>/dev/null | grep -A 20 '"scripts"'

# 或读 Makefile（多语言项目）
cat Makefile 2>/dev/null | head -40

# 或读 pyproject.toml（Python 项目）
cat pyproject.toml 2>/dev/null | grep -A 20 '\[tool.poetry.scripts\]'

# 确认现有 AGENTS.md 里的启动命令
grep -A 5 '启动命令\|start\|dev\|run' AGENTS.md 2>/dev/null

收集：

• 开发服务器启动命令
• 测试命令
• 类型检查/lint 命令（如果有）
• 有没有需要先跑的初始化步骤（如数据库迁移）

---

Step 2：创建 init.sh

init.sh 的作用：每次 session 开始时运行，快速验证环境是否正常，不正常就立即修复再继续。

#!/bin/bash
# init.sh — 每次 session 开始时运行
# 验证开发环境处于可工作状态

set -e  # 任何步骤失败就停止

echo "=== 检查环境 ==="

# 1. 确认在正确目录
echo "工作目录: $(pwd)"

# 2. 安装依赖（如果 node_modules 不存在）
# [根据技术栈选择，以下是示例]
# Node.js:
if [ ! -d "node_modules" ]; then
  echo "安装依赖..."
  npm install
fi

# 3. 冒烟测试：验证项目能正常启动
# [根据项目实际情况写，目标是用最快的方式验证基本功能正常]
# 示例：跑一个最快的测试
# npm run test -- --testPathPattern=smoke 2>/dev/null || echo "警告：冒烟测试失败，请先修复"

echo "=== 环境检查完成，可以开始工作 ==="
echo "提示：运行 'git log --oneline -10' 查看最近工作历史"

写作要求：

• 根据扫描到的实际启动命令填写，不要留示例注释
• 冒烟测试要快（< 30秒），目的是快速发现环境问题，不是跑完整测试套件
• 如果项目有数据库，加一步检查数据库连接是否正常
• 写完后实际运行一遍，确认脚本无报错：bash init.sh

---

Step 3：创建 tasks.json

结构设计：

{
  "project": "[项目名]",
  "last_updated": "[今天日期，格式 YYYY-MM-DD]",
  "current_focus": "[当前最重要的一件事，一句话]",
  "tasks": [
    {
      "id": "[模块缩写]-[序号]",
      "title": "[任务标题]",
      "description": "[具体做什么，1-3句话]",
      "status": "pending | in_progress | done | blocked",
      "priority": "high | medium | low",
      "blocked_by": "[阻塞原因，仅 blocked 状态时填写]",
      "verify": "[如何验证这个任务完成了]",
      "requires_eval": false
    }
  ]
}

字段说明（每次新增任务时必须逐字段填写，不能省略）：

字段	是否必填	说明
id	必填	模块缩写 + 序号，如 auth-01、ui-03，简短可读
title	必填	任务标题，一句话
description	必填	具体做什么，1-3 句话
status	必填	初始值为 pending，由 agent 工作时更新
priority	必填	high / medium / low
blocked_by	仅 blocked 时填	阻塞原因
verify	必填	如何验证完成，必须是可执行的步骤（命令或操作）
requires_eval	必填	是否需要独立 Evaluator 评审，默认 false，见判断标准

requires_eval 判断标准（新增任务时必须对照判断，不能不加思考直接填 false）：

设为 true 的条件，满足任意一条即需要评审：

• 这是一个新功能（不只是修 bug 或改配置）
• 涉及安全、权限、数据校验相关逻辑
• 预计会修改 3 个以上文件
• 任务描述里有"重构"或"架构调整"

设为 false 的条件（以下全部满足才可以跳过评审）：

• 纯 bug 修复，改动范围明确
• 文档更新、注释补充
• 配置调整、环境变量修改
• 单元测试补充

如何确定初始任务列表：

优先从以下来源提取：

1. docs/exec-plans/active/ 里的计划文件（如果有）
2. docs/exec-plans/tech-debt-tracker.md 里的高优先级债务
3. README 里提到的 TODO 或路线图
4. 询问用户：「当前最想推进的 3-5 个任务是什么？」

写作要求：

• verify 字段必须是可执行的步骤，不能写"确认功能正常"这种废话
• 任务粒度：一个任务应该在 1-2 小时内完成，太大的拆分
• 初始状态：所有任务都是 pending，由 agent 工作时更新

询问用户（如果无法从现有文档推断任务）：

我已经扫描了项目，准备创建任务清单。请告诉我： 当前最想推进的 3-5 个任务是什么？ 每个任务用一句话描述就行。

---

Step 4：创建 progress.md

初始内容：

# 项目进度记录

> 每次 session 完成任务后，在顶部追加记录。不要删除历史。
> 格式：## [日期] [任务名]

---

## [今天日期] 初始化 Harness

- 完成 harness-step1：建立 docs/ 骨架
- 完成 harness-step2：填充知识库内容
- 完成 harness-step3：建立状态管理
- tasks.json 初始任务数：[N] 个
- 下次从这里开始：读 tasks.json，选 priority=high 且 status=pending 的任务开始

---

Step 4b：更新 AGENTS.md —— 写入任务管理规则

找到 AGENTS.md 里 step2 写入的"每次完成一个任务后"部分，替换为以下内容：

### 新增任务时，必须：
1. 填写 tasks.json 里的所有字段，不能省略
2. 对照以下标准判断 `requires_eval`，不能默认填 false 不加思考：
   - 新功能 / 涉及安全权限 / 改动超过 3 个文件 / 重构 → true
   - 纯 bug 修复 / 文档更新 / 配置调整 → false

### 每次完成一个任务后，必须按顺序执行：
1. 执行 `tasks.json` 里该任务 `verify` 字段描述的验证步骤
2. 若该任务 `requires_eval` 为 `true`：填写 `sprint_output.md`，等待 Evaluator 评审通过后才能标记 `done`
   若该任务 `requires_eval` 为 `false`：验证通过即可标记 `done`
3. git commit，格式：`type(scope): 做了什么，遗留了什么（如有）`
4. 在 `progress.md` 顶部追加本次记录

**禁止**：跳过 verify 步骤自行判断任务已完成。
**禁止**：不经判断直接把 `requires_eval` 设为 false。

---

Step 5：验证整体联动

三个文件创建完后，模拟一次完整的 session 启动流程，验证联动是否正常：

# 模拟 agent 新 session 开始的操作序列
echo "=== 模拟新 session 启动 ==="

# 1. 跑 init.sh
bash init.sh

# 2. 看 git log
git log --oneline -10

# 3. 读 progress.md（确认文件存在且可读）
head -20 progress.md

# 4. 读 tasks.json（确认格式正确）
cat tasks.json | python3 -m json.tool > /dev/null && echo "tasks.json 格式正确" || echo "tasks.json 格式有误"

全部通过才算完成。

---

质量检验

• init.sh 实际运行无报错？
• tasks.json JSON 格式合法？每个任务都有 verify 和 requires_eval 字段？
• 每个任务的 requires_eval 是否对照判断标准填写，而非默认 false？
• progress.md 有初始记录？
• AGENTS.md 里是否包含新增任务和完成任务的两条规则？

---

完成后告知用户

输出摘要：

创建的文件：

• init.sh：[描述做了什么检查]
• tasks.json：[N] 个任务，其中需要 Evaluator 评审的 [N] 个
• progress.md：已初始化

如何使用：

现在你可以把项目交给 Claude Code 了。它每次启动时会自动读这三个文件 + git log， 恢复工作状态。你不需要每次都解释"上次做到哪里了"。

需要你做的事：

• 检查 tasks.json 里的任务列表是否符合你的预期，可以手动增删
• 确认 requires_eval 的判断是否合理
• 如果 init.sh 有步骤失败，告诉我，我来修复

下一步：

• Harness 地基已完成（step1 + step2 + step3）
• 可以开始正式使用 Claude Code 开发
• 遇到 agent 反复违反代码规范时，运行 harness-step4-linter，把规则变成机械约束
• 遇到 agent 自评不可信时，运行 harness-step5-evaluator，引入独立评审