docs

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Docs

文档

Create and maintain project documentation in

docs/

with a consistent, lightweight workflow.

通过一致、轻量化的工作流在

docs/

目录下创建并维护项目文档。

Parameters

参数

```
--init
```
: Create documentation for the first time.
```
--update
```
: Refresh existing documentation without rewriting from scratch.

```
--init
```
: 首次创建文档。
```
--update
```
: 刷新现有文档，无需从头重写。

Outputs

输出内容

Always maintain these files:

```
docs/project-pdr.md
```
— product goals, users, requirements
```
docs/code-standard.md
```
— stack, conventions, development rules
```
docs/codebase.md
```
— codebase map and key files
```
docs/architecture.md
```
— components, interactions, data flow

Also keep

README.md

aligned with current docs links and project summary.

始终维护以下文件：

```
docs/project-pdr.md
```
— 产品目标、用户群体、需求说明
```
docs/code-standard.md
```
— 技术栈、编码规范、开发规则
```
docs/codebase.md
```
— 代码库映射及关键文件说明
```
docs/architecture.md
```
— 组件、交互逻辑、数据流

同时保持

README.md

与当前文档链接及项目摘要一致。

Workflow

工作流

Step 1: Context Scan (Docs First)

步骤1：上下文扫描（优先文档）

Review documentation first, then inspect code/config only as needed.

Priority order:

```
docs/project-pdr.md
```
```
docs/code-standard.md
```
```
docs/codebase.md
```
```
docs/architecture.md
```
```
README.md
```
Key source/config files

Focus on facts that changed: features, architecture, stack, structure, and workflows.

先查看文档，仅在必要时检查代码/配置。

优先级顺序：

```
docs/project-pdr.md
```
```
docs/code-standard.md
```
```
docs/codebase.md
```
```
docs/architecture.md
```
```
README.md
```
核心源码/配置文件

重点关注已变更的事实：功能、架构、技术栈、结构及工作流。

Step 2: Choose Mode

步骤2：选择模式

If docs do not exist or are incomplete: run
```
--init
```
behavior.
If docs exist: run
```
--update
```
behavior.
If mode is unspecified, infer from repository state and state your assumption.

若文档不存在或不完整：执行
```
--init
```
模式。
若文档已存在：执行
```
--update
```
模式。
若未指定模式，根据仓库状态自动推断并说明假设。

Step 3: Produce Documentation

步骤3：生成文档

--init

--init

模式

Create
```
docs/
```
if missing.
Create all required documentation files.
Populate each file with concrete, project-specific content.
Avoid placeholders and generic templates.

若
```
docs/
```
目录不存在则创建。
创建所有要求的文档文件。
为每个文件填充具体的、项目专属的内容。
避免占位符和通用模板。

--update

--update

模式

Preserve useful existing content and section structure.
Update stale or inaccurate sections.
Add newly discovered features/components/conventions.
Remove clearly obsolete statements.

保留有用的现有内容和章节结构。
更新过时或不准确的章节。
添加新发现的功能/组件/规范。
删除明显过时的表述。

Step 4: Sync README

步骤4：同步README

Ensure

README.md

includes:

Short project overview
Quick start (if present in project)
Documentation links section pointing to all 4 docs files

确保

README.md

包含：

简短的项目概述
快速开始（若项目中已存在）
文档链接章节，指向全部4个文档文件

Step 5: Validate Quality

步骤5：质量验证

Before finishing, verify:

Terminology is consistent across files
No contradictions between docs and code
Paths and component names are accurate
Content is concise, specific, and actionable

完成前，验证以下内容：

所有文件中的术语保持一致
文档与代码之间无矛盾
路径和组件名称准确无误
内容简洁、具体且具有可操作性

Content Requirements by File

各文件内容要求

project-pdr.md

project-pdr.md

Include:

Problem statement
Product purpose
Target users
Core use cases
Feature scope and constraints
Success criteria

需包含：

问题陈述
产品用途
目标用户
核心用例
功能范围与约束
成功标准

code-standard.md

code-standard.md

Include:

Languages/frameworks/tools in use
Naming and structure conventions
Testing/linting/formatting expectations
PR/commit expectations if discoverable

需包含：

使用的语言/框架/工具
命名与结构规范
测试/代码检查/格式化要求
若可查知，PR/提交规范

codebase.md

codebase.md

Include:

High-level tree
Directory responsibilities
Key entry points and modules
Important scripts/config files

需包含：

高层级目录树
目录职责说明
核心入口点与模块
重要脚本/配置文件

architecture.md

architecture.md

Include:

Main components/subsystems
Data flow between components
Integration boundaries (internal/external)
Deployment/runtime assumptions (if known)

需包含：

主要组件/子系统
组件间的数据流
集成边界（内部/外部）
部署/运行时假设（若已知）

Clarification Rules

澄清规则

Ask targeted questions only when information cannot be reliably inferred, especially for:

Business goals and domain intent
Ambiguous ownership/responsibility of modules
Conflicting conventions
Unclear architecture decisions

Prefer 1 focused question at a time.

仅当信息无法可靠推断时才提出针对性问题，尤其是针对以下内容：

业务目标与领域意图
模块所有权/职责不明确的情况
冲突的规范
模糊的架构决策

每次优先提出1个聚焦的问题。

Rules

规则

Keep documentation factual; do not invent requirements.
Prefer concise updates over verbose prose.
Keep docs aligned with current implementation.
Follow project conventions from
```
docs/code-standard.md
```
.
When uncertain, mark assumptions explicitly and request confirmation.

文档内容需基于事实，不得编造需求。
优先选择简洁的更新而非冗长的描述。
确保文档与当前实现保持一致。
遵循
```
docs/code-standard.md
```
中的项目规范。
若存在不确定性，需明确标记假设并请求确认。

docs

Original

Translation

Docs

文档

Parameters

参数

Outputs

输出内容

Workflow

工作流

Step 1: Context Scan (Docs First)

步骤1：上下文扫描（优先文档）

Step 2: Choose Mode

步骤2：选择模式

Step 3: Produce Documentation

步骤3：生成文档

`--init`

`--init`
模式

`--update`

`--update`
模式

Step 4: Sync README

步骤4：同步README

Step 5: Validate Quality

步骤5：质量验证

Content Requirements by File

各文件内容要求

`project-pdr.md`

`project-pdr.md`

`code-standard.md`

`code-standard.md`

`codebase.md`

`codebase.md`

`architecture.md`

`architecture.md`

Clarification Rules

澄清规则

Rules

规则

docs

Original

Translation

Docs

文档

Parameters

参数

Outputs

输出内容

Workflow

工作流

Step 1: Context Scan (Docs First)

步骤1：上下文扫描（优先文档）

Step 2: Choose Mode

步骤2：选择模式

Step 3: Produce Documentation

步骤3：生成文档

--init

--init模式

--update

--update模式

Step 4: Sync README

步骤4：同步README

Step 5: Validate Quality

步骤5：质量验证

Content Requirements by File

各文件内容要求

project-pdr.md

project-pdr.md

code-standard.md

code-standard.md

codebase.md

codebase.md

architecture.md

architecture.md

Clarification Rules

澄清规则

Rules

规则

`--init`

`--init`
模式

`--update`

`--update`
模式

`project-pdr.md`

`project-pdr.md`

`code-standard.md`

`code-standard.md`

`codebase.md`

`codebase.md`

`architecture.md`

`architecture.md`