Back to Details

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:
  1. docs/project-pdr.md
    — product goals, users, requirements
  2. docs/code-standard.md
    — stack, conventions, development rules
  3. docs/codebase.md
    — codebase map and key files
  4. docs/architecture.md
    — components, interactions, data flow
Also keep 
README.md
aligned with current docs links and project summary.
始终维护以下文件：
  1. docs/project-pdr.md
    — 产品目标、用户群体、需求说明
  2. docs/code-standard.md
    — 技术栈、编码规范、开发规则
  3. docs/codebase.md
    — 代码库映射及关键文件说明
  4. 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:
  1. docs/project-pdr.md
  2. docs/code-standard.md
  3. docs/codebase.md
  4. docs/architecture.md
  5. README.md
  6. Key source/config files
Focus on facts that changed: features, architecture, stack, structure, and workflows.
先查看文档，仅在必要时检查代码/配置。
优先级顺序：
  1. docs/project-pdr.md
  2. docs/code-standard.md
  3. docs/codebase.md
  4. docs/architecture.md
  5. README.md
  6. 核心源码/配置文件
重点关注已变更的事实：功能、架构、技术栈、结构及工作流。

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
    中的项目规范。
  • 若存在不确定性，需明确标记假设并请求确认。