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.

Glob for docs -- search for

**/*.md

**/*.mdx

**/*.txt

**/*.rtf

(exclude

node_modules/

.git/

vendor/

target/

dist/

build/

__pycache__/

archive/

List what you found -- output each file with its path. Note how many docs exist total.
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.

找到项目中的所有文档文件。

全局搜索文档 -- 搜索

**/*.md

、

**/*.mdx

、

**/*.txt

、

**/*.rtf

格式的文件（排除

node_modules/

、

.git/

、

vendor/

、

target/

、

dist/

、

build/

、

__pycache__/

、

archive/

目录）。

列出找到的文档 -- 输出每个文件的路径。记录文档的总数量。
单独标记单体仓库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}

Path	Type	Covers	Overlaps With
README.md	readme	setup, overview	CONTRIBUTING.md (setup)
...	...	...	...

找到的文档数量： {数量}

路径	类型	覆盖内容	重叠文件
README.md	readme	安装、概述	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:

Action	Meaning
MERGE	Combine multiple docs into one target
MOVE	Relocate to a better path (uses `git mv` )
UPDATE	Rewrite or refresh in place
CREATE	New doc (usually CLAUDE.md)
ARCHIVE	Move to `archive/` -- never delete
SKIP	Leave as-is, with reason

Present the plan:

undefined

提出文档的合理存放位置及修改方案。

为每个文档分配操作类型：

操作类型	说明
MERGE（合并）	将多个文档合并为一个目标文档
MOVE（移动）	迁移到更合适的路径（使用 `git mv` 命令）
UPDATE（更新）	原地重写或刷新内容
CREATE（创建）	新建文档（通常是CLAUDE.md）
ARCHIVE（归档）	移动到 `archive/` 目录 -- 绝不直接删除
SKIP（跳过）	保持原样，并说明原因

呈现规划方案：

undefined

Consolidation Plan

整合规划方案

#	Action	Target	Details
1	MERGE	docs/setup.md	README setup + CONTRIBUTING setup
2	UPDATE	README.md	Remove duplicated setup, link to docs/setup.md
3	CREATE	CLAUDE.md	Commands, architecture, conventions
4	ARCHIVE	docs/old-api.md	Superseded by docs/api.md
5	SKIP	LICENSE	No 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.

序号	操作	目标	详情
1	MERGE	docs/setup.md	合并README的安装部分和CONTRIBUTING的安装部分
2	UPDATE	README.md	删除重复的安装内容，添加指向docs/setup.md的链接
3	CREATE	CLAUDE.md	包含命令、架构、约定
4	ARCHIVE	docs/old-api.md	被docs/api.md替代
5	SKIP	LICENSE	无需修改


**强制要求：** 使用`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

修改内容

Before	After	What Changed
README.md (setup + overview)	README.md (overview only)	Setup moved to docs/setup.md
docs/old-api.md	archive/docs/old-api.md	Archived
(new)	CLAUDE.md	Created with commands, architecture

修改前	修改后	变更说明
README.md（包含安装+概述）	README.md（仅保留概述）	安装内容已迁移至docs/setup.md
docs/old-api.md	archive/docs/old-api.md	已归档
（无）	CLAUDE.md	已创建，包含命令、架构内容

What's Next

后续操作建议

Review changes -- walk through each modified file
Undo -- revert all changes (
```
git checkout
```
)
Commit -- commit as a single commit

undefined

审核修改 -- 逐一查看每个被修改的文件
撤销修改 -- 恢复所有变更（执行
```
git checkout
```
）
提交变更 -- 将所有变更作为单个提交记录

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能追踪文件历史
操作完成后必须呈现总结，展示修改前后的变化