/harness-step2-fill-docs

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

Harness Step 2: 填充 docs/ 知识库内容

目标

通过深度阅读项目代码，将隐藏在代码里的业务能力、用户流程、架构知识、命名约定、技术决策， 显式地写入 docs/ 各文件。让 agent 在任何 session 都能快速理解项目全貌。

**核心原则**：推断出来的内容要标注来源，无法确定的内容标注「待补充」， 不要用模糊的占位符糊弄过去。

---

执行步骤

Step 1：深度扫描

在写任何文档之前，先充分读懂项目。按顺序执行：

# 1. 确认 docs/ 骨架已存在
ls docs/

# 2. 读懂目录结构（3层）
find . -maxdepth 3 \
  -not -path '*/node_modules/*' -not -path '*/.git/*' \
  -not -path '*/__pycache__/*' -not -path '*/dist/*' \
  -not -path '*/.next/*' -not -path '*/build/*' | sort

# 3. 读主要入口文件
# （根据技术栈判断：main.ts / main.py / app.go / index.js 等）

# 4. 读模块边界（各主要目录的 index 文件或第一个文件）
# 目标：搞清楚每个目录的职责

# 5. 读依赖声明
cat package.json 2>/dev/null || cat pyproject.toml 2>/dev/null || \
  cat go.mod 2>/dev/null || cat Cargo.toml 2>/dev/null

# 6. 读已有文档（复用，不重复）
cat README.md 2>/dev/null
cat AGENTS.md 2>/dev/null

扫描目标——在写文档前，必须能回答这些问题：

• 这个项目服务哪些用户/角色？他们要完成什么任务？
• 它解决哪些业务痛点，哪些能力已经由页面、路由、API 或 service 实现？
• 用户从输入资料/发起操作到得到业务结果的核心流程是什么？
• 哪些只是 README 宣传、路线图或合理二开设想，尚不能视为现有能力？
• 这个项目分成哪几个主要模块？每个模块做什么？
• 代码调用链是怎样的？（UI → ? → ? → 数据层）
• 用了哪些主要的库/框架？能推断出选择原因吗？
• 文件命名有什么规律？变量命名有什么规律？
• 什么情况会导致测试失败？验收标准是什么？

---

Step 2：写 `docs/business-solution.md`

**写什么**：从业务和需求视角说明项目服务谁、解决什么问题、如何产生价值，以及能力边界。不要把技术组件清单改写成业务价值，也不要把路线图或设想当成现有功能。

**⚠️ 强制要求：业务能力必须验证可见入口或执行链路**

README 可以用于发现候选能力，但在写“系统可以完成 X”之前，至少找到以下一种证据：

• 用户入口：页面、CLI command、API route、IM/Embed/MCP 接口
• 执行链路：handler/service/use case、任务 worker 或 provider registry
• 验证材料：对应测试、API 文档、正式产品文档

推荐搜索方法：

# 从路由和页面验证用户可见能力
rg -n "path:|Register.*Routes|\.GET\(|\.POST\(" frontend/src/router internal/router

# 从业务对象和服务验证执行能力
rg -n "type .*Service|func New.*Service|Create|Search|Import|Sync|Evaluate" internal/application

# 区分已实现、路线图和待办
rg -n "Roadmap|TODO|planned|coming soon|路线图|规划" README.md docs/ frontend/ internal/

每项能力标记证据状态：

• **已验证**：找到入口和执行/文档证据
• **部分验证**：只有单侧证据，明确缺失什么
• **待补充**：目标行业、商业模式、业务指标等仓库无法确定的信息

**格式模板**：

# 业务解决方案

## 一句话定位
[服务谁，用什么方式，解决什么核心问题]

## 目标用户与核心任务
| 用户/角色 | 核心任务 | 当前痛点 |
|---|---|---|

## 问题—能力—价值映射
| 业务问题 | 已验证能力 | 产生的价值 | 证据 |
|---|---|---|---|

## 典型业务场景
[3-8 个由代码/产品文档支持的场景，每个说明参与者、输入、过程和结果]

## 核心业务流程
[从用户输入到获得结果的端到端流程]

## 能力边界
- [不适用场景、依赖条件、安全/人工审核要求]

## 二次开发机会
[明确标注为建议，不得混入现有能力]

## 待补充
- [ ] [目标行业、指标、商业规则等需业务负责人确认的内容]

**写作要求**：

• 使用用户能理解的语言，先写任务和结果，再提技术实现
• “支持某集成”不等于“业务闭环已完成”，必须描述它在流程中的作用
• 不承诺无法从代码或文档确认的性能、准确率、合规等级和 SLA
• 能力边界至少覆盖数据质量、权限、高风险操作人工确认和运营维护

---

Step 3：写 `docs/ARCHITECTURE.md`

**写什么**：模块划分、依赖方向、主要数据流。写"是什么结构"和"为什么这样分"，不写具体实现。

**⚠️ 强制要求：描述组件/模块关系前，必须验证 import**

写任何"A 被 B 使用"、"A 内嵌了 B"、"A 页面包含 C 组件"这类断言之前， 必须用 Grep 确认实际 import，不得根据文件名或目录位置猜测。

# 验证某组件是否被某页面实际引用
grep -r "ChatInterface" frontend/src/app/[locale]/book/[bookCode]/ 2>/dev/null

# 验证某组件被哪些文件实际引用
grep -rl "ComponentName" src/ 2>/dev/null

如果 grep 无结果，说明没有引用关系——即使组件在同一目录下也不能断言它被使用。 未经验证的关系统一标注「待验证：未找到 import，请人工确认」。

**格式模板**：

# 架构说明

## 整体结构
[用文字描述整体分层，再用目录树辅助说明]

[目录树，只到关键层级，不要穷举所有文件]

## 依赖方向规则
[用箭头图或列表说明哪层可以引用哪层]

关键约束：
- [约束1，说明原因]
- [约束2，说明原因]

## 主要数据流
[描述最核心的 1-2 条请求/数据流，从入口到数据库]

## 待补充
- [ ] [扫描时无法确定的内容]

**写作要求**：

• 依赖规则要具体，不要写"保持清晰的分层"这种废话
• 每条约束附上原因（"不要在 UI 层调 DB，因为……"）
• 无法从代码推断的内容，明确标注「待补充：需人工确认」

---

Step 4：写 `docs/CONVENTIONS.md`

**写什么**：从代码里归纳出来的命名规律和文件组织规律。

**扫描方法**：

# 看文件命名规律
find src -name "*.ts" -o -name "*.py" -o -name "*.go" 2>/dev/null | head -30

# 看函数/变量命名（随机抽几个文件）
head -50 [主要源文件路径]

**格式模板**：

# 代码约定

## 文件命名
- [规律1]：示例 `XxxYyy.tsx`
- [规律2]：示例 `xxx-yyy.ts`

## 变量和函数命名
- 变量/函数：[规律 + 示例]
- 类/组件：[规律 + 示例]
- 常量：[规律 + 示例]

## 目录组织
[每个主要目录放什么类型的文件]

## Git Commit 格式
[从 git log 里归纳，或写推荐格式]
`type(scope): 描述`
type 可选：feat / fix / docs / refactor / test

## 待补充
- [ ] [无法从代码推断的约定]

**写作要求**：

• 每条规律附上从代码中观察到的实例
• 如果代码本身命名不一致，如实写出来并标注「当前不一致，建议统一为……」
• 不要发明项目里没有的约定

---

Step 5：写 `docs/TECH_DECISIONS.md`

**写什么**：技术选型的原因。这是最难写的一份，因为原因往往不在代码里。

**扫描方法**：

# 看所有直接依赖
cat package.json | grep '"dependencies"' -A 50 2>/dev/null
# 或
cat pyproject.toml | grep -A 30 '\[tool.poetry.dependencies\]' 2>/dev/null

**格式模板**：

# 技术决策记录

## [框架/库名]
**用途**：[这个库/框架用来做什么]  
**选择原因**：[能推断出的原因，或标注「待补充」]  
**替代方案**：[如果明显有替代品，列出并说明为何不选]  
**注意事项**：[使用时需要特别注意的地方]

## 待补充
- [ ] [无法从代码推断选型原因的库，需要人工说明]

**写作要求**：

• 只写主要的框架和库，不要把每个工具依赖都列一遍
• 能推断的写推断，推断不了的明确标「待补充：原始选型原因不明，请补充」
• 不要凭空捏造选型理由

---

Step 6：写 `docs/QUALITY.md`

**写什么**：什么叫"完成"，以及代码审查的检查清单。

**扫描方法**：

# 看测试文件的模式
find . -name "*.test.*" -o -name "*.spec.*" -o -name "*_test.*" 2>/dev/null | head -10

# 看 CI 配置（如果有）
cat .github/workflows/*.yml 2>/dev/null | head -60

**格式模板**：

# 质量标准

## Definition of Done（完成的定义）
一个任务算完成，必须满足：
- [ ] 功能在本地运行正常
- [ ] 写了对应测试（覆盖正常路径 + 至少一个异常路径）
- [ ] [根据项目实际情况补充，如：类型检查通过、lint 无报错]
- [ ] git commit 信息清晰
- [ ] 如修改了架构或约定，docs/ 已同步更新

## 代码审查检查清单

**正确性**
- [ ] [项目特有的正确性检查，如：多租户隔离、权限验证]

**可维护性**
- [ ] 命名是否符合 CONVENTIONS.md？
- [ ] 有无重复代码可提取？
- [ ] 业务逻辑是否在正确的层？（见 ARCHITECTURE.md）

## 测试要求
[从现有测试文件归纳出的测试约定，或写推荐标准]

## 待补充
- [ ] [无法从代码推断的验收标准]

---

Step 7：写 `docs/exec-plans/tech-debt-tracker.md`

**写什么**：扫描过程中发现的潜在问题和技术债务。

**格式**：

# 技术债务追踪

每条格式：`[优先级: 高/中/低] 问题描述 — 影响范围`

## 当前债务
[扫描时发现的问题，诚实地写]

## 已解决
（空）

**判断债务的线索**：

• 重复代码（同样的逻辑在多个地方出现）
• 命名不一致（同一概念有多种叫法）
• TODO / FIXME 注释
• 过于庞大的文件（超过 300 行）
• 没有测试的核心模块

---

质量检验

每个文件写完后，逐一自检：

• [ ] 有没有"待补充"的地方？→ 整理成清单告知用户
• [ ] 有没有凭空捏造的内容？→ 删掉，换成「待补充」
• [ ] business-solution.md 的每项现有能力是否有页面、路由、API、service、测试或正式文档证据？
• [ ] business-solution.md 是否区分了现有能力、路线图和二开建议，并写明能力边界？
• [ ] ARCHITECTURE.md 的依赖规则是否具体可执行？
• [ ] CONVENTIONS.md 的规律是否有代码实例支撑？
• [ ] QUALITY.md 的 DoD 是否包含项目特有的检查项？

---

##