harness-step3-session-management

Name: harness-step3-session-management
Author: simbajigege

65installs21forks

How to install harness-step3-session-management?

simbajigege/book2skills/harness-step3-session-management

$npx -y skills add simbajigege/book2skills --skill harness-step3-session-management

Installs into the current project.

Summary

Harness Engineering 第二阶段：建立跨 session 状态管理，解决 agent 每次对话失忆的问题。创建 tasks.json（任务清单）、progress.md（进度记录）、init.sh（环境初始化脚本）三个文件。当用户说"建立任务管理"、"让 agent 记住进度"、"创建 tasks.json"、"跨 session 保持状态"、 "agent 每次都不记得上次做了什么"、"建立 progress 文件"、"初始化状态管理"时，立即使用此 skill。前置条件：harness-step1 和 harness-step2

Files · 1

View on GitHub

SKILL.md

1	# Harness Step 3: 建立跨 Session 状态管理
2
3	## 目标
4
5	创建三个文件，让 agent 在任何新 session 开始时能在 30 秒内恢复工作状态：
6
7	- `init.sh`：环境初始化脚本，验证项目可以正常启动
8	- `tasks.json`：当前任务清单，agent 的工作指令来源
9	- `progress.md`：人类可读的进度摘要，记录每次 session 的关键信息
10
11	核心原则：状态靠文件传递，不靠 agent 的记忆。git log 是主记录，这三个文件是辅助。
12
13	---
14
15	## 执行步骤
16
17	### Step 1：扫描项目启动方式
18
19	在写 `init.sh` 之前，先确认项目如何启动和测试：
20
21	```bash
22	# 读 package.json 的 scripts（Node.js 项目）
23	cat package.json 2>/dev/null \| grep -A 20 '"scripts"'
24
25	# 或读 Makefile（多语言项目）
26	cat Makefile 2>/dev/null \| head -40
27
28	# 或读 pyproject.toml（Python 项目）
29	cat pyproject.toml 2>/dev/null \| grep -A 20 '\[tool.poetry.scripts\]'
30
31	# 确认现有 AGENTS.md 里的启动命令
32	grep -A 5 '启动命令\\|start\\|dev\\|run' AGENTS.md 2>/dev/null
33	```
34
35	收集：
36	- 开发服务器启动命令
37	- 测试命令
38	- 类型检查/lint 命令（如果有）
39	- 有没有需要先跑的初始化步骤（如数据库迁移）
40
41	---
42
43	### Step 2：创建 `init.sh`
44
45	`init.sh` 的作用：每次 session 开始时运行，快速验证环境是否正常，不正常就立即修复再继续。
46
47	```bash
48	#!/bin/bash
49	# init.sh — 每次 session 开始时运行
50	# 验证开发环境处于可工作状态
51
52	set -e # 任何步骤失败就停止
53
54	echo "=== 检查环境 ==="
55
56	# 1. 确认在正确目录
57	echo "工作目录: $(pwd)"
58
59	# 2. 安装依赖（如果 node_modules 不存在）
60	# [根据技术栈选择，以下是示例]
61	# Node.js:
62	if [ ! -d "node_modules" ]; then
63	echo "安装依赖..."
64	npm install
65	fi
66
67	# 3. 冒烟测试：验证项目能正常启动
68	# [根据项目实际情况写，目标是用最快的方式验证基本功能正常]
69	# 示例：跑一个最快的测试
70	# npm run test -- --testPathPattern=smoke 2>/dev/null \|\| echo "警告：冒烟测试失败，请先修复"
71
72	echo "=== 环境检查完成，可以开始工作 ==="
73	echo "提示：运行 'git log --oneline -10' 查看最近工作历史"
74	```
75
76	写作要求：
77	- 根据扫描到的实际启动命令填写，不要留示例注释
78	- 冒烟测试要快（< 30秒），目的是快速发现环境问题，不是跑完整测试套件
79	- 如果项目有数据库，加一步检查数据库连接是否正常
80	- 写完后实际运行一遍，确认脚本无报错：`bash init.sh`
81
82	---
83
84	### Step 3：创建 `tasks.json`
85
86	结构设计：
87
88	```json
89	{
90	"project": "[项目名]",
91	"last_updated": "[今天日期，格式 YYYY-MM-DD]",
92	"current_focus": "[当前最重要的一件事，一句话]",
93	"tasks": [
94	{
95	"id": "[模块缩写]-[序号]",
96	"title": "[任务标题]",
97	"description": "[具体做什么，1-3句话]",
98	"status": "pending \| in_progress \| done \| blocked",
99	"priority": "high \| medium \| low",
100	"blocked_by": "[阻塞原因，仅 blocked 状态时填写]",
101	"verify": "[如何验证这个任务完成了]",
102	"requires_eval": false
103	}
104	]
105	}
106	```
107
108	字段说明（每次新增任务时必须逐字段填写，不能省略）：
109
110	\| 字段 \| 是否必填 \| 说明 \|
111	\|------\|----------\|------\|
112	\| `id` \| 必填 \| 模块缩写 + 序号，如 `auth-01`、`ui-03`，简短可读 \|
113	\| `title` \| 必填 \| 任务标题，一句话 \|
114	\| `description` \| 必填 \| 具体做什么，1-3 句话 \|
115	\| `status` \| 必填 \| 初始值为 `pending`，由 agent 工作时更新 \|
116	\| `priority` \| 必填 \| `high / medium / low` \|
117	\| `blocked_by` \| 仅 blocked 时填 \| 阻塞原因 \|
118	\| `verify` \| 必填 \| 如何验证完成，必须是可执行的步骤（命令或操作） \|
119	\| `requires_eval` \| 必填 \| 是否需要独立 Evaluator 评审，默认 `false`，见判断标准 \|
120
121	`requires_eval` 判断标准（新增任务时必须对照判断，不能不加思考直接填 false）：
122
123	设为 `true` 的条件，满足任意一条即需要评审：
124	- 这是一个新功能（不只是修 bug 或改配置）
125	- 涉及安全、权限、数据校验相关逻辑
126	- 预计会修改 3 个以上文件
127	- 任务描述里有"重构"或"架构调整"
128
129	设为 `false` 的条件（以下全部满足才可以跳过评审）：
130	- 纯 bug 修复，改动范围明确
131	- 文档更新、注释补充
132	- 配置调整、环境变量修改
133	- 单元测试补充
134
135	如何确定初始任务列表：
136
137	优先从以下来源提取：
138	1. `docs/exec-plans/active/` 里的计划文件（如果有）
139	2. `docs/exec-plans/tech-debt-tracker.md` 里的高优先级债务
140	3. README 里提到的 TODO 或路线图
141	4. 询问用户：「当前最想推进的 3-5 个任务是什么？」
142
143	写作要求：
144	- `verify` 字段必须是可执行的步骤，不能写"确认功能正常"这种废话
145	- 任务粒度：一个任务应该在 1-2 小时内完成，太大的拆分
146	- 初始状态：所有任务都是 `pending`，由 agent 工作时更新
147
148	询问用户（如果无法从现有文档推断任务）：
149
150	> 我已经扫描了项目，准备创建任务清单。请告诉我：
151	> 当前最想推进的 3-5 个任务是什么？
152	> 每个任务用一句话描述就行。
153
154	---
155
156	### Step 4：创建 `progress.md`
157
158	初始内容：
159
160	```markdown
161	# 项目进度记录
162
163	> 每次 session 完成任务后，在顶部追加记录。不要删除历史。
164	> 格式：## [日期] [任务名]
165
166	---
167
168	## [今天日期] 初始化 Harness
169
170	- 完成 harness-step1：建立 docs/ 骨架
171	- 完成 harness-step2：填充知识库内容
172	- 完成 harness-step3：建立状态管理
173	- tasks.json 初始任务数：[N] 个
174	- 下次从这里开始：读 tasks.json，选 priority=high 且 status=pending 的任务开始
175	```
176
177	---
178
179	### Step 4b：更新 `AGENTS.md` —— 写入任务管理规则
180
181	找到 `AGENTS.md` 里 step2 写入的"每次完成一个任务后"部分，替换为以下内容：
182
183	```markdown
184	### 新增任务时，必须：
185	1. 填写 tasks.json 里的所有字段，不能省略
186	2. 对照以下标准判断 `requires_eval`，不能默认填 false 不加思考：
187	- 新功能 / 涉及安全权限 / 改动超过 3 个文件 / 重构 → true
188	- 纯 bug 修复 / 文档更新 / 配置调整 → false
189
190	### 每次完成一个任务后，必须按顺序执行：
191	1. 执行 `tasks.json` 里该任务 `verify` 字段描述的验证步骤
192	2. 若该任务 `requires_eval` 为 `true`：填写 `sprint_output.md`，等待 Evaluator 评审通过后才能标记 `done`
193	若该任务 `requires_eval` 为 `false`：验证通过即可标记 `done`
194	3. git commit，格式：`type(scope): 做了什么，遗留了什么（如有）`
195	4. 在 `progress.md` 顶部追加本次记录
196
197	禁止：跳过 verify 步骤自行判断任务已完成。
198	禁止：不经判断直接把 `requires_eval` 设为 false。
199	```
200
201	---
202
203	### Step 5：验证整体联动
204
205	三个文件创建完后，模拟一次完整的 session 启动流程，验证联动是否正常：
206
207	```bash
208	# 模拟 agent 新 session 开始的操作序列
209	echo "=== 模拟新 session 启动 ==="
210
211	# 1. 跑 init.sh
212	bash init.sh
213
214	# 2. 看 git log
215	git log --oneline -10
216
217	# 3. 读 progress.md（确认文件存在且可读）
218	head -20 progress.md
219
220	# 4. 读 tasks.json（确认格式正确）
221	cat tasks.json \| python3 -m json.tool > /dev/null && echo "tasks.json 格式正确" \|\| echo "tasks.json 格式有误"
222	```
223
224	全部通过才算完成。
225
226	---
227
228	## 质量检验
229
230	- [ ] `init.sh` 实际运行无报错？
231	- [ ] `tasks.json` JSON 格式合法？每个任务都有 `verify` 和 `requires_eval` 字段？
232	- [ ] 每个任务的 `requires_eval` 是否对照判断标准填写，而非默认 false？
233	- [ ] `progress.md` 有初始记录？
234	- [ ] `AGENTS.md` 里是否包含新增任务和完成任务的两条规则？
235
236	---
237
238	## 完成后告知用户

People who liked this also viewed

6 picks

Type

harness-step3-session-management

65installs21forks

View on GitHub

How to install harness-step3-session-management?

simbajigege/book2skills/harness-step3-session-management

$npx -y skills add simbajigege/book2skills --skill harness-step3-session-management

Installs into the current project.

Summary

Files · 1

View on GitHub

SKILL.md

1	# Harness Step 3: 建立跨 Session 状态管理
2
3	## 目标
4
5	创建三个文件，让 agent 在任何新 session 开始时能在 30 秒内恢复工作状态：
6
7	- `init.sh`：环境初始化脚本，验证项目可以正常启动
8	- `tasks.json`：当前任务清单，agent 的工作指令来源
9	- `progress.md`：人类可读的进度摘要，记录每次 session 的关键信息
10
11	核心原则：状态靠文件传递，不靠 agent 的记忆。git log 是主记录，这三个文件是辅助。
12
13	---
14
15	## 执行步骤
16
17	### Step 1：扫描项目启动方式
18
19	在写 `init.sh` 之前，先确认项目如何启动和测试：
20
21	```bash
22	# 读 package.json 的 scripts（Node.js 项目）
23	cat package.json 2>/dev/null \| grep -A 20 '"scripts"'
24
25	# 或读 Makefile（多语言项目）
26	cat Makefile 2>/dev/null \| head -40
27
28	# 或读 pyproject.toml（Python 项目）
29	cat pyproject.toml 2>/dev/null \| grep -A 20 '\[tool.poetry.scripts\]'
30
31	# 确认现有 AGENTS.md 里的启动命令
32	grep -A 5 '启动命令\\|start\\|dev\\|run' AGENTS.md 2>/dev/null
33	```
34
35	收集：
36	- 开发服务器启动命令
37	- 测试命令
38	- 类型检查/lint 命令（如果有）
39	- 有没有需要先跑的初始化步骤（如数据库迁移）
40
41	---
42
43	### Step 2：创建 `init.sh`
44
45	`init.sh` 的作用：每次 session 开始时运行，快速验证环境是否正常，不正常就立即修复再继续。
46
47	```bash
48	#!/bin/bash
49	# init.sh — 每次 session 开始时运行
50	# 验证开发环境处于可工作状态
51
52	set -e # 任何步骤失败就停止
53
54	echo "=== 检查环境 ==="
55
56	# 1. 确认在正确目录
57	echo "工作目录: $(pwd)"
58
59	# 2. 安装依赖（如果 node_modules 不存在）
60	# [根据技术栈选择，以下是示例]
61	# Node.js:
62	if [ ! -d "node_modules" ]; then
63	echo "安装依赖..."
64	npm install
65	fi
66
67	# 3. 冒烟测试：验证项目能正常启动
68	# [根据项目实际情况写，目标是用最快的方式验证基本功能正常]
69	# 示例：跑一个最快的测试
70	# npm run test -- --testPathPattern=smoke 2>/dev/null \|\| echo "警告：冒烟测试失败，请先修复"
71
72	echo "=== 环境检查完成，可以开始工作 ==="
73	echo "提示：运行 'git log --oneline -10' 查看最近工作历史"
74	```
75
76	写作要求：
77	- 根据扫描到的实际启动命令填写，不要留示例注释
78	- 冒烟测试要快（< 30秒），目的是快速发现环境问题，不是跑完整测试套件
79	- 如果项目有数据库，加一步检查数据库连接是否正常
80	- 写完后实际运行一遍，确认脚本无报错：`bash init.sh`
81
82	---
83
84	### Step 3：创建 `tasks.json`
85
86	结构设计：
87
88	```json
89	{
90	"project": "[项目名]",
91	"last_updated": "[今天日期，格式 YYYY-MM-DD]",
92	"current_focus": "[当前最重要的一件事，一句话]",
93	"tasks": [
94	{
95	"id": "[模块缩写]-[序号]",
96	"title": "[任务标题]",
97	"description": "[具体做什么，1-3句话]",
98	"status": "pending \| in_progress \| done \| blocked",
99	"priority": "high \| medium \| low",
100	"blocked_by": "[阻塞原因，仅 blocked 状态时填写]",
101	"verify": "[如何验证这个任务完成了]",
102	"requires_eval": false
103	}
104	]
105	}
106	```
107
108	字段说明（每次新增任务时必须逐字段填写，不能省略）：
109
110	\| 字段 \| 是否必填 \| 说明 \|
111	\|------\|----------\|------\|
112	\| `id` \| 必填 \| 模块缩写 + 序号，如 `auth-01`、`ui-03`，简短可读 \|
113	\| `title` \| 必填 \| 任务标题，一句话 \|
114	\| `description` \| 必填 \| 具体做什么，1-3 句话 \|
115	\| `status` \| 必填 \| 初始值为 `pending`，由 agent 工作时更新 \|
116	\| `priority` \| 必填 \| `high / medium / low` \|
117	\| `blocked_by` \| 仅 blocked 时填 \| 阻塞原因 \|
118	\| `verify` \| 必填 \| 如何验证完成，必须是可执行的步骤（命令或操作） \|
119	\| `requires_eval` \| 必填 \| 是否需要独立 Evaluator 评审，默认 `false`，见判断标准 \|
120
121	`requires_eval` 判断标准（新增任务时必须对照判断，不能不加思考直接填 false）：
122
123	设为 `true` 的条件，满足任意一条即需要评审：
124	- 这是一个新功能（不只是修 bug 或改配置）
125	- 涉及安全、权限、数据校验相关逻辑
126	- 预计会修改 3 个以上文件
127	- 任务描述里有"重构"或"架构调整"
128
129	设为 `false` 的条件（以下全部满足才可以跳过评审）：
130	- 纯 bug 修复，改动范围明确
131	- 文档更新、注释补充
132	- 配置调整、环境变量修改
133	- 单元测试补充
134
135	如何确定初始任务列表：
136
137	优先从以下来源提取：
138	1. `docs/exec-plans/active/` 里的计划文件（如果有）
139	2. `docs/exec-plans/tech-debt-tracker.md` 里的高优先级债务
140	3. README 里提到的 TODO 或路线图
141	4. 询问用户：「当前最想推进的 3-5 个任务是什么？」
142
143	写作要求：
144	- `verify` 字段必须是可执行的步骤，不能写"确认功能正常"这种废话
145	- 任务粒度：一个任务应该在 1-2 小时内完成，太大的拆分
146	- 初始状态：所有任务都是 `pending`，由 agent 工作时更新
147
148	询问用户（如果无法从现有文档推断任务）：
149
150	> 我已经扫描了项目，准备创建任务清单。请告诉我：
151	> 当前最想推进的 3-5 个任务是什么？
152	> 每个任务用一句话描述就行。
153
154	---
155
156	### Step 4：创建 `progress.md`
157
158	初始内容：
159
160	```markdown
161	# 项目进度记录
162
163	> 每次 session 完成任务后，在顶部追加记录。不要删除历史。
164	> 格式：## [日期] [任务名]
165
166	---
167
168	## [今天日期] 初始化 Harness
169
170	- 完成 harness-step1：建立 docs/ 骨架
171	- 完成 harness-step2：填充知识库内容
172	- 完成 harness-step3：建立状态管理
173	- tasks.json 初始任务数：[N] 个
174	- 下次从这里开始：读 tasks.json，选 priority=high 且 status=pending 的任务开始
175	```
176
177	---
178
179	### Step 4b：更新 `AGENTS.md` —— 写入任务管理规则
180
181	找到 `AGENTS.md` 里 step2 写入的"每次完成一个任务后"部分，替换为以下内容：
182
183	```markdown
184	### 新增任务时，必须：
185	1. 填写 tasks.json 里的所有字段，不能省略
186	2. 对照以下标准判断 `requires_eval`，不能默认填 false 不加思考：
187	- 新功能 / 涉及安全权限 / 改动超过 3 个文件 / 重构 → true
188	- 纯 bug 修复 / 文档更新 / 配置调整 → false
189
190	### 每次完成一个任务后，必须按顺序执行：
191	1. 执行 `tasks.json` 里该任务 `verify` 字段描述的验证步骤
192	2. 若该任务 `requires_eval` 为 `true`：填写 `sprint_output.md`，等待 Evaluator 评审通过后才能标记 `done`
193	若该任务 `requires_eval` 为 `false`：验证通过即可标记 `done`
194	3. git commit，格式：`type(scope): 做了什么，遗留了什么（如有）`
195	4. 在 `progress.md` 顶部追加本次记录
196
197	禁止：跳过 verify 步骤自行判断任务已完成。
198	禁止：不经判断直接把 `requires_eval` 设为 false。
199	```
200
201	---
202
203	### Step 5：验证整体联动
204
205	三个文件创建完后，模拟一次完整的 session 启动流程，验证联动是否正常：
206
207	```bash
208	# 模拟 agent 新 session 开始的操作序列
209	echo "=== 模拟新 session 启动 ==="
210
211	# 1. 跑 init.sh
212	bash init.sh
213
214	# 2. 看 git log
215	git log --oneline -10
216
217	# 3. 读 progress.md（确认文件存在且可读）
218	head -20 progress.md
219
220	# 4. 读 tasks.json（确认格式正确）
221	cat tasks.json \| python3 -m json.tool > /dev/null && echo "tasks.json 格式正确" \|\| echo "tasks.json 格式有误"
222	```
223
224	全部通过才算完成。
225
226	---
227
228	## 质量检验
229
230	- [ ] `init.sh` 实际运行无报错？
231	- [ ] `tasks.json` JSON 格式合法？每个任务都有 `verify` 和 `requires_eval` 字段？
232	- [ ] 每个任务的 `requires_eval` 是否对照判断标准填写，而非默认 false？
233	- [ ] `progress.md` 有初始记录？
234	- [ ] `AGENTS.md` 里是否包含新增任务和完成任务的两条规则？
235
236	---
237
238	## 完成后告知用户

People who liked this also viewed

6 picks

Type