harness-step2-fill-docs

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 个由代码/产品文档支持的场景，每个说明参与者、输入、过程和结果]

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

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

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

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