项目文档自动整理方案（通用版）
04/0780 浏览开发心得
# 项目文档自动整理方案（通用版）
> 本文档是一套可复用的项目文档自动整理方案，适用于任何使用 AI 编程助手 + Git 管理文档的项目。
---
## 一、问题背景
长期迭代的项目中，文档会自然增长并逐渐散乱：
| 典型问题 | 后果 |
|---------|------|
| 文档散落在根目录 | 找不到、忘记存在 |
| 同类文档分散在不同目录 | 同一主题的信息无法聚合 |
| 文件名风格不统一 | 英文、中文、缩写混用，辨识成本高 |
| 移动文件后引用断裂 | 其他文档中的链接失效、AI 助手找不到文档 |
**核心矛盾**：文档增长是渐进的，但整理是一次性的大动作。需要一套可重复执行的自动化方案。
---
## 二、方案概述
### 2.1 核心思路
1. **分类归档** — 按内容类型将文档归入预定义的目录结构
2. **文件名规范化** — 统一命名风格（中文 / 英文 / 混合，按项目需求选择）
3. **路径引用同步** — 移动文件后，批量更新所有引用该文件的地方
4. **目录索引更新** — 维护一份 README.md 作为文档导航
### 2.2 适用条件
- 项目使用 Git 管理代码和文档
- 文档集中在一个目录下（如 docs/）
- 有 AI 编程助手辅助执行（Claude Code、Cursor 等）
---
## 三、目录架构设计
### 3.1 推荐的顶层分类
根据文档的**读者和用途**划分顶层目录，建议 3-5 个分类：
```
docs/
├── 设计/ — 产品设计、需求文档、系统方案
├── 知识库/ — 技术文档、开发规范、经验积累
├── 索引/ — 资源清单、模块索引（可选）
├── 项目管理/ — 日志、进度、配置
└── README.md — 目录导航
```
**编号前缀（可选）**：用数字前缀控制目录排列顺序，如 `0设计/`、`1知识库/`、`2项目管理/`。
### 3.2 子目录设计原则
| 原则 | 说明 |
|------|------|
| **至少 3 个文件才建子目录** | 避免过度细分，1-2 个文件留在父目录即可 |
| **2-4 个字命名** | 子目录名言简意赅：系统设计/、开发规范/、操作日志/ |
| **深度不超过 3 层** | docs/分类/子目录/文件.md 已经是极限，再深难以导航 |
| **预留"其他"空间** | 每个分类的根目录可放不好归类的文件 |
### 3.3 子目录模板
**设计类文档**：
| 子目录 | 归档内容 |
|--------|---------|
| 系统设计/ | 各子系统的设计总结 |
| 方案文档/ | 具体改动方案、改造计划 |
**知识库类文档**：
| 子目录 | 归档内容 |
|--------|---------|
| 技术总结/ | 架构文档、技术方案总结 |
| 开发规范/ | 编码约定、检查清单 |
| 工具与流程/ | 工具手册、经验库、最佳实践 |
**项目管理类文档**：
| 子目录 | 归档内容 |
|--------|---------|
| 日志/ | 操作日志、同步日志 |
| 配置/ | 项目配置、环境配置 |
---
## 四、分类判断规则
### 4.1 内容 → 分类映射
| 文档内容特征 | 归入 |
|-------------|------|
| 产品设计、功能规格、数值公式、用户故事 | 设计/ |
| 技术架构、开发经验、工具使用、Bug 经验 | 知识库/ |
| 资源清单、模块列表、API 索引 | 索引/ |
| 变更日志、进度跟踪、会议记录、项目配置 | 项目管理/ |
### 4.2 子目录归属关键词
| 关键词/文件名模式 | 建议子目录 |
|------------------|-----------|
| "XX系统""XX模块"设计 | 设计/系统设计/ |
| "XX方案""XX改造""XX计划" | 设计/方案文档/ |
| "XX架构""XX总结" | 知识库/技术总结/ |
| "XX规范""XX约定""XX清单" | 知识库/开发规范/ |
| "XX手册""XX指南""XX经验" | 知识库/工具与流程/ |
| "XX日志""XX记录" | 项目管理/日志/ |
### 4.3 边界情况
- **分类存疑** → 看主体内容，哪个分类占比大就归哪个
- **确实无法判断** → 标注存疑，交给项目负责人确认
- **新类型** → 优先归入现有子目录，确实无法容纳再新建
---
## 五、文件名规范化
### 5.1 命名风格选择
项目启动时确定一种风格，后续统一执行：
| 风格 | 示例 | 适用场景 |
|------|------|---------|
| **全中文** | 战斗系统总结.md | 面向非技术人员的文档 |
| **全英文-kebab-case** | battle-system-summary.md | 国际化团队 |
| **中英混合** | Bug经验库.md | 中文为主，术语保留英文 |
### 5.2 通用保留规则
无论选择哪种风格，以下内容保持原样：
- **技术术语/缩写**：Bug、API、UI、SDK、README
- **版本号**：v3.0、v2.1
- **专有名词**：Git、Docker、React
---
## 六、路径引用同步（核心难点）
### 6.1 为什么这是最重要的步骤
文件移动本身只需一条 `git mv` 命令。但项目中可能有大量文件**引用了被移动文件的路径**：
- 项目配置文件中的文档路径
- 其他文档中的交叉链接
- 自动化脚本中的路径常量
- AI 助手的规则文件中的文档引用
**不同步更新 = 链接全部断裂。** 这是整理工作中最耗时也最容易遗漏的环节。
### 6.2 批量替换方法
**第一步：构建替换映射表**
```json
{
"docs/旧路径/文件A.md": "docs/新路径/子目录/文件A.md",
"docs/旧路径/文件B.md": "docs/新路径/子目录/文件B.md"
}
```
**第二步：覆盖多种路径写法**
同一个文件可能被三种格式引用：
| 格式 | 示例 |
|------|------|
| 相对路径（带顶层目录） | `docs/知识库/Bug经验库.md` |
| 相对路径（不带顶层目录） | `知识库/Bug经验库.md` |
| 绝对路径 | `/workspace/docs/知识库/Bug经验库.md` |
每条映射都要生成三种变体进行替换。
**第三步：按 key 长度降序排列**
防止短路径被长路径的子串先匹配。例如 `日志/` 可能被 `日志指南` 的替换规则误伤。
**第四步：执行替换**
```python
# 伪代码
for file in all_files:
content = read(file)
for old_path, new_path in sorted_mappings:
content = content.replace(old_path, new_path)
if changed:
write(file, content)
```
### 6.3 手动补漏
批量替换无法覆盖的特殊情况：
| 类型 | 示例 | 处理 |
|------|------|------|
| 通配符路径 | `docs/日志/sync*.md` | 手动修改 |
| 模板变量路径 | `docs/日志/sync-{name}.md` | 手动修改 |
| 代码中动态拼接 | `"docs/" .. dirName .. "/" .. fileName` | 理解上下文后修改 |
### 6.4 验证
替换完成后，逐一验证旧路径是否还存在：
```bash
# 用 ripgrep 或 grep 验证
rg "docs/旧路径" --type md
rg "docs/另一个旧路径" --type md
```
确认零残留后才能提交。
---
## 七、执行流程
```
步骤 1: 扫描
↓ 列出 docs/ 下所有文件及当前位置
步骤 2: 分类判断
↓ 按规则判断每个文件的目标位置
步骤 3: 文件名检查
↓ 是否符合命名规范，需要改名的列出
步骤 4: 生成调整方案（表格形式）
↓ 项目负责人审核确认
步骤 5: 执行移动
↓ mkdir -p 创建目录 + git mv 移动文件
步骤 6: 路径引用同步
↓ 批量替换 + 手动补漏 + 验证
步骤 7: 更新 README.md
↓ 重写目录导航，反映最新结构
步骤 8: Git 提交
```
### 方案表格模板
```markdown
| 文件 | 当前位置 | 目标位置 | 操作 | 原因 |
|------|---------|---------|------|------|
| 文件A.md | docs/ | docs/知识库/技术总结/ | 移动 | 技术文档属于知识库 |
| old-name.md | docs/知识库/ | docs/知识库/工具与流程/新名称.md | 移动+改名 | 归类+中文化 |
| 文件C.md | — | — | 不动 | 已在正确位置 |
```
---
## 八、AI 助手集成
### 8.1 触发条件
建议将以下场景设为自动触发：
| 场景 | 说明 |
|------|------|
| 新增文档文件 | 在 docs/ 下创建了新文件 |
| 用户手动要求 | 用户说"整理文档""归档""梳理文档" |
| 定期检查 | 每月或累积 10+ 新文件时 |
| 会话结束前 | 收工检查时发现散落文件 |
### 8.2 AI 助手规则模板
```
当用户说"整理文档""归档"时：
1. 扫描 docs/ 目录，找出不在正确位置的文件
2. 生成调整方案表格，等用户确认
3. 执行 git mv + 路径引用同步
4. 更新 README.md
5. Git 提交
```
### 8.3 与其他流程的集成
| 集成点 | 方式 |
|--------|------|
| Git 提交 | 归档完成后自动提交 |
| 文档维护规则 | 本方案是文档维护规则的落地工具 |
| 提交后检查 | 提交代码后检查是否有新文档需要归档 |
---
## 九、维护指南
### 9.1 日常：新增文档时
直接创建在正确子目录，更新 README.md 即可，无需全量归档。
### 9.2 定期：全量归档检查
推荐频率：每月一次，或累积 10+ 新文件时。
```bash
# 检查 docs/ 根目录是否有散落文件
ls docs/*.md # 除 README.md 外不应有其他文件
```
### 9.3 演进：新增子目录
- 现有子目录确实无法容纳新类型文档
- 新子目录预期至少有 3+ 个文件
- 命名 2-4 个字，概括归档范围
---
## 十、检查清单
```
□ docs/ 根目录除 README.md 外无散落文件
□ 所有文件已归入正确分类目录
□ 文件名符合命名规范
□ 所有路径引用已同步更新（批量 + 手动验证）
□ README.md 已更新为最新目录结构
□ rg/grep 验证零残留旧路径
□ Git 提交完成
□ 同类文档在同一目录下，无分散
```
---
## 十一、踩坑经验（通用）
| 问题 | 原因 | 预防措施 |
|------|------|---------|
| 批量替换遗漏通配符路径 | 通配符路径不在固定映射表中 | 替换后手动 grep 特殊字符 `*`、`{`、`}` |
| 短路径先匹配导致误替换 | `日志/` 被 `日志指南` 的规则误伤 | 按 key 长度降序排列 |
| 移动后忘记更新引用 | 只关注了文件移动本身 | 把路径同步作为核心步骤，不是可选步骤 |
| 目录过度细分 | 1-2 个文件就建子目录 | 坚持"至少 3 个文件"原则 |
| 一次性移动太多导致混乱 | 50+ 文件同时移动 | 分批执行，每批 10-15 个文件 |
---
## 十二、快速上手
如果你想在自己的项目中使用这套方案，按以下步骤操作：
1. **定义目录结构** — 参考第三章，设计 3-5 个顶层分类 + 子目录
2. **确定命名风格** — 全中文 / 全英文 / 混合，项目内统一
3. **扫描现有文档** — 列出所有文件及当前位置
4. **生成方案表格** — 标注每个文件的目标位置和操作
5. **执行移动** — git mv，保留历史
6. **同步路径引用** — 批量替换 + 手动补漏 + 验证（**这步最关键**）
7. **更新 README.md** — 重写目录导航
8. **提交并记录** — Git 提交，记录本次整理的变更
---
## 十三、自动化脚本模板
> v1.1.0 新增。将第七章的 8 步手动流程封装为 Python 脚本，AI 助手或开发者可一键执行。
### 13.1 概述
手动整理适合小规模（< 10 个文件），但文件多、引用多时容易遗漏。自动化脚本解决三个痛点：
| 痛点 | 自动化方案 |
|------|-----------|
| 分类判断耗时 | 基于关键词的配置化分类规则 |
| 路径引用替换易遗漏 | 自动扫描所有引用文件，批量替换 |
| 验证不充分 | 自动搜索旧路径残留 |
### 13.2 脚本架构
建议创建两个文件：
| 文件 | 用途 | 说明 |
|------|------|------|
| `scripts/tools/doc_organize.py` | 主脚本 | 包含 4 个命令的完整逻辑 |
| `scripts/tools/doc_organize_config.json` | 配置文件 | 项目专属的分类规则和扫描范围 |
### 13.3 四个命令
| 命令 | 功能 | 对应手动步骤 |
|------|------|-------------|
| `scan` | 扫描 docs/ 下所有 .md 文件，显示当前分布 | 步骤 1 |
| `plan` | 按分类规则生成移动方案，输出 JSON 文件 | 步骤 2-4 |
| `execute` | 读取方案 JSON，执行 git mv + 路径替换 | 步骤 5-6 |
| `verify` | 验证旧路径是否仍有残留引用 | 步骤 6.4 验证 |
### 13.4 配置文件结构
配置文件采用 JSON 格式，包含以下字段：
| 字段 | 类型 | 说明 | 示例 |
|------|------|------|------|
| `docs_root` | string | 文档根目录 | `"docs"` |
| `categories` | object | 分类规则（关键词 → 目标目录） | 见下方 |
| `exclude_dirs` | array | 跳过的子目录 | `["索引"]` |
| `scan_refs_files` | array | 需要扫描引用的独立文件 | `["CLAUDE.md", "README.md"]` |
| `scan_refs_dirs` | array | 需要扫描引用的目录 | `["scripts", "docs"]` |
| `keep_english` | array | 保持英文名的文件模式 | `["README.md", "CHANGELOG.md"]` |
**分类规则示例**：
```json
{
"categories": {
"设计/系统设计": {
"keywords": ["系统", "模块", "架构设计"],
"description": "各子系统的设计总结文档"
},
"设计/方案文档": {
"keywords": ["方案", "计划", "改造"],
"description": "具体改动方案、改造计划"
},
"知识库/技术总结": {
"keywords": ["总结", "架构", "技术"],
"description": "技术架构和经验总结"
},
"知识库/开发规范": {
"keywords": ["规范", "约定", "清单", "规则"],
"description": "编码约定和检查清单"
},
"知识库/工具与流程": {
"keywords": ["手册", "指南", "经验", "工具"],
"description": "工具手册和最佳实践"
},
"项目管理/日志": {
"keywords": ["日志", "记录", "changelog"],
"description": "操作日志和变更记录"
}
}
}
```
### 13.5 核心实现要点
编写脚本时需注意以下关键技术点：
1. **关键词匹配**：遍历文件名，检查是否包含某个分类的关键词。匹配到多个分类时取第一个命中
2. **三种路径变体**：每个文件的路径引用可能有三种写法（`docs/...`、裸路径、绝对路径），替换时需覆盖全部
3. **按 key 长度降序排列**：防止短路径被长路径的子串先匹配（见第六章 6.2 第三步）
4. **plan → execute 两步确认**：plan 生成 JSON 方案供人审核，execute 读取该 JSON 执行，不跳过审核
5. **verify 搜索旧路径残留**：对每个已移动文件的旧路径，在所有引用文件中搜索是否仍有残留
### 13.6 使用方式模板
```bash
# 1. 扫描当前文件分布
python3 scripts/tools/doc_organize.py scan
# 2. 生成移动方案（输出 plan.json）
python3 scripts/tools/doc_organize.py plan
# 3. 人工审核 plan.json，确认无误后执行
python3 scripts/tools/doc_organize.py execute
# 4. 验证旧路径无残留
python3 scripts/tools/doc_organize.py verify
```
### 13.7 已知限制
| 限制 | 原因 | 应对方式 |
|------|------|---------|
| 关键词分类可能误判 | 文件名与内容不完全对应 | plan 步骤允许人工审核和修改 |
| 无法处理动态拼接路径 | 代码中用变量拼接路径 | 手动检查（见第六章 6.3） |
| 通配符路径不在替换范围 | 正则/glob 模式无法简单替换 | execute 后手动 grep 特殊字符 |
| 新增分类需更新配置 | 配置文件不会自动学习 | 定期审查分类规则的覆盖率 |
### 13.8 与手动流程的关系
自动化脚本**不取代**手动流程，而是**加速**手动流程的执行：
- **scan** = 手动步骤 1 的自动版
- **plan** = 手动步骤 2-4 的自动版（仍需人工审核）
- **execute** = 手动步骤 5-6 的自动版
- **verify** = 手动步骤 6.4 的自动版
- 手动步骤 7（更新 README）和步骤 8（Git 提交）仍需手动执行
**推荐工作流**：先用脚本完成 scan → plan → execute → verify，再手动更新 README 和提交。
---
*创建日期: 2026-04-06*
*适用范围: 任何使用 Git 管理文档的项目*