{"id":"0d8f71ca-17fc-4ee9-be61-a9509e3162a2","shortId":"W5SrnE","kind":"skill","title":"harness-step2-fill-docs","tagline":"Harness Engineering 第一阶段第二步：深度分析项目代码，填充 docs/ 知识库各文件的实质内容。\n\n在 harness-step1-create-agents-md 创建好目录骨架之后使用。当用户说\"填充文档内容\"、\n\"完善 docs/ 文件\"、\"让文档有实质内容\"、\"分析项目写架构文档\"、\"写 ARCHITECTURE.md\"、\n\"写技术决策文档\"时，立即使用此 skill。\n\n前置条件：项目中已有 AGENTS.md 和 docs/ 目录骨架（由 harness-step1 创建）。","description":"# Harness Step 2: 填充 docs/ 知识库内容\n\n## 目标\n\n通过深度阅读项目代码，将隐藏在代码里的架构知识、命名约定、技术决策，\n显式地写入 docs/ 各文件。让 agent 在任何 session 都能快速理解项目全貌。\n\n**核心原则**：推断出来的内容要标注来源，无法确定的内容标注「待补充」，\n不要用模糊的占位符糊弄过去。\n\n---\n\n## 执行步骤\n\n### Step 1：深度扫描\n\n在写任何文档之前，先充分读懂项目。按顺序执行：\n\n```bash\n# 1. 确认 docs/ 骨架已存在\nls docs/\n\n# 2. 读懂目录结构（3层）\nfind . -maxdepth 3 \\\n  -not -path '*/node_modules/*' -not -path '*/.git/*' \\\n  -not -path '*/__pycache__/*' -not -path '*/dist/*' \\\n  -not -path '*/.next/*' -not -path '*/build/*' | sort\n\n# 3. 读主要入口文件\n# （根据技术栈判断：main.ts / main.py / app.go / index.js 等）\n\n# 4. 读模块边界（各主要目录的 index 文件或第一个文件）\n# 目标：搞清楚每个目录的职责\n\n# 5. 读依赖声明\ncat package.json 2>/dev/null || cat pyproject.toml 2>/dev/null || \\\n  cat go.mod 2>/dev/null || cat Cargo.toml 2>/dev/null\n\n# 6. 读已有文档（复用，不重复）\ncat README.md 2>/dev/null\ncat AGENTS.md 2>/dev/null\n```\n\n扫描目标——在写文档前，必须能回答这些问题：\n- 这个项目分成哪几个主要模块？每个模块做什么？\n- 代码调用链是怎样的？（UI → ? → ? → 数据层）\n- 用了哪些主要的库/框架？能推断出选择原因吗？\n- 文件命名有什么规律？变量命名有什么规律？\n- 什么情况会导致测试失败？验收标准是什么？\n\n---\n\n### Step 2：写 `docs/ARCHITECTURE.md`\n\n**写什么**：模块划分、依赖方向、主要数据流。写\"是什么结构\"和\"为什么这样分\"，不写具体实现。\n\n**⚠️ 强制要求：描述组件/模块关系前，必须验证 import**\n\n写任何\"A 被 B 使用\"、\"A 内嵌了 B\"、\"A 页面包含 C 组件\"这类断言之前，\n必须用 Grep 确认实际 import，不得根据文件名或目录位置猜测。\n\n```bash\n# 验证某组件是否被某页面实际引用\ngrep -r \"ChatInterface\" frontend/src/app/[locale]/book/[bookCode]/ 2>/dev/null\n\n# 验证某组件被哪些文件实际引用\ngrep -rl \"ComponentName\" src/ 2>/dev/null\n```\n\n如果 grep 无结果，说明没有引用关系——即使组件在同一目录下也不能断言它被使用。\n未经验证的关系统一标注「待验证：未找到 import，请人工确认」。\n\n**格式模板**：\n\n```markdown\n# 架构说明\n\n## 整体结构\n[用文字描述整体分层，再用目录树辅助说明]\n\n[目录树，只到关键层级，不要穷举所有文件]\n\n## 依赖方向规则\n[用箭头图或列表说明哪层可以引用哪层]\n\n关键约束：\n- [约束1，说明原因]\n- [约束2，说明原因]\n\n## 主要数据流\n[描述最核心的 1-2 条请求/数据流，从入口到数据库]\n\n## 待补充\n- [ ] [扫描时无法确定的内容]\n```\n\n**写作要求**：\n- 依赖规则要具体，不要写\"保持清晰的分层\"这种废话\n- 每条约束附上原因（\"不要在 UI 层调 DB，因为……\"）\n- 无法从代码推断的内容，明确标注「待补充：需人工确认」\n\n---\n\n### Step 3：写 `docs/CONVENTIONS.md`\n\n**写什么**：从代码里归纳出来的命名规律和文件组织规律。\n\n**扫描方法**：\n```bash\n# 看文件命名规律\nfind src -name \"*.ts\" -o -name \"*.py\" -o -name \"*.go\" 2>/dev/null | head -30\n\n# 看函数/变量命名（随机抽几个文件）\nhead -50 [主要源文件路径]\n```\n\n**格式模板**：\n\n```markdown\n# 代码约定\n\n## 文件命名\n- [规律1]：示例 `XxxYyy.tsx`\n- [规律2]：示例 `xxx-yyy.ts`\n\n## 变量和函数命名\n- 变量/函数：[规律 + 示例]\n- 类/组件：[规律 + 示例]\n- 常量：[规律 + 示例]\n\n## 目录组织\n[每个主要目录放什么类型的文件]\n\n## Git Commit 格式\n[从 git log 里归纳，或写推荐格式]\n`type(scope): 描述`\ntype 可选：feat / fix / docs / refactor / test\n\n## 待补充\n- [ ] [无法从代码推断的约定]\n```\n\n**写作要求**：\n- 每条规律附上从代码中观察到的实例\n- 如果代码本身命名不一致，如实写出来并标注「当前不一致，建议统一为……」\n- 不要发明项目里没有的约定\n\n---\n\n### Step 4：写 `docs/TECH_DECISIONS.md`\n\n**写什么**：技术选型的原因。这是最难写的一份，因为原因往往不在代码里。\n\n**扫描方法**：\n```bash\n# 看所有直接依赖\ncat package.json | grep '\"dependencies\"' -A 50 2>/dev/null\n# 或\ncat pyproject.toml | grep -A 30 '\\[tool.poetry.dependencies\\]' 2>/dev/null\n```\n\n**格式模板**：\n\n```markdown\n# 技术决策记录\n\n## [框架/库名]\n**用途**：[这个库/框架用来做什么]  \n**选择原因**：[能推断出的原因，或标注「待补充」]  \n**替代方案**：[如果明显有替代品，列出并说明为何不选]  \n**注意事项**：[使用时需要特别注意的地方]\n\n## 待补充\n- [ ] [无法从代码推断选型原因的库，需要人工说明]\n```\n\n**写作要求**：\n- 只写主要的框架和库，不要把每个工具依赖都列一遍\n- 能推断的写推断，推断不了的明确标「待补充：原始选型原因不明，请补充」\n- 不要凭空捏造选型理由\n\n---\n\n### Step 5：写 `docs/QUALITY.md`\n\n**写什么**：什么叫\"完成\"，以及代码审查的检查清单。\n\n**扫描方法**：\n```bash\n# 看测试文件的模式\nfind . -name \"*.test.*\" -o -name \"*.spec.*\" -o -name \"*_test.*\" 2>/dev/null | head -10\n\n# 看 CI 配置（如果有）\ncat .github/workflows/*.yml 2>/dev/null | head -60\n```\n\n**格式模板**：\n\n```markdown\n# 质量标准\n\n## Definition of Done（完成的定义）\n一个任务算完成，必须满足：\n- [ ] 功能在本地运行正常\n- [ ] 写了对应测试（覆盖正常路径 + 至少一个异常路径）\n- [ ] [根据项目实际情况补充，如：类型检查通过、lint 无报错]\n- [ ] git commit 信息清晰\n- [ ] 如修改了架构或约定，docs/ 已同步更新\n\n## 代码审查检查清单\n\n**正确性**\n- [ ] [项目特有的正确性检查，如：多租户隔离、权限验证]\n\n**可维护性**\n- [ ] 命名是否符合 CONVENTIONS.md？\n- [ ] 有无重复代码可提取？\n- [ ] 业务逻辑是否在正确的层？（见 ARCHITECTURE.md）\n\n## 测试要求\n[从现有测试文件归纳出的测试约定，或写推荐标准]\n\n## 待补充\n- [ ] [无法从代码推断的验收标准]\n```\n\n---\n\n### Step 6：写 `docs/exec-plans/tech-debt-tracker.md`\n\n**写什么**：扫描过程中发现的潜在问题和技术债务。\n\n**格式**：\n```markdown\n# 技术债务追踪\n\n每条格式：`[优先级: 高/中/低] 问题描述 — 影响范围`\n\n## 当前债务\n[扫描时发现的问题，诚实地写]\n\n## 已解决\n（空）\n```\n\n**判断债务的线索**：\n- 重复代码（同样的逻辑在多个地方出现）\n- 命名不一致（同一概念有多种叫法）\n- TODO / FIXME 注释\n- 过于庞大的文件（超过 300 行）\n- 没有测试的核心模块\n\n---\n\n## 质量检验\n\n每个文件写完后，逐一自检：\n\n- [ ] 有没有\"待补充\"的地方？→ 整理成清单告知用户\n- [ ] 有没有凭空捏造的内容？→ 删掉，换成「待补充」\n- [ ] ARCHITECTURE.md 的依赖规则是否具体可执行？\n- [ ] CONVENTIONS.md 的规律是否有代码实例支撑？\n- [ ] QUALITY.md 的 DoD 是否包含项目特有的检查项？\n\n---\n\n## 完成后告知用户\n\n输出摘要，包含三部分：\n\n**已写入的内容**：列出每个文件写了什么\n\n**需要人工确认的「待补充」清单**：\n汇总所有文件里标注了「待补充」的条目，这是用户最需要关注的部分\n\n**下一步**：\n- 人工补充「待补充」的内容后，这份知识库就可以投入使用\n- 之后运行 `harness-step3-state-management` skill，建立跨 session 的状态管理（progress 文件 + tasks.json）","tags":["harness","step2","fill","docs","book2skills","simbajigege","agent-skills","agentskills","anthropic","anthropic-claude","growth-investing","investing"],"capabilities":["skill","source-simbajigege","skill-harness-step2-fill-docs","topic-agent-skills","topic-agentskills","topic-anthropic","topic-anthropic-claude","topic-book2skills","topic-growth-investing","topic-investing","topic-investing-skills","topic-skills","topic-stock-analysis"],"categories":["book2skills"],"synonyms":[],"warnings":[],"endpointUrl":"https://skills.sh/simbajigege/book2skills/harness-step2-fill-docs","protocol":"skill","transport":"skills-sh","auth":{"type":"none","details":{"cli":"npx skills add simbajigege/book2skills","source_repo":"https://github.com/simbajigege/book2skills","install_from":"skills.sh"}},"qualityScore":"0.468","qualityRationale":"deterministic score 0.47 from registry signals: · indexed on github topic:agent-skills · 36 github stars · SKILL.md body (4,291 chars)","verified":false,"liveness":"unknown","lastLivenessCheck":null,"agentReviews":{"count":0,"score_avg":null,"cost_usd_avg":null,"success_rate":null,"latency_p50_ms":null,"narrative_summary":null,"summary_updated_at":null},"enrichmentModel":"deterministic:skill-github:v1","enrichmentVersion":1,"enrichedAt":"2026-05-01T12:56:54.011Z","embedding":null,"createdAt":"2026-04-18T22:21:59.317Z","updatedAt":"2026-05-01T12:56:54.011Z","lastSeenAt":"2026-05-01T12:56:54.011Z","tsv":"'-10':432 '-2':251 '-30':294 '-50':299 '-60':443 '/.git':94 '/.next':103 '/__pycache__':97 '/book':211 '/build':106 '/dev/null':128,132,136,140,148,152,214,221,292,370,379,430,441 '/dist':100 '/node_modules':91 '1':71,77,250 '2':47,83,127,131,135,139,147,151,169,213,220,291,369,378,429,440 '3':88,108,273 '30':376 '300':517 '3层':85 '4':116,353 '5':123,410 '50':368 '6':141,487 'agent':18,60 'agents.md':36,150 'app.go':113 'architecture.md':29,480,531 'b':189,193 'bash':76,204,279,361,418 'bookcod':212 'c':196 'cargo.toml':138 'cat':125,129,133,137,145,149,363,372,437 'chatinterfac':208 'ci':434 'commit':326,463 'componentnam':218 'conventions.md':476,533 'creat':17 'db':266 'definit':447 'depend':366 'doc':5,11,24,38,49,57,79,82,340,466 'docs/architecture.md':171 'docs/conventions.md':275 'docs/exec-plans/tech-debt-tracker.md':489 'docs/quality.md':412 'docs/tech_decisions.md':355 'dod':537 'done':449 'engin':7 'feat':338 'fill':4 'find':86,281,420 'fix':339 'fixm':513 'frontend/src/app':209 'git':325,329,462 'github/workflows':438 'go':290 'go.mod':134 'grep':200,206,216,223,365,374 'har':2,6,15,42,45,558 'harness-step1':41 'harness-step1-create-agents-md':14 'harness-step2-fill-docs':1 'harness-step3-state-management':557 'head':293,298,431,442 'import':185,202,230 'index':119 'index.js':114 'lint':460 'local':210 'log':330 'ls':81 'main.py':112 'main.ts':111 'manag':561 'markdown':233,302,381,445,493 'maxdepth':87 'md':19 'name':283,286,289,421,424,427 'o':285,288,423,426 'package.json':126,364 'path':90,93,96,99,102,105 'progress':566 'py':287 'pyproject.toml':130,373 'quality.md':535 'r':207 'readme.md':146 'refactor':341 'rl':217 'scope':334 'session':62,564 'skill':33,562 'skill-harness-step2-fill-docs' 'sort':107 'source-simbajigege' 'spec':425 'src':219,282 'state':560 'step':46,70,168,272,352,409,486 'step1':16,43 'step2':3 'step3':559 'tasks.json':568 'test':342,422,428 'todo':512 'tool.poetry.dependencies':377 'topic-agent-skills' 'topic-agentskills' 'topic-anthropic' 'topic-anthropic-claude' 'topic-book2skills' 'topic-growth-investing' 'topic-investing' 'topic-investing-skills' 'topic-skills' 'topic-stock-analysis' 'ts':284 'type':333,336 'ui':159,264 'xxx-yyy.ts':310 'xxxyyy.tsx':307 'yml':439 '一个任务算完成':451 '下一步':551 '不写具体实现':180 '不得根据文件名或目录位置猜测':203 '不要写':259 '不要凭空捏造选型理由':408 '不要发明项目里没有的约定':351 '不要在':263 '不要把每个工具依赖都列一遍':402 '不要用模糊的占位符糊弄过去':68 '不要穷举所有文件':240 '不重复':144 '业务逻辑是否在正确的层':478 '中':498 '为什么这样分':179 '主要数据流':175,248 '主要源文件路径':300 '之后运行':556 '人工补充':552 '什么叫':414 '什么情况会导致测试失败':166 '从':328 '从代码里归纳出来的命名规律和文件组织规律':277 '从入口到数据库':254 '从现有测试文件归纳出的测试约定':482 '代码审查检查清单':468 '代码约定':303 '代码调用链是怎样的':158 '以及代码审查的检查清单':416 '优先级':496 '低':499 '使用':190 '使用时需要特别注意的地方':396 '依赖方向':174 '依赖方向规则':241 '依赖规则要具体':258 '保持清晰的分层':260 '信息清晰':464 '先充分读懂项目':74 '关键约束':243 '内嵌了':192 '再用目录树辅助说明':237 '写':28,170,176,274,354,411,488 '写了对应测试':454 '写什么':172,276,356,413,490 '写任何':186 '写作要求':257,345,400 '写技术决策文档':30 '函数':313 '分析项目写架构文档':27 '列出并说明为何不选':394 '列出每个文件写了什么':543 '创建':44 '创建好目录骨架之后使用':20 '删掉':528 '判断债务的线索':507 '前置条件':34 '功能在本地运行正常':453 '包含三部分':541 '即使组件在同一目录下也不能断言它被使用':226 '原始选型原因不明':406 '变量':312 '变量命名':296 '变量命名有什么规律':165 '变量和函数命名':311 '只写主要的框架和库':401 '只到关键层级':239 '可维护性':474 '可选':337 '各主要目录的':118 '各文件':58 '同一概念有多种叫法':511 '同样的逻辑在多个地方出现':509 '命名不一致':510 '命名是否符合':475 '命名约定':54 '和':37,178 '因为':267 '因为原因往往不在代码里':359 '在':13 '在任何':61 '在写任何文档之前':73 '在写文档前':154 '填充':10,48 '填充文档内容':22 '复用':143 '多租户隔离':472 '如':458,471 '如修改了架构或约定':465 '如实写出来并标注':348 '如果':222 '如果代码本身命名不一致':347 '如果明显有替代品':393 '如果有':436 '完善':23 '完成':415 '完成后告知用户':539 '完成的定义':450 '将隐藏在代码里的架构知识':53 '层调':265 '已写入的内容':542 '已同步更新':467 '已解决':505 '常量':320 '库名':384 '建立跨':563 '建议统一为':350 '强制要求':181 '当前不一致':349 '当前债务':502 '当用户说':21 '影响范围':501 '待补充':67,255,270,343,391,397,405,484,524,530,545,548,553 '待验证':228 '必须满足':452 '必须用':199 '必须能回答这些问题':155 '必须验证':184 '或':371 '或写推荐标准':483 '或写推荐格式':332 '或标注':390 '执行步骤':69 '扫描方法':278,360,417 '扫描时发现的问题':503 '扫描时无法确定的内容':256 '扫描目标':153 '扫描过程中发现的潜在问题和技术债务':491 '技术债务追踪':494 '技术决策':55 '技术决策记录':382 '技术选型的原因':357 '按顺序执行':75 '换成':529 '推断不了的明确标':404 '推断出来的内容要标注来源':65 '描述':335 '描述最核心的':249 '描述组件':182 '搞清楚每个目录的职责':122 '数据层':160 '数据流':253 '整体结构':235 '整理成清单告知用户':526 '文件':25,567 '文件命名':304 '文件命名有什么规律':164 '文件或第一个文件':120 '无报错':461 '无法从代码推断的内容':268 '无法从代码推断的约定':344 '无法从代码推断的验收标准':485 '无法从代码推断选型原因的库':398 '无法确定的内容标注':66 '无结果':224 '时':31 '明确标注':269 '是什么结构':177 '是否包含项目特有的检查项':538 '显式地写入':56 '替代方案':392 '有无重复代码可提取':477 '有没有':523 '有没有凭空捏造的内容':527 '未找到':229 '未经验证的关系统一标注':227 '权限验证':473 '条请求':252 '架构说明':234 '核心原则':64 '根据技术栈判断':110 '根据项目实际情况补充':457 '格式':327,492 '格式模板':232,301,380,444 '框架':162,383 '框架用来做什么':387 '模块关系前':183 '模块划分':173 '正确性':469 '每个主要目录放什么类型的文件':324 '每个文件写完后':521 '每个模块做什么':157 '每条格式':495 '每条约束附上原因':262 '每条规律附上从代码中观察到的实例':346 '汇总所有文件里标注了':547 '没有测试的核心模块':519 '注意事项':395 '注释':514 '测试要求':481 '深度分析项目代码':9 '深度扫描':72 '清单':546 '用了哪些主要的库':161 '用文字描述整体分层':236 '用箭头图或列表说明哪层可以引用哪层':242 '用途':385 '由':40 '的':536 '的依赖规则是否具体可执行':532 '的内容后':554 '的地方':525 '的条目':549 '的状态管理':565 '的规律是否有代码实例支撑':534 '目录树':238 '目录组织':323 '目录骨架':39 '目标':51,121 '看':433 '看函数':295 '看所有直接依赖':362 '看文件命名规律':280 '看测试文件的模式':419 '知识库内容':50 '知识库各文件的实质内容':12 '确认':78 '确认实际':201 '示例':306,309,315,319,322 '空':506 '立即使用此':32 '第一阶段第二步':8 '等':115 '类':316 '类型检查通过':459 '约束1':244 '约束2':246 '组件':197,317 '能推断出的原因':389 '能推断出选择原因吗':163 '能推断的写推断':403 '至少一个异常路径':456 '行':518 '被':188 '覆盖正常路径':455 '见':479 '规律':314,318,321 '规律1':305 '规律2':308 '让':59 '让文档有实质内容':26 '诚实地写':504 '说明原因':245,247 '说明没有引用关系':225 '请人工确认':231 '请补充':407 '读主要入口文件':109 '读依赖声明':124 '读已有文档':142 '读懂目录结构':84 '读模块边界':117 '质量标准':446 '质量检验':520 '超过':516 '输出摘要':540 '过于庞大的文件':515 '这个库':386 '这个项目分成哪几个主要模块':156 '这份知识库就可以投入使用':555 '这是最难写的一份':358 '这是用户最需要关注的部分':550 '这种废话':261 '这类断言之前':198 '选择原因':388 '逐一自检':522 '通过深度阅读项目代码':52 '都能快速理解项目全貌':63 '配置':435 '里归纳':331 '重复代码':508 '问题描述':500 '随机抽几个文件':297 '需人工确认':271 '需要人工确认的':544 '需要人工说明':399 '页面包含':195 '项目中已有':35 '项目特有的正确性检查':470 '验收标准是什么':167 '验证某组件是否被某页面实际引用':205 '验证某组件被哪些文件实际引用':215 '骨架已存在':80 '高':497","prices":[{"id":"7f57111f-1c7f-4daa-92fc-c201df14a80d","listingId":"0d8f71ca-17fc-4ee9-be61-a9509e3162a2","amountUsd":"0","unit":"free","nativeCurrency":null,"nativeAmount":null,"chain":null,"payTo":null,"paymentMethod":"skill-free","isPrimary":true,"details":{"org":"simbajigege","category":"book2skills","install_from":"skills.sh"},"createdAt":"2026-04-18T22:21:59.317Z"}],"sources":[{"listingId":"0d8f71ca-17fc-4ee9-be61-a9509e3162a2","source":"github","sourceId":"simbajigege/book2skills/harness-step2-fill-docs","sourceUrl":"https://github.com/simbajigege/book2skills/tree/main/skills/harness-step2-fill-docs","isPrimary":false,"firstSeenAt":"2026-04-18T22:21:59.317Z","lastSeenAt":"2026-05-01T12:56:54.011Z"}],"details":{"listingId":"0d8f71ca-17fc-4ee9-be61-a9509e3162a2","quickStartSnippet":null,"exampleRequest":null,"exampleResponse":null,"schema":null,"openapiUrl":null,"agentsTxtUrl":null,"citations":[],"useCases":[],"bestFor":[],"notFor":[],"kindDetails":{"org":"simbajigege","slug":"harness-step2-fill-docs","github":{"repo":"simbajigege/book2skills","stars":36,"topics":["agent-skills","agentskills","anthropic","anthropic-claude","book2skills","growth-investing","investing","investing-skills","skills","stock-analysis"],"license":"mit","html_url":"https://github.com/simbajigege/book2skills","pushed_at":"2026-04-30T05:08:07Z","description":"Create best skills based on best books","skill_md_sha":"1816f6b2602cc867a3986a5953fe68c17ba7a34f","skill_md_path":"skills/harness-step2-fill-docs/SKILL.md","default_branch":"main","skill_tree_url":"https://github.com/simbajigege/book2skills/tree/main/skills/harness-step2-fill-docs"},"layout":"multi","source":"github","category":"book2skills","frontmatter":{"name":"harness-step2-fill-docs","description":"Harness Engineering 第一阶段第二步：深度分析项目代码，填充 docs/ 知识库各文件的实质内容。\n\n在 harness-step1-create-agents-md 创建好目录骨架之后使用。当用户说\"填充文档内容\"、\n\"完善 docs/ 文件\"、\"让文档有实质内容\"、\"分析项目写架构文档\"、\"写 ARCHITECTURE.md\"、\n\"写技术决策文档\"时，立即使用此 skill。\n\n前置条件：项目中已有 AGENTS.md 和 docs/ 目录骨架（由 harness-step1 创建）。"},"skills_sh_url":"https://skills.sh/simbajigege/book2skills/harness-step2-fill-docs"},"updatedAt":"2026-05-01T12:56:54.011Z"}}