harness-step2-fill-docs

Name: harness-step2-fill-docs
Author: simbajigege

71installs21forks

How to install harness-step2-fill-docs?

simbajigege/book2skills/harness-step2-fill-docs

$npx -y skills add simbajigege/book2skills --skill harness-step2-fill-docs

Installs into the current project.

Summary

Harness Engineering 第一阶段第二步：深度分析项目代码，填充业务解决方案、架构、约定、技术决策和质量标准等 docs/ 知识库内容。在 harness-step1-create-agents-md 创建好目录骨架之后使用。当用户说"填充文档内容"、 "完善 docs/ 文件"、"让文档有实质内容"、"分析项目写架构文档"、"写 ARCHITECTURE.md"、 "写技术决策文档"、"从业务视角理解项目"、"完善 business-solution.md"时，立即使用此 skill。前置条件：项目中已有 AGENTS.md 和 do

Files · 1

View on GitHub

SKILL.md

1	# Harness Step 2: 填充 docs/ 知识库内容
2
3	## 目标
4
5	通过深度阅读项目代码，将隐藏在代码里的业务能力、用户流程、架构知识、命名约定、技术决策，
6	显式地写入 docs/ 各文件。让 agent 在任何 session 都能快速理解项目全貌。
7
8	核心原则：推断出来的内容要标注来源，无法确定的内容标注「待补充」，
9	不要用模糊的占位符糊弄过去。
10
11	---
12
13	## 执行步骤
14
15	### Step 1：深度扫描
16
17	在写任何文档之前，先充分读懂项目。按顺序执行：
18
19	```bash
20	# 1. 确认 docs/ 骨架已存在
21	ls docs/
22
23	# 2. 读懂目录结构（3层）
24	find . -maxdepth 3 \
25	-not -path '/node_modules/' -not -path '/.git/' \
26	-not -path '/__pycache__/' -not -path '/dist/' \
27	-not -path '/.next/' -not -path '/build/' \| sort
28
29	# 3. 读主要入口文件
30	# （根据技术栈判断：main.ts / main.py / app.go / index.js 等）
31
32	# 4. 读模块边界（各主要目录的 index 文件或第一个文件）
33	# 目标：搞清楚每个目录的职责
34
35	# 5. 读依赖声明
36	cat package.json 2>/dev/null \|\| cat pyproject.toml 2>/dev/null \|\| \
37	cat go.mod 2>/dev/null \|\| cat Cargo.toml 2>/dev/null
38
39	# 6. 读已有文档（复用，不重复）
40	cat README.md 2>/dev/null
41	cat AGENTS.md 2>/dev/null
42	```
43
44	扫描目标——在写文档前，必须能回答这些问题：
45	- 这个项目服务哪些用户/角色？他们要完成什么任务？
46	- 它解决哪些业务痛点，哪些能力已经由页面、路由、API 或 service 实现？
47	- 用户从输入资料/发起操作到得到业务结果的核心流程是什么？
48	- 哪些只是 README 宣传、路线图或合理二开设想，尚不能视为现有能力？
49	- 这个项目分成哪几个主要模块？每个模块做什么？
50	- 代码调用链是怎样的？（UI → ? → ? → 数据层）
51	- 用了哪些主要的库/框架？能推断出选择原因吗？
52	- 文件命名有什么规律？变量命名有什么规律？
53	- 什么情况会导致测试失败？验收标准是什么？
54
55	---
56
57	### Step 2：写 `docs/business-solution.md`
58
59	写什么：从业务和需求视角说明项目服务谁、解决什么问题、如何产生价值，以及能力边界。不要把技术组件清单改写成业务价值，也不要把路线图或设想当成现有功能。
60
61	⚠️ 强制要求：业务能力必须验证可见入口或执行链路
62
63	README 可以用于发现候选能力，但在写“系统可以完成 X”之前，至少找到以下一种证据：
64	- 用户入口：页面、CLI command、API route、IM/Embed/MCP 接口
65	- 执行链路：handler/service/use case、任务 worker 或 provider registry
66	- 验证材料：对应测试、API 文档、正式产品文档
67
68	推荐搜索方法：
69
70	```bash
71	# 从路由和页面验证用户可见能力
72	rg -n "path:\|Register.*Routes\|\.GET\(\|\.POST\(" frontend/src/router internal/router
73
74	# 从业务对象和服务验证执行能力
75	rg -n "type .Service\|func New.Service\|Create\|Search\|Import\|Sync\|Evaluate" internal/application
76
77	# 区分已实现、路线图和待办
78	rg -n "Roadmap\|TODO\|planned\|coming soon\|路线图\|规划" README.md docs/ frontend/ internal/
79	```
80
81	每项能力标记证据状态：
82	- 已验证：找到入口和执行/文档证据
83	- 部分验证：只有单侧证据，明确缺失什么
84	- 待补充：目标行业、商业模式、业务指标等仓库无法确定的信息
85
86	格式模板：
87
88	```markdown
89	# 业务解决方案
90
91	## 一句话定位
92	[服务谁，用什么方式，解决什么核心问题]
93
94	## 目标用户与核心任务
95	\| 用户/角色 \| 核心任务 \| 当前痛点 \|
96	\|---\|---\|---\|
97
98	## 问题—能力—价值映射
99	\| 业务问题 \| 已验证能力 \| 产生的价值 \| 证据 \|
100	\|---\|---\|---\|---\|
101
102	## 典型业务场景
103	[3-8 个由代码/产品文档支持的场景，每个说明参与者、输入、过程和结果]
104
105	## 核心业务流程
106	[从用户输入到获得结果的端到端流程]
107
108	## 能力边界
109	- [不适用场景、依赖条件、安全/人工审核要求]
110
111	## 二次开发机会
112	[明确标注为建议，不得混入现有能力]
113
114	## 待补充
115	- [ ] [目标行业、指标、商业规则等需业务负责人确认的内容]
116	```
117
118	写作要求：
119	- 使用用户能理解的语言，先写任务和结果，再提技术实现
120	- “支持某集成”不等于“业务闭环已完成”，必须描述它在流程中的作用
121	- 不承诺无法从代码或文档确认的性能、准确率、合规等级和 SLA
122	- 能力边界至少覆盖数据质量、权限、高风险操作人工确认和运营维护
123
124	---
125
126	### Step 3：写 `docs/ARCHITECTURE.md`
127
128	写什么：模块划分、依赖方向、主要数据流。写"是什么结构"和"为什么这样分"，不写具体实现。
129
130	⚠️ 强制要求：描述组件/模块关系前，必须验证 import
131
132	写任何"A 被 B 使用"、"A 内嵌了 B"、"A 页面包含 C 组件"这类断言之前，
133	必须用 Grep 确认实际 import，不得根据文件名或目录位置猜测。
134
135	```bash
136	# 验证某组件是否被某页面实际引用
137	grep -r "ChatInterface" frontend/src/app/[locale]/book/[bookCode]/ 2>/dev/null
138
139	# 验证某组件被哪些文件实际引用
140	grep -rl "ComponentName" src/ 2>/dev/null
141	```
142
143	如果 grep 无结果，说明没有引用关系——即使组件在同一目录下也不能断言它被使用。
144	未经验证的关系统一标注「待验证：未找到 import，请人工确认」。
145
146	格式模板：
147
148	```markdown
149	# 架构说明
150
151	## 整体结构
152	[用文字描述整体分层，再用目录树辅助说明]
153
154	[目录树，只到关键层级，不要穷举所有文件]
155
156	## 依赖方向规则
157	[用箭头图或列表说明哪层可以引用哪层]
158
159	关键约束：
160	- [约束1，说明原因]
161	- [约束2，说明原因]
162
163	## 主要数据流
164	[描述最核心的 1-2 条请求/数据流，从入口到数据库]
165
166	## 待补充
167	- [ ] [扫描时无法确定的内容]
168	```
169
170	写作要求：
171	- 依赖规则要具体，不要写"保持清晰的分层"这种废话
172	- 每条约束附上原因（"不要在 UI 层调 DB，因为……"）
173	- 无法从代码推断的内容，明确标注「待补充：需人工确认」
174
175	---
176
177	### Step 4：写 `docs/CONVENTIONS.md`
178
179	写什么：从代码里归纳出来的命名规律和文件组织规律。
180
181	扫描方法：
182	```bash
183	# 看文件命名规律
184	find src -name ".ts" -o -name ".py" -o -name "*.go" 2>/dev/null \| head -30
185
186	# 看函数/变量命名（随机抽几个文件）
187	head -50 [主要源文件路径]
188	```
189
190	格式模板：
191
192	```markdown
193	# 代码约定
194
195	## 文件命名
196	- [规律1]：示例 `XxxYyy.tsx`
197	- [规律2]：示例 `xxx-yyy.ts`
198
199	## 变量和函数命名
200	- 变量/函数：[规律 + 示例]
201	- 类/组件：[规律 + 示例]
202	- 常量：[规律 + 示例]
203
204	## 目录组织
205	[每个主要目录放什么类型的文件]
206
207	## Git Commit 格式
208	[从 git log 里归纳，或写推荐格式]
209	`type(scope): 描述`
210	type 可选：feat / fix / docs / refactor / test
211
212	## 待补充
213	- [ ] [无法从代码推断的约定]
214	```
215
216	写作要求：
217	- 每条规律附上从代码中观察到的实例
218	- 如果代码本身命名不一致，如实写出来并标注「当前不一致，建议统一为……」
219	- 不要发明项目里没有的约定
220
221	---
222
223	### Step 5：写 `docs/TECH_DECISIONS.md`
224
225	写什么：技术选型的原因。这是最难写的一份，因为原因往往不在代码里。
226
227	扫描方法：
228	```bash
229	# 看所有直接依赖
230	cat package.json \| grep '"dependencies"' -A 50 2>/dev/null
231	# 或
232	cat pyproject.toml \| grep -A 30 '\[tool.poetry.dependencies\]' 2>/dev/null
233	```
234
235	格式模板：
236
237	```markdown
238	# 技术决策记录
239
240	## [框架/库名]
241	用途：[这个库/框架用来做什么]
242	选择原因：[能推断出的原因，或标注「待补充」]
243	替代方案：[如果明显有替代品，列出并说明为何不选]
244	注意事项：[使用时需要特别注意的地方]
245
246	## 待补充
247	- [ ] [无法从代码推断选型原因的库，需要人工说明]
248	```
249
250	写作要求：
251	- 只写主要的框架和库，不要把每个工具依赖都列一遍
252	- 能推断的写推断，推断不了的明确标「待补充：原始选型原因不明，请补充」
253	- 不要凭空捏造选型理由
254
255	---
256
257	### Step 6：写 `docs/QUALITY.md`
258
259	写什么：什么叫"完成"，以及代码审查的检查清单。
260
261	扫描方法：
262	```bash
263	# 看测试文件的模式
264	find . -name ".test." -o -name ".spec." -o -name "_test." 2>/dev/null \| head -10
265
266	# 看 CI 配置（如果有）
267	cat .github/workflows/*.yml 2>/dev/null \| head -60
268	```
269
270	格式模板：
271
272	```markdown
273	# 质量标准
274
275	## Definition o

People who liked this also viewed

6 picks

Type

harness-step2-fill-docs

71installs21forks

View on GitHub

How to install harness-step2-fill-docs?

simbajigege/book2skills/harness-step2-fill-docs

$npx -y skills add simbajigege/book2skills --skill harness-step2-fill-docs

Installs into the current project.

Summary

Files · 1

View on GitHub

SKILL.md

1	# Harness Step 2: 填充 docs/ 知识库内容
2
3	## 目标
4
5	通过深度阅读项目代码，将隐藏在代码里的业务能力、用户流程、架构知识、命名约定、技术决策，
6	显式地写入 docs/ 各文件。让 agent 在任何 session 都能快速理解项目全貌。
7
8	核心原则：推断出来的内容要标注来源，无法确定的内容标注「待补充」，
9	不要用模糊的占位符糊弄过去。
10
11	---
12
13	## 执行步骤
14
15	### Step 1：深度扫描
16
17	在写任何文档之前，先充分读懂项目。按顺序执行：
18
19	```bash
20	# 1. 确认 docs/ 骨架已存在
21	ls docs/
22
23	# 2. 读懂目录结构（3层）
24	find . -maxdepth 3 \
25	-not -path '/node_modules/' -not -path '/.git/' \
26	-not -path '/__pycache__/' -not -path '/dist/' \
27	-not -path '/.next/' -not -path '/build/' \| sort
28
29	# 3. 读主要入口文件
30	# （根据技术栈判断：main.ts / main.py / app.go / index.js 等）
31
32	# 4. 读模块边界（各主要目录的 index 文件或第一个文件）
33	# 目标：搞清楚每个目录的职责
34
35	# 5. 读依赖声明
36	cat package.json 2>/dev/null \|\| cat pyproject.toml 2>/dev/null \|\| \
37	cat go.mod 2>/dev/null \|\| cat Cargo.toml 2>/dev/null
38
39	# 6. 读已有文档（复用，不重复）
40	cat README.md 2>/dev/null
41	cat AGENTS.md 2>/dev/null
42	```
43
44	扫描目标——在写文档前，必须能回答这些问题：
45	- 这个项目服务哪些用户/角色？他们要完成什么任务？
46	- 它解决哪些业务痛点，哪些能力已经由页面、路由、API 或 service 实现？
47	- 用户从输入资料/发起操作到得到业务结果的核心流程是什么？
48	- 哪些只是 README 宣传、路线图或合理二开设想，尚不能视为现有能力？
49	- 这个项目分成哪几个主要模块？每个模块做什么？
50	- 代码调用链是怎样的？（UI → ? → ? → 数据层）
51	- 用了哪些主要的库/框架？能推断出选择原因吗？
52	- 文件命名有什么规律？变量命名有什么规律？
53	- 什么情况会导致测试失败？验收标准是什么？
54
55	---
56
57	### Step 2：写 `docs/business-solution.md`
58
59	写什么：从业务和需求视角说明项目服务谁、解决什么问题、如何产生价值，以及能力边界。不要把技术组件清单改写成业务价值，也不要把路线图或设想当成现有功能。
60
61	⚠️ 强制要求：业务能力必须验证可见入口或执行链路
62
63	README 可以用于发现候选能力，但在写“系统可以完成 X”之前，至少找到以下一种证据：
64	- 用户入口：页面、CLI command、API route、IM/Embed/MCP 接口
65	- 执行链路：handler/service/use case、任务 worker 或 provider registry
66	- 验证材料：对应测试、API 文档、正式产品文档
67
68	推荐搜索方法：
69
70	```bash
71	# 从路由和页面验证用户可见能力
72	rg -n "path:\|Register.*Routes\|\.GET\(\|\.POST\(" frontend/src/router internal/router
73
74	# 从业务对象和服务验证执行能力
75	rg -n "type .Service\|func New.Service\|Create\|Search\|Import\|Sync\|Evaluate" internal/application
76
77	# 区分已实现、路线图和待办
78	rg -n "Roadmap\|TODO\|planned\|coming soon\|路线图\|规划" README.md docs/ frontend/ internal/
79	```
80
81	每项能力标记证据状态：
82	- 已验证：找到入口和执行/文档证据
83	- 部分验证：只有单侧证据，明确缺失什么
84	- 待补充：目标行业、商业模式、业务指标等仓库无法确定的信息
85
86	格式模板：
87
88	```markdown
89	# 业务解决方案
90
91	## 一句话定位
92	[服务谁，用什么方式，解决什么核心问题]
93
94	## 目标用户与核心任务
95	\| 用户/角色 \| 核心任务 \| 当前痛点 \|
96	\|---\|---\|---\|
97
98	## 问题—能力—价值映射
99	\| 业务问题 \| 已验证能力 \| 产生的价值 \| 证据 \|
100	\|---\|---\|---\|---\|
101
102	## 典型业务场景
103	[3-8 个由代码/产品文档支持的场景，每个说明参与者、输入、过程和结果]
104
105	## 核心业务流程
106	[从用户输入到获得结果的端到端流程]
107
108	## 能力边界
109	- [不适用场景、依赖条件、安全/人工审核要求]
110
111	## 二次开发机会
112	[明确标注为建议，不得混入现有能力]
113
114	## 待补充
115	- [ ] [目标行业、指标、商业规则等需业务负责人确认的内容]
116	```
117
118	写作要求：
119	- 使用用户能理解的语言，先写任务和结果，再提技术实现
120	- “支持某集成”不等于“业务闭环已完成”，必须描述它在流程中的作用
121	- 不承诺无法从代码或文档确认的性能、准确率、合规等级和 SLA
122	- 能力边界至少覆盖数据质量、权限、高风险操作人工确认和运营维护
123
124	---
125
126	### Step 3：写 `docs/ARCHITECTURE.md`
127
128	写什么：模块划分、依赖方向、主要数据流。写"是什么结构"和"为什么这样分"，不写具体实现。
129
130	⚠️ 强制要求：描述组件/模块关系前，必须验证 import
131
132	写任何"A 被 B 使用"、"A 内嵌了 B"、"A 页面包含 C 组件"这类断言之前，
133	必须用 Grep 确认实际 import，不得根据文件名或目录位置猜测。
134
135	```bash
136	# 验证某组件是否被某页面实际引用
137	grep -r "ChatInterface" frontend/src/app/[locale]/book/[bookCode]/ 2>/dev/null
138
139	# 验证某组件被哪些文件实际引用
140	grep -rl "ComponentName" src/ 2>/dev/null
141	```
142
143	如果 grep 无结果，说明没有引用关系——即使组件在同一目录下也不能断言它被使用。
144	未经验证的关系统一标注「待验证：未找到 import，请人工确认」。
145
146	格式模板：
147
148	```markdown
149	# 架构说明
150
151	## 整体结构
152	[用文字描述整体分层，再用目录树辅助说明]
153
154	[目录树，只到关键层级，不要穷举所有文件]
155
156	## 依赖方向规则
157	[用箭头图或列表说明哪层可以引用哪层]
158
159	关键约束：
160	- [约束1，说明原因]
161	- [约束2，说明原因]
162
163	## 主要数据流
164	[描述最核心的 1-2 条请求/数据流，从入口到数据库]
165
166	## 待补充
167	- [ ] [扫描时无法确定的内容]
168	```
169
170	写作要求：
171	- 依赖规则要具体，不要写"保持清晰的分层"这种废话
172	- 每条约束附上原因（"不要在 UI 层调 DB，因为……"）
173	- 无法从代码推断的内容，明确标注「待补充：需人工确认」
174
175	---
176
177	### Step 4：写 `docs/CONVENTIONS.md`
178
179	写什么：从代码里归纳出来的命名规律和文件组织规律。
180
181	扫描方法：
182	```bash
183	# 看文件命名规律
184	find src -name ".ts" -o -name ".py" -o -name "*.go" 2>/dev/null \| head -30
185
186	# 看函数/变量命名（随机抽几个文件）
187	head -50 [主要源文件路径]
188	```
189
190	格式模板：
191
192	```markdown
193	# 代码约定
194
195	## 文件命名
196	- [规律1]：示例 `XxxYyy.tsx`
197	- [规律2]：示例 `xxx-yyy.ts`
198
199	## 变量和函数命名
200	- 变量/函数：[规律 + 示例]
201	- 类/组件：[规律 + 示例]
202	- 常量：[规律 + 示例]
203
204	## 目录组织
205	[每个主要目录放什么类型的文件]
206
207	## Git Commit 格式
208	[从 git log 里归纳，或写推荐格式]
209	`type(scope): 描述`
210	type 可选：feat / fix / docs / refactor / test
211
212	## 待补充
213	- [ ] [无法从代码推断的约定]
214	```
215
216	写作要求：
217	- 每条规律附上从代码中观察到的实例
218	- 如果代码本身命名不一致，如实写出来并标注「当前不一致，建议统一为……」
219	- 不要发明项目里没有的约定
220
221	---
222
223	### Step 5：写 `docs/TECH_DECISIONS.md`
224
225	写什么：技术选型的原因。这是最难写的一份，因为原因往往不在代码里。
226
227	扫描方法：
228	```bash
229	# 看所有直接依赖
230	cat package.json \| grep '"dependencies"' -A 50 2>/dev/null
231	# 或
232	cat pyproject.toml \| grep -A 30 '\[tool.poetry.dependencies\]' 2>/dev/null
233	```
234
235	格式模板：
236
237	```markdown
238	# 技术决策记录
239
240	## [框架/库名]
241	用途：[这个库/框架用来做什么]
242	选择原因：[能推断出的原因，或标注「待补充」]
243	替代方案：[如果明显有替代品，列出并说明为何不选]
244	注意事项：[使用时需要特别注意的地方]
245
246	## 待补充
247	- [ ] [无法从代码推断选型原因的库，需要人工说明]
248	```
249
250	写作要求：
251	- 只写主要的框架和库，不要把每个工具依赖都列一遍
252	- 能推断的写推断，推断不了的明确标「待补充：原始选型原因不明，请补充」
253	- 不要凭空捏造选型理由
254
255	---
256
257	### Step 6：写 `docs/QUALITY.md`
258
259	写什么：什么叫"完成"，以及代码审查的检查清单。
260
261	扫描方法：
262	```bash
263	# 看测试文件的模式
264	find . -name ".test." -o -name ".spec." -o -name "_test." 2>/dev/null \| head -10
265
266	# 看 CI 配置（如果有）
267	cat .github/workflows/*.yml 2>/dev/null \| head -60
268	```
269
270	格式模板：
271
272	```markdown
273	# 质量标准
274
275	## Definition o

People who liked this also viewed

6 picks

Type