harness-step1-create-agents-md

Harness Step 1: Create AGENTS.md and docs/ knowledge base

Goal

Establish an agent-readable knowledge base foundation for the project:

A short AGENTS.md(~100 lines, serving as a "table of contents" rather than an encyclopedia)
A set of docs/ directory structure, storing the real knowledge

Core principles: what the agent cannot see does not exist. The project's business positioning, target users, problems solved, architectural decisions, naming conventions, and technology choices must exist in the repository in file form.

Execution steps

Step 1: Scan the project

Collect project information in order,skip information already known, do not ask repeatedly：

# 1. 项目根目录结构（2层）
find . -maxdepth 2 -not -path '*/node_modules/*' -not -path '*/.git/*' \
  -not -path '*/__pycache__/*' -not -path '*/dist/*' -not -path '*/.next/*' | sort

# 2. 识别技术栈
cat package.json 2>/dev/null || cat pyproject.toml 2>/dev/null || \
  cat go.mod 2>/dev/null || cat Cargo.toml 2>/dev/null || echo "未找到包管理文件"

# 3. 查看是否已有文档
ls -la *.md 2>/dev/null; ls -la docs/ 2>/dev/null

# 4. 查看 README（如有）
head -80 README.md 2>/dev/null || head -80 readme.md 2>/dev/null

Extract from the scan results:

Project name and purpose(from README or package.json)
Business positioning and user value(whom it serves, what problems it solves, which visible capabilities it provides)
Typical business scenarios(extracted from README features, examples, screenshot descriptions, and existing product documentation)
Tech stack(language, framework, main dependencies)
Directory structure(main module division)
Existing documentation(avoid duplication, reuse existing content)

Business content must distinguish between "existing capabilities explicitly declared by the repository" and "potential scenarios inferred from functionality". Content with only marketing descriptions and no code or product documentation evidence should be marked "Pending Step 2 verification".

Step 2: Generate the docs/ directory structure

Create the following files (fill in content based on scan results, do not leave empty placeholders):

Files that must be created:

AGENTS.md                    ← 目录文件，~100行
docs/
├── business-solution.md     ← 业务定位、用户问题、解决方案和能力边界
├── ARCHITECTURE.md          ← 模块划分、依赖关系
├── CONVENTIONS.md           ← 命名规则、代码风格
├── TECH_DECISIONS.md        ← 技术选型理由
├── QUALITY.md               ← 验收标准、完成定义
└── exec-plans/
    ├── active/              ← 当前进行中的计划（空目录，放 .gitkeep）
    ├── completed/           ← 已完成的计划（空目录，放 .gitkeep）
    ├── backlog.md           ← 待开发功能列表（已知需求，尚未排期）
    └── tech-debt-tracker.md ← 已知技术债务

Optional creation (judged based on the project's actual situation):

docs/
├── design-docs/             ← 有复杂设计决策时创建
├── product-specs/           ← 有产品规格时创建
└── references/              ← 有外部文档需要本地化时创建

Step 3: Write AGENTS.md

Strictly follow the format below, keep it within 100 lines:

# [项目名称] — Agent 工作指南

## 这是什么项目
[1-3句话：项目用途、核心功能、服务对象]

## 快速定向
- **我在哪个目录？** 运行 `pwd` 确认工作目录
- **技术栈**：[语言] + [框架] + [主要工具]
- **入口文件**：[主要入口，如 src/main.ts、app/main.py]
- **启动命令**：[如何启动开发服务器]
- **测试命令**：[如何跑测试]

## 知识库地图
在做任何修改前，先阅读相关文档：

| 我想了解... | 去读这个文件 |
|------------|-------------|
| 业务定位、目标用户、解决什么问题 | `docs/business-solution.md` |
| 整体架构、模块划分 | `docs/ARCHITECTURE.md` |
| 命名规则、代码风格 | `docs/CONVENTIONS.md` |
| 技术选型原因 | `docs/TECH_DECISIONS.md` |
| 什么叫"完成" | `docs/QUALITY.md` |
| 当前进行中的计划 | `docs/exec-plans/active/` |
| 待开发功能列表 | `docs/exec-plans/backlog.md` |
| 已知技术债务 | `docs/exec-plans/tech-debt-tracker.md` |

## 工作规范
1. **改之前先读**：修改任何模块前，先读对应的架构文档
2. **完成即提交**：每个功能完成后立即 git commit，写清楚做了什么
3. **更新文档**：如果你的修改影响了架构或约定，同步更新 docs/
4. **不要猜**：看不懂的地方先读文档，文档没有再问

## 禁止事项
[根据项目实际情况填写，例如：]
- 不要直接修改 `generated/` 目录下的文件（自动生成）
- 不要跳过测试直接合并
- 不要在 service 层引用 UI 组件（见 docs/ARCHITECTURE.md）

Step 4: Write each docs/ file

Content requirements for each file:

docs/business-solution.md

A one-sentence business positioning, and what the project is not
Target users/roles and their respective core tasks
The correspondence between current business pain points and project capabilities
3-8 typical business scenarios supported by evidence
One core end-to-end business process (from user input to obtaining a business result)
Capability boundaries, risks, and inapplicable scenarios
Existing capabilities and ideas yet to be developed must be clearly separated
If the target industry, business model, or business metrics cannot be determined from the repository, mark "Pending supplement: requires confirmation by the business owner"

docs/ARCHITECTURE.md

Module/package division and responsibilities
Dependency direction rules (which layer can reference which layer)
Main data flows
Do not write implementation details; write "what it is" and "why it is divided this way"

docs/CONVENTIONS.md

File naming rules
Variable/function/class naming rules
Directory organization rules
Comment style
Any habits established by team convention

docs/TECH_DECISIONS.md

Why this framework was chosen instead of others
Why this library is used
Important architectural decisions made historically and the reasons
If the reason cannot be determined during scanning, write "To be supplemented" and note that this needs to be filled in manually

docs/QUALITY.md

The criteria for a feature to count as "done" (Definition of Done)
Code review checklist
Test coverage requirements
Performance benchmarks (if any)

docs/exec-plans/backlog.md

List of known but not yet scheduled features to be developed; this point can be asked about to the user
Format for each item:[优先级: P1/P2/P3] 功能描述 — 背景说明
Note: backlog means "wanted but not yet done", not technical debt (technical debt is "already exists but is poorly done")
If scanning finds features that are already implemented on the backend but not yet launched on the frontend, or planned features mentioned in the documentation, write them here
If scanning finds no obvious backlog, write an empty list and note "To be supplemented when discovered"

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

List of known technical debt (parts of the existing code with poor quality that need improvement)
Format for each item:[优先级] 问题描述 — 影响范围
Note: do not mix backlog (features to be developed) into this file
If scanning finds no obvious debt, write an empty list and note "To be supplemented when discovered"

Quality check

After generation is complete, self-check the following questions:

Is AGENTS.md kept within 150 lines?
Does AGENTS.md contain specific startup/test commands (rather than "see the documentation")?
Does business-solution.md explain whom it serves, what problem it solves, how it creates value, and the capability boundaries?
Does business-solution.md clearly separate existing capabilities from potential secondary development ideas?
Do the files in docs/ have actual content rather than empty placeholders?
Are decisions in TECH_DECISIONS.md that cannot be determined marked as "To be supplemented"?
Does every link in the table of contents correspond to a file that actually exists?

Notify the user after completion

Output a brief summary:

Which files were created
The extracted business positioning, target users, and main solutions
Which content was inferred from project scanning (may need manual verification)
Which fields need to be filled in manually by the user (the places marked "To be supplemented")
Next step: run harness-step2-fill-docs In-depth validation of business capabilities and technical knowledge base