Goal
By deeply reading the project code, explicitly write the business capabilities, user flows, architecture knowledge, naming conventions, and technical decisions hidden in the code into the docs/ files. This lets the agent quickly understand the full picture of the project in any session.
Core Principles: For inferred content, note the source; for content that cannot be determined, mark it "To be supplemented". Do not fob it off with vague placeholders.
Execution Steps
Step 1: Deep Scan
Before writing any documentation, first fully understand the project. Execute in order:
# 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
Scan objectives - before writing documentation, you must be able to answer these questions:
- Which users/roles does this project serve? What tasks do they need to complete?
- Which business pain points does it solve, and which capabilities have already been implemented by pages, routes, APIs, or services?
- What is the core flow for users from entering materials/initiating actions to obtaining business results?
- Which items are only README promotion, roadmap, or reasonable secondary-development assumptions and cannot yet be regarded as existing capabilities?
- Which major modules is this project divided into? What does each module do?
- What is the code call chain? (UI → ? → ? → data layer)
- Which major libraries/frameworks are used? Can the reasons for the choices be inferred?
- What patterns are there in file naming? What patterns are there in variable naming?
- What situations cause tests to fail? What are the acceptance criteria?
Step 2: Write docs/business-solution.md
What to write: From the business and requirements perspective, explain whom the project serves, what problem it solves, how it creates value, and its capability boundaries. Do not rewrite a list of technical components as business value, and do not treat the roadmap or assumptions as existing functionality.
⚠️ Mandatory requirement: business capabilities must be verified with a visible entry point or execution chain
The README can be used to discover candidate capabilities, but before writing "the system can complete X", find at least one of the following kinds of evidence:
- User entry point: page, CLI command, API route, IM/Embed/MCP interface
- Execution chain: handler/service/use case, task worker, or provider registry
- Verification materials: corresponding tests, API documentation, formal product documentation
Recommended search methods:
# 从路由和页面验证用户可见能力
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/
Mark the evidence status for each capability:
- Verified: Found entry point and execution/documentation evidence
- Partially verified: Only one-sided evidence; clearly state what is missing
- To be supplemented: Information that cannot be determined from the repository, such as target industry, business model, business metrics, etc.
Format Template：
# 业务解决方案
## 一句话定位
[服务谁，用什么方式，解决什么核心问题]
## 目标用户与核心任务
| 用户/角色 | 核心任务 | 当前痛点 |
|---|---|---|
## 问题—能力—价值映射
| 业务问题 | 已验证能力 | 产生的价值 | 证据 |
|---|---|---|---|
## 典型业务场景
[3-8 个由代码/产品文档支持的场景，每个说明参与者、输入、过程和结果]
## 核心业务流程
[从用户输入到获得结果的端到端流程]
## 能力边界
- [不适用场景、依赖条件、安全/人工审核要求]
## 二次开发机会
[明确标注为建议，不得混入现有能力]
## 待补充
- [ ] [目标行业、指标、商业规则等需业务负责人确认的内容]
Writing Requirements：
- Use language users can understand; write the task and result first, then mention the technical implementation
- "Supporting a certain integration" does not equal "the business loop is complete"; its role in the flow must be described
- Do not promise performance, accuracy rates, compliance levels, or SLAs that cannot be confirmed from code or documentation
- The capability boundary must at least cover data quality, permissions, manual confirmation for high-risk operations, and operations and maintenance
Step 3: Write docs/ARCHITECTURE.md
What to write: module division, dependency direction, and main data flows. Write "what the structure is" and "why it is divided this way"; do not write specific implementation.
⚠️ Mandatory requirement: before describing component/module relationships, you must verify imports
Before writing any assertion such as "A is used by B", "A embeds B", or "A page contains component C", you must use Grep to confirm the actual import; do not guess based on file names or directory locations.
# 验证某组件是否被某页面实际引用
grep -r "ChatInterface" frontend/src/app/[locale]/book/[bookCode]/ 2>/dev/null
# 验证某组件被哪些文件实际引用
grep -rl "ComponentName" src/ 2>/dev/null
If grep returns no results, it means there is no reference relationship—even if the components are in the same directory, you cannot assert that it is used. Relationships that have not been verified must be uniformly marked "Pending verification: no import found, please confirm manually".
Format template：
# 架构说明
## 整体结构
[用文字描述整体分层，再用目录树辅助说明]
[目录树，只到关键层级，不要穷举所有文件]
## 依赖方向规则
[用箭头图或列表说明哪层可以引用哪层]
关键约束：
- [约束1，说明原因]
- [约束2，说明原因]
## 主要数据流
[描述最核心的 1-2 条请求/数据流，从入口到数据库]
## 待补充
- [ ] [扫描时无法确定的内容]
Writing requirements：
- Dependency rules must be specific; do not write useless statements like "maintain clear layering"
- Each constraint must include a reason ("Do not call the DB in the UI layer, because...")
- For content that cannot be inferred from the code, clearly mark "To be added: requires manual confirmation"
Step 4: Write docs/CONVENTIONS.md
What to write: naming patterns and file organization patterns summarized from the code.
Scanning method：
# 看文件命名规律
find src -name "*.ts" -o -name "*.py" -o -name "*.go" 2>/dev/null | head -30
# 看函数/变量命名（随机抽几个文件）
head -50 [主要源文件路径]
Format template：
# 代码约定
## 文件命名
- [规律1]：示例 `XxxYyy.tsx`
- [规律2]：示例 `xxx-yyy.ts`
## 变量和函数命名
- 变量/函数：[规律 + 示例]
- 类/组件：[规律 + 示例]
- 常量：[规律 + 示例]
## 目录组织
[每个主要目录放什么类型的文件]
## Git Commit 格式
[从 git log 里归纳，或写推荐格式]
`type(scope): 描述`
type 可选：feat / fix / docs / refactor / test
## 待补充
- [ ] [无法从代码推断的约定]
Writing requirements：
- Each pattern must include an example observed in the code
- If the code itself is inconsistently named, write it as it is and mark "Currently inconsistent; suggest unifying as..."
- Do not invent conventions that do not exist in the project
Step 5: Write docs/TECH_DECISIONS.md
What to write: the reasons for the technology choices. This is the hardest document to write, because the reasons are often not in the code.
Scanning method：
# 看所有直接依赖
cat package.json | grep '"dependencies"' -A 50 2>/dev/null
# 或
cat pyproject.toml | grep -A 30 '\[tool.poetry.dependencies\]' 2>/dev/null
Format template：
# 技术决策记录
## [框架/库名]
**用途**：[这个库/框架用来做什么]
**选择原因**：[能推断出的原因，或标注「待补充」]
**替代方案**：[如果明显有替代品，列出并说明为何不选]
**注意事项**：[使用时需要特别注意的地方]
## 待补充
- [ ] [无法从代码推断选型原因的库，需要人工说明]
Writing requirements：
- Write only the main frameworks and libraries; do not list every tool dependency
- Write inferences where you can infer; where you cannot, clearly mark "To be added: original selection reason unknown, please supplement"
- Do not fabricate selection reasons out of thin air
Step 6: Write docs/QUALITY.md
What to write: what counts as "done", and the checklist for code review.
Scanning method：
# 看测试文件的模式
find . -name "*.test.*" -o -name "*.spec.*" -o -name "*_test.*" 2>/dev/null | head -10
# 看 CI 配置（如果有）
cat .github/workflows/*.yml 2>/dev/null | head -60
Format template：
# 质量标准
## Definition of Done（完成的定义）
一个任务算完成，必须满足：
- [ ] 功能在本地运行正常
- [ ] 写了对应测试（覆盖正常路径 + 至少一个异常路径）
- [ ] [根据项目实际情况补充，如：类型检查通过、lint 无报错]
- [ ] git commit 信息清晰
- [ ] 如修改了架构或约定，docs/ 已同步更新
## 代码审查检查清单
**正确性**
- [ ] [项目特有的正确性检查，如：多租户隔离、权限验证]
**可维护性**
- [ ] 命名是否符合 CONVENTIONS.md？
- [ ] 有无重复代码可提取？
- [ ] 业务逻辑是否在正确的层？（见 ARCHITECTURE.md）
## 测试要求
[从现有测试文件归纳出的测试约定，或写推荐标准]
## 待补充
- [ ] [无法从代码推断的验收标准]
Step 7: Write docs/exec-plans/tech-debt-tracker.md
What to write: potential issues and technical debt discovered during the scanning process.
Format：
# 技术债务追踪
每条格式：`[优先级: 高/中/低] 问题描述 — 影响范围`
## 当前债务
[扫描时发现的问题，诚实地写]
## 已解决
（空）
Clues for identifying debt：
- Duplicate code (the same logic appears in multiple places)
- Inconsistent naming (the same concept has multiple names)
- TODO / FIXME comments
- Overly large files (more than 300 lines)
- Core modules without tests
Quality inspection
After writing each file, self-check one by one:
- Are there any "to be added" places? → Organize them into a list and inform the user
- Is there any fabricated content? → Delete it and replace it with "to be added"
- Does each existing capability in business-solution.md have evidence from pages, routes, APIs, services, tests, or formal documentation?
- Does business-solution.md distinguish existing capabilities, the roadmap, and secondary development suggestions, and clearly state the capability boundaries?
- Are the dependency rules in ARCHITECTURE.md specific and executable?
- Are the rules in CONVENTIONS.md backed by code examples?
- Does the DoD in QUALITY.md include project-specific check items?
Notify the user when complete
Output a summary containing three parts:
What has been written: list what was written in each file
Business solution summary: list the target users, core business problems, validated scenarios, and capability boundaries
List of "to be supplemented" items requiring manual confirmation: Summarize all items marked "to be supplemented" across all files; this is the part the user most needs to pay attention to
Next steps：
- After manually supplementing the "to be supplemented" content, this knowledge base can be put into use
- Then run the
harness-step3-session-managementskill to establish cross-session state management (progress file + tasks.json)