Harness Step 2: Fill in docs/ Knowledge Base Content

Goal

By deeply reading the project code, explicitly document the architectural knowledge, naming conventions, and technical decisions hidden in the code into each file in docs/. Enable agents to quickly understand the overall project overview in any session.

Core Principle: Mark the source for inferred content, mark "To be supplemented" for uncertain content, do not use vague placeholders.

Execution Steps

Step 1: In-depth Scanning

Before writing any documentation, fully understand the project first. Execute in the following order:

bash

# 1. Confirm the docs/ skeleton exists
ls docs/

# 2. Understand the directory structure (3 levels)
find . -maxdepth 3 \
  -not -path '*/node_modules/*' -not -path '*/.git/*' \
  -not -path '*/__pycache__/*' -not -path '*/dist/*' \
  -not -path '*/.next/*' -not -path '*/build/*' | sort

# 3. Read main entry files
# (Judge based on tech stack: main.ts / main.py / app.go / index.js, etc.)

# 4. Read module boundaries (index file or first file of each main directory)
# Goal: Clarify the responsibility of each directory

# 5. Read dependency declarations
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. Read existing documentation (reuse, do not duplicate)
cat README.md 2>/dev/null
cat AGENTS.md 2>/dev/null

Scanning Goals — Before writing documentation, you must be able to answer these questions:

What are the main modules of this project? What does each module do?
What is the code call chain like? (UI → ? → ? → Data Layer)
Which main libraries/frameworks are used? Can you infer the reasons for the choice?
What are the file naming rules? What are the variable naming rules?
What situations will cause test failures? What are the acceptance criteria?

Step 2: Write

docs/ARCHITECTURE.md

What to write: Module division, dependency directions, main data flow. Write "what the structure is" and "why it is divided this way", not the specific implementation.

⚠️ Mandatory Requirement: Verify imports before describing component/module relationships

Before making any assertions like "A is used by B", "A embeds B", or "A page contains C component", you must use Grep to confirm the actual import. Do not guess based on file names or directory locations.

bash

# Verify if a component is actually referenced by a page
grep -r "ChatInterface" frontend/src/app/[locale]/book/[bookCode]/ 2>/dev/null

# Verify which files actually reference a component
grep -rl "ComponentName" src/ 2>/dev/null

If Grep returns no results, there is no reference relationship — even if the components are in the same directory, you cannot assert they are used. All unverified relationships must be marked as "To be verified: No import found, please confirm manually".

Format Template:

markdown

# Architecture Description

## Overall Structure
[Describe the overall layering in text, then use a directory tree for illustration]

[Directory tree, only to key levels, do not list all files]

## Dependency Direction Rules
[Use arrow diagrams or lists to explain which layers can reference which layers]

Key Constraints:
- [Constraint 1, explain the reason]
- [Constraint 2, explain the reason]

## Main Data Flow
[Describe the 1-2 core request/data flows, from entry to database]

## To be Supplemented
- [ ] [Content that cannot be determined during scanning]

Writing Requirements:

Dependency rules must be specific, do not write vague statements like "maintain clear layering"
Attach reasons for each constraint (e.g., "Do not call the DB from the UI layer because...")
Clearly mark content that cannot be inferred from code as "To be supplemented: Need manual confirmation"

Step 3: Write

docs/CONVENTIONS.md

What to write: Naming rules and file organization rules summarized from the code.

Scanning Method:

bash

# Check file naming rules
find src -name "*.ts" -o -name "*.py" -o -name "*.go" 2>/dev/null | head -30

# Check function/variable naming (randomly select a few files)
head -50 [main source file path]

Format Template:

markdown

# Code Conventions

## File Naming
- [Rule 1]: Example `XxxYyy.tsx`
- [Rule 2]: Example `xxx-yyy.ts`

## Variable and Function Naming
- Variables/Functions: [Rule + Example]
- Classes/Components: [Rule + Example]
- Constants: [Rule + Example]

## Directory Organization
[What types of files are placed in each main directory]

## Git Commit Format
[Summarize from git log, or write recommended format]
`type(scope): description`
Optional types: feat / fix / docs / refactor / test

## To be Supplemented
- [ ] [Conventions that cannot be inferred from code]

Writing Requirements:

Attach code examples observed from the project for each rule
If there are inconsistencies in code naming, record them truthfully and mark "Currently inconsistent, it is recommended to unify as..."
Do not invent conventions that do not exist in the project

Step 4: Write

docs/TECH_DECISIONS.md

What to write: Reasons for technology selection. This is the most difficult document to write because the reasons are often not in the code.

Scanning Method:

bash

# Check all direct dependencies
cat package.json | grep '"dependencies"' -A 50 2>/dev/null
# Or
cat pyproject.toml | grep -A 30 '\[tool.poetry.dependencies\]' 2>/dev/null

Format Template:

markdown

# Technical Decision Records

## [Framework/Library Name]
**Purpose**: [What this library/framework is used for]  
**Reasons for Selection**: [Inferable reasons, or mark "To be supplemented"]  
**Alternative Solutions**: [List obvious alternatives and explain why they were not chosen]  
**Notes**: [Points that need special attention during use]

## To be Supplemented
- [ ] [Libraries whose selection reasons cannot be inferred from code, need manual explanation]

Writing Requirements:

Only write major frameworks and libraries, do not list every tool dependency
Write inferences where possible, clearly mark "To be supplemented: Original selection reason unknown, please supplement" for un inferable content
Do not fabricate selection reasons out of thin air

Step 5: Write

docs/QUALITY.md

What to write: What "done" means, and the code review checklist.

Scanning Method:

bash

# Check test file patterns
find . -name "*.test.*" -o -name "*.spec.*" -o -name "*_test.*" 2>/dev/null | head -10

# Check CI configuration (if available)
cat .github/workflows/*.yml 2>/dev/null | head -60

Format Template:

markdown

# Quality Standards

## Definition of Done
A task is considered complete only if it meets:
- [ ] Functions run normally locally
- [ ] Corresponding tests are written (covering normal paths + at least one exception path)
- [ ] [Supplement based on actual project situation, e.g., type checking passed, no lint errors]
- [ ] Clear git commit message
- [ ] If architecture or conventions are modified, docs/ has been updated synchronously

## Code Review Checklist

**Correctness**
- [ ] [Project-specific correctness checks, e.g., multi-tenant isolation, permission verification]

**Maintainability**
- [ ] Does the naming conform to CONVENTIONS.md?
- [ ] Is there duplicate code that can be extracted?
- [ ] Is the business logic in the correct layer? (See ARCHITECTURE.md)

## Testing Requirements
[Testing conventions summarized from existing test files, or write recommended standards]

## To be Supplemented
- [ ] [Acceptance criteria that cannot be inferred from code]

Step 6: Write

docs/exec-plans/tech-debt-tracker.md

What to write: Potential issues and technical debts discovered during scanning.

Format:

markdown

# Technical Debt Tracker

Each entry format: `[Priority: High/Medium/Low] Issue Description — Scope of Impact`

## Current Debts
[Issues discovered during scanning, record truthfully]

## Resolved
(Empty)

Clues for Identifying Debts:

Duplicate code (same logic appearing in multiple places)
Inconsistent naming (multiple names for the same concept)
TODO / FIXME comments
Overly large files (more than 300 lines)
Core modules without tests

Quality Inspection

After writing each file, perform self-checks one by one:

Are there any "To be supplemented" sections? → Compile a list and inform the user
Is there any fabricated content? → Delete it and replace with "To be supplemented"
Are the dependency rules in ARCHITECTURE.md specific and executable?
Are the rules in CONVENTIONS.md supported by code examples?
Does the DoD in QUALITY.md include project-specific check items?

Notify User After Completion

Output a summary including three parts:

Content Written: List what was written in each file

"To be Supplemented" List Needing Manual Confirmation: Summarize all entries marked "To be supplemented" in all files — this is the part the user needs to focus on most

Next Steps:

After manually supplementing the "To be supplemented" content, this knowledge base can be put into use
Then run the
```
harness-step3-state-management
```
skill to establish cross-session state management (progress file + tasks.json)

harness-step2-fill-docs

NPX Install

Tags

SKILL.md Content (Chinese)

Harness Step 2: Fill in docs/ Knowledge Base Content

Goal

Execution Steps

Step 1: In-depth Scanning

Step 2: Write
`docs/ARCHITECTURE.md`

Step 3: Write
`docs/CONVENTIONS.md`

Step 4: Write
`docs/TECH_DECISIONS.md`

Step 5: Write
`docs/QUALITY.md`

Step 6: Write
`docs/exec-plans/tech-debt-tracker.md`

Quality Inspection

Notify User After Completion