Back to Details

combine-docs

Compare original and translation side by side

🇺🇸

Original

English
🇨🇳

Translation

Chinese

Documentation Consolidator

文档整合工具

Discover all documentation in a project, analyze for redundancy and contradictions, propose a consolidation plan, then execute it with user approval.
Follow all 4 steps sequentially. Do NOT execute changes without user approval at Step 3.
发现项目中的所有文档，分析其中的冗余和矛盾内容，提出合并整合方案，在获得用户批准后执行。
请按顺序执行以下4个步骤。在步骤3未获得用户批准前，不得执行任何修改操作。

Step 1: Discover

步骤1：发现文档

Find every documentation file in the project.
  1. Glob for docs -- search for 
    **/*.md
    , 
    **/*.mdx
    , 
    **/*.txt
    , 
    **/*.rtf
    (exclude 
    node_modules/
    , 
    .git/
    , 
    vendor/
    , 
    target/
    , 
    dist/
    , 
    build/
    , 
    __pycache__/
    , 
    archive/
    ).
  2. List what you found -- output each file with its path. Note how many docs exist total.
  3. Flag monorepo READMEs separately -- if the project has READMEs inside subdirectories (packages, modules, services), list them in their own group. These need extra care in Step 3.
找到项目中的所有文档文件。
  1. 全局搜索文档 -- 搜索
    **/*.md
    、
    **/*.mdx
    、
    **/*.txt
    、
    **/*.rtf
    格式的文件（排除
    node_modules/
    、
    .git/
    、
    vendor/
    、
    target/
    、
    dist/
    、
    build/
    、
    __pycache__/
    、
    archive/
    目录）。
  2. 列出找到的文档 -- 输出每个文件的路径。记录文档的总数量。
  3. 单独标记单体仓库README -- 如果项目的子目录（包、模块、服务）中存在README文件，将它们单独分组列出。这些文件在步骤3中需要额外处理。

Step 2: Map & Categorize

步骤2：映射与分类

Read each doc and build a landscape table for the user.
For each doc, note:
  • Path
  • Type: readme / guide / reference / changelog / config / adr / agent-config / other
  • What it covers (brief summary)
  • Overlaps with other docs (list paths)
Then identify:
  • Duplicated sections -- same content in multiple files (e.g., setup steps in README + CONTRIBUTING + docs/getting-started)
  • Contradictions -- different files say different things about the same topic
Present the map:
undefined
读取每个文档，为用户构建一份文档全景表。
针对每个文档，记录以下信息：
  • 路径
  • 类型：readme / 指南 / 参考文档 / 更新日志 / 配置文档 / 架构决策记录（ADR） / Agent配置 / 其他
  • 覆盖内容（简要概述）
  • 与其他文档的重叠部分（列出对应路径）
然后识别：
  • 重复章节 -- 多个文件中存在相同内容（例如，README、CONTRIBUTING和docs/getting-started中都有安装步骤）
  • 矛盾内容 -- 不同文件对同一主题的描述不一致
呈现映射结果：
undefined

Documentation Map: {project}

文档映射：{项目名称}

Documents found: {count}
PathTypeCoversOverlaps With
README.mdreadmesetup, overviewCONTRIBUTING.md (setup)
............
找到的文档数量： {数量}
路径类型覆盖内容重叠文件
README.mdreadme安装、概述CONTRIBUTING.md（安装部分）
............

Duplicated Content

重复内容

  • Setup instructions appear in: README.md, CONTRIBUTING.md, docs/getting-started.md
  • 安装说明出现在：README.md、CONTRIBUTING.md、docs/getting-started.md

Contradictions

矛盾内容

  • README.md says 
    npm start
    , CONTRIBUTING.md says 
    yarn dev

Ask the user using `AskUserQuestion` with `multiSelect: true`:

- Are any of these docs **auto-generated** or **externally published** (should not be edited)?
- Are any docs **off-limits** for other reasons?
  • README.md中写的是
    npm start
    ，CONTRIBUTING.md中写的是
    yarn dev

使用`AskUserQuestion`并设置`multiSelect: true`询问用户：

- 这些文档中是否有**自动生成**或**外部发布**的文档（不应编辑）？
- 是否有其他原因导致某些文档**不可修改**？

Step 3: Plan Structure

步骤3：规划结构

Propose where docs should live and what changes to make.
For each doc, assign an action:
ActionMeaning
MERGECombine multiple docs into one target
MOVERelocate to a better path (uses 
git mv
)
UPDATERewrite or refresh in place
CREATENew doc (usually CLAUDE.md)
ARCHIVEMove to 
archive/
-- never delete
SKIPLeave as-is, with reason
Present the plan:
undefined
提出文档的合理存放位置及修改方案。
为每个文档分配操作类型：
操作类型说明
MERGE（合并）将多个文档合并为一个目标文档
MOVE（移动）迁移到更合适的路径（使用
git mv
命令）
UPDATE（更新）原地重写或刷新内容
CREATE（创建）新建文档（通常是CLAUDE.md）
ARCHIVE（归档）移动到
archive/
目录 -- 绝不直接删除
SKIP（跳过）保持原样，并说明原因
呈现规划方案：
undefined

Consolidation Plan

整合规划方案

#ActionTargetDetails
1MERGEdocs/setup.mdREADME setup + CONTRIBUTING setup
2UPDATEREADME.mdRemove duplicated setup, link to docs/setup.md
3CREATECLAUDE.mdCommands, architecture, conventions
4ARCHIVEdocs/old-api.mdSuperseded by docs/api.md
5SKIPLICENSENo changes needed

**Hard gate:** Ask the user to approve, modify, or reject using `AskUserQuestion`:

- **Approve and execute** (Recommended)
- **Modify** -- user adjusts specific actions
- **Reject** -- stop, no changes

**If uncertain about any monorepo README or module-level doc, ask the user explicitly before including it in the plan.**

Do NOT proceed to Step 4 without explicit approval.
序号操作目标详情
1MERGEdocs/setup.md合并README的安装部分和CONTRIBUTING的安装部分
2UPDATEREADME.md删除重复的安装内容，添加指向docs/setup.md的链接
3CREATECLAUDE.md包含命令、架构、约定
4ARCHIVEdocs/old-api.md被docs/api.md替代
5SKIPLICENSE无需修改

**强制要求：** 使用`AskUserQuestion`询问用户是否批准、修改或拒绝方案：

- **批准并执行**（推荐选项）
- **修改** -- 用户调整具体操作
- **拒绝** -- 终止操作，不做任何修改

**如果对单体仓库的README或模块级文档有任何疑问，在将其纳入规划前请明确询问用户。**

未获得明确批准前，不得进入步骤4。

Step 4: Execute & Summarize

步骤4：执行与总结

Execute approved actions in order: ARCHIVE first, then MERGE, then UPDATE, then CREATE, then MOVE.
Execution rules:
  • ARCHIVE -- 
    git mv {path} archive/{path}
    . Add a header: 
    <!-- Archived by combine-docs. Superseded by {replacement}. -->
  • MERGE -- Read all sources. Combine content -- keep all unique information, deduplicate overlapping sections, resolve contradictions (prefer fresher source; ask user if unclear).
  • UPDATE -- Apply specified changes.
  • CREATE -- For CLAUDE.md: commands first, terse, structured, under 300 lines. For other docs: scannable headings, examples over prose.
  • MOVE -- 
    git mv
    so git tracks history.
After all actions, grep for broken internal links (
](
, 
href=
) pointing to moved/archived files and fix them.
Present results:
undefined
按顺序执行已批准的操作：先执行ARCHIVE，然后是MERGE，接着是UPDATE，再是CREATE，最后是MOVE。
执行规则：
  • ARCHIVE -- 执行
    git mv {路径} archive/{路径}
    。添加头部注释：
    <!-- 由combine-docs归档。已被{替代文档}替代。 -->
  • MERGE -- 读取所有源文档。合并内容时保留所有独特信息，去重重叠章节，解决矛盾内容（优先选择更新的源文档；若不确定则询问用户）。
  • UPDATE -- 执行指定的修改。
  • CREATE -- 对于CLAUDE.md：先列出命令，内容简洁结构化，篇幅不超过300行。对于其他文档：使用便于快速浏览的标题，多用示例少用文字描述。
  • MOVE -- 使用
    git mv
    命令，确保Git能追踪文件历史。
完成所有操作后，检查所有指向已移动/归档文件的内部链接（
](
、
href=
），修复损坏的链接。
呈现执行结果：
undefined

Consolidation Complete

整合完成

Changes

修改内容

BeforeAfterWhat Changed
README.md (setup + overview)README.md (overview only)Setup moved to docs/setup.md
docs/old-api.mdarchive/docs/old-api.mdArchived
(new)CLAUDE.mdCreated with commands, architecture
修改前修改后变更说明
README.md（包含安装+概述）README.md（仅保留概述）安装内容已迁移至docs/setup.md
docs/old-api.mdarchive/docs/old-api.md已归档
（无）CLAUDE.md已创建，包含命令、架构内容

What's Next

后续操作建议

  1. Review changes -- walk through each modified file
  2. Undo -- revert all changes (
    git checkout
    )
  3. Commit -- commit as a single commit
undefined
  1. 审核修改 -- 逐一查看每个被修改的文件
  2. 撤销修改 -- 恢复所有变更（执行
    git checkout
    ）
  3. 提交变更 -- 将所有变更作为单个提交记录
undefined

Style Guide

风格指南

General principle: Same information in exactly one place. Links replace duplication.
CLAUDE.md (agent-optimized):
  • Commands section first -- build, test, lint, deploy
  • Terse: 
    Run tests: npm test
    not a paragraph about the test framework
  • Structured: bullet lists and tables, not prose
  • Under 300 lines total
Human docs:
  • Scannable headings -- a reader skimming should understand the structure
  • Examples over explanations -- show, don't tell
  • One doc per concern -- setup, API, architecture each get their own file
  • Reference config files instead of duplicating their content
Monorepo READMEs:
  • Be careful -- module READMEs often serve a real purpose for that module's users
  • Keep module-specific content in module READMEs
  • Only consolidate if content is truly duplicated project-wide info
  • When in doubt, ask the user
基本原则： 同一信息仅存于一处。用链接替代重复内容。
CLAUDE.md（Agent优化版）：
  • 优先列出命令：构建、测试、Lint、部署
  • 简洁明了：例如用
    运行测试：npm test
    替代关于测试框架的长篇描述
  • 结构化：使用项目符号列表和表格，避免大段文字
  • 总篇幅不超过300行
面向人类的文档：
  • 使用便于快速浏览的标题 -- 用户扫一眼就能理解文档结构
  • 多用示例少用解释 -- 展示而非描述
  • 单一文档对应单一主题 -- 安装、API、架构分别使用独立文件
  • 引用配置文件而非重复其内容
单体仓库README：
  • 谨慎处理 -- 模块级README通常为该模块的用户提供重要信息
  • 模块专属内容保留在模块README中
  • 仅当内容在全项目范围内真正重复时才进行整合
  • 如有疑问，务必询问用户

Rules

规则

  • Never delete docs -- archive to 
    archive/
    if obsolete
  • Don't remove content when merging -- combine duplicated sections, keep unique info from each source
  • If uncertain whether a change is safe, ask the user
  • Use 
    git mv
    for all moves     so git tracks history
  • Always present the summary at the end with before/after changes
  • 绝不删除文档 -- 若文档过时，将其归档至
    archive/
    目录
  • 合并时不得删除内容 -- 合并重复章节，保留每个源文档的独特信息
  • 若不确定修改是否安全，请询问用户
  • 所有移动操作均使用
    git mv
    命令    ，确保Git能追踪文件历史
  • 操作完成后必须呈现总结，展示修改前后的变化