文档架构维护指南

版本：v1.0 最后更新：2026-01-28 目标读者：开发者、文档维护者、技术写作者

📖 文档简介

目的

本指南为 Reading Vocab Helper 项目的文档维护提供完整的操作规范，确保文档架构的一致性和可持续性。

使用场景

📝 新增项目文档
✏️ 修改现有文档
🗑️ 删除或归档文档
🔍 查找文档应该放置的位置
✅ 验证文档规范性

7层文档架构概览

本项目采用7层文档体系架构（共38个文档）：

层级	名称	定位	文档数
Layer 1	项目入口	5分钟快速了解项目全貌	3
Layer 2	产品和业务	产品定位、功能规划、任务追踪	4
Layer 3	开发规范	日常开发必备的规范和指南	10
Layer 4	架构设计	系统架构、技术决策、设计思路	2
Layer 5	专项技术	各技术领域的深度文档	6
Layer 6	辅助工具	开发工具、脚本、使用指南	7+
Layer 7	自动化维护	CI/CD、文档维护、自动化检查	6+

完整导航见：docs/README.md

🚀 快速参考（5分钟速查）

新增文档决策树

需要创建新文档？
  ↓
Q1: 能否合并到现有文档？
  ├─ 是 → 扩展现有文档 ✅ DONE
  └─ 否 → 继续 Q2

Q2: 属于哪一层？
  ├─ Layer 1: 项目入口 → ❌ 不允许新增
  ├─ Layer 2: 产品业务 → product.md, plans/backlog.md, CHANGELOG.md
  ├─ Layer 3: 开发规范 → development.md, ui-guidelines/
  ├─ Layer 4: 架构设计 → design.md, decisions.md
  ├─ Layer 5: 专项技术 → database/, deployment/
  ├─ Layer 6: 辅助工具 → tools/, scripts/
  └─ Layer 7: 自动化 → .git/hooks/, scripts/

Q3: 命名规范？
  ├─ docs/ 下 → kebab-case（api-design.md）
  └─ 根目录 → UPPER_CASE（README.md, CHANGELOG.md）

Q4: 必须同步更新？
  ├─ docs/README.md（导航）
  ├─ CHANGELOG.md（Unreleased）
  └─ CLAUDE.md（如果是核心文档）

Q5: 提交验证
  └─ Git pre-commit hook 自动检查 ✅

常见场景快速查找表

场景	推荐位置	层级	示例
新增功能说明	`docs/product.md`	Layer 2	扩展"功能规划"章节
API 设计文档	`docs/api-design.md`	Layer 5	新建专项技术文档
代码规范	`docs/development.md`	Layer 3	扩展现有章节
UI 组件指南	`docs/ui-guidelines/`	Layer 3	按组件类型创建
数据库变更	`docs/database/schema.md`	Layer 5	更新 ER 图和表结构
工具使用说明	`tools/xxx/README.md`	Layer 6	工具目录下创建
CI/CD 配置	`.github/workflows/`	Layer 7	工作流配置文件
技术决策记录	`docs/decisions.md`	Layer 4	添加 ADR 条目

命令速查卡片

bash

# 1. 检查文档一致性
bash scripts/doc-consistency-check.sh

# 2. 查找所有 Markdown 文档
find docs/ -name "*.md" | sort

# 3. 检查断链
grep -r "\[.*\](.*\.md)" docs/ CLAUDE.md README.md

# 4. 统计各层文档数量
echo "Layer 1: $(ls -1 README.md QUICKSTART.md docs/README.md 2>/dev/null | wc -l)"
echo "Layer 2: $(ls -1 docs/product.md docs/USER_NOTES.md docs/plans/backlog.md CHANGELOG.md 2>/dev/null | wc -l)"
echo "Layer 3: $(find docs/ui-guidelines/ -name "*.md" 2>/dev/null | wc -l) + 2"

# 5. 查看最近修改的文档
find docs/ -name "*.md" -mtime -7 -exec ls -lh {} \;

# 6. 验证 pre-commit hook
.git/hooks/pre-commit --help 2>/dev/null || echo "Hook exists"

📋 详细流程

3.1 新增文档流程

Step 1：决策是否需要新文档

判断标准：

✅ 需要新文档的情况：

新的技术领域（如新增 API 设计文档）
独立的工具使用说明
完整的流程指南
专项技术深度文档

❌ 应扩展现有文档的情况：

现有文档有相关章节（如 development.md 已有代码规范）
内容较少（< 1000 字）
与现有文档高度相关
避免文档碎片化

决策工具：

bash

# 查找相关的现有文档
grep -r "关键词" docs/ --include="*.md" -l

Step 2：确定层级归属

层级判断规则：

Layer 1（项目入口）- ❌ 不允许新增

定型文档：README.md, QUICKSTART.md, docs/README.md
例外情况：重大架构调整需要新的入口文档（需团队讨论）

Layer 2（产品业务）- ⚠️ 谨慎新增

允许：产品战略、用户研究、竞品分析、功能规划
禁止：技术实现细节、代码示例
当前文档：product.md, USER_NOTES.md, plans/backlog.md, CHANGELOG.md
警戒阈值：6个文档

典型案例：

✅ user-research.md - 用户调研报告
✅ roadmap-2026.md - 年度路线图
❌ api-implementation.md - 属于 Layer 5

Layer 3（开发规范）- ✅ 允许新增

允许：代码规范、UI规范、测试规范、安全规范
注意：规范是"怎么做"，设计是"为什么这样做"（Layer 4）
当前文档：CLAUDE.md, development.md, ui-guidelines/ (8个)
警戒阈值：15个文档

典型案例：

✅ testing-guide.md - 测试规范
✅ security-checklist.md - 安全检查清单
✅ ui-guidelines/form-style-guide.md - 表单组件规范
❌ architecture-evolution.md - 属于 Layer 4

Layer 4（架构设计）- ⚠️ 优先记录到 decisions.md

允许：架构演进、重大重构的设计文档
注意：单个技术决策优先使用 ADR 格式记录到 decisions.md
当前文档：design.md, decisions.md
警戒阈值：4个文档

典型案例：

✅ clean-architecture-migration.md - 架构迁移方案
⚠️ use-riverpod-instead-of-provider.md - 应记录到 decisions.md
❌ api-endpoints.md - 属于 Layer 5

Layer 5（专项技术）- ✅ 允许新增

允许：数据库、API、性能优化、安全方案、新技术栈
建议：超过3个相关文档时创建子目录（参考 database/）
当前文档：database/ (3个), deployment/ (2个), assets/sql/ (3个)
警戒阈值：10个文档

典型案例：

✅ api-design.md - API 设计文档
✅ performance-optimization.md - 性能优化指南
✅ security-implementation.md - 安全实现方案
✅ 创建子目录：docs/api/endpoints.md, docs/api/authentication.md

Layer 6（辅助工具）- ✅ 允许新增

允许：工具使用指南、脚本说明
建议：放在工具代码目录下（tools/xxx/README.md）
当前文档：guides/ (3个), scripts/（tools/vocabulary_builder/ 2026-08-28 退出版本控制）
警戒阈值：15个文档

典型案例：

✅ tools/image_processor/README.md - 图像处理工具说明
✅ scripts/README.md - 脚本使用说明
❌ docs/tools-overview.md - 应放在工具目录下

Layer 7（自动化维护）- ✅ 允许新增

允许：CI/CD 配置、自动化流程文档、检查脚本
建议：放在脚本/配置目录下
当前文档：.git/hooks/, scripts/ (检查脚本), .claude/skills/ (6个)
警戒阈值：10个文档

典型案例：

✅ .github/workflows/README.md - CI/CD 说明
✅ scripts/automation-guide.md - 自动化脚本指南
✅ .claude/skills/new-skill/SKILL.md - 新的 Skill 定义

Step 3：命名和放置

命名规范

docs/ 目录下：使用 kebab-case

bash

✅ api-design.md
✅ database-migration-guide.md
✅ performance-optimization.md

❌ ApiDesign.md          # 不使用 PascalCase
❌ database_migration.md # 不使用 snake_case
❌ API-Design.md         # 不使用大写字母

根目录：使用 UPPER_CASE（行业惯例）

bash

✅ README.md
✅ CHANGELOG.md
✅ docs/plans/backlog.md
✅ QUICKSTART.md

❌ readme.md             # 根目录必须大写
❌ change-log.md         # 根目录必须大写

特殊命名约定：

schema.md - 数据库表结构文档
xxx-guide.md - 指南类文档
xxx-setup-guide.md - 配置指南

放置位置

项目根目录/
├── README.md               # 行业惯例文档（根目录）
├── CHANGELOG.md
├── docs/plans/backlog.md
├── QUICKSTART.md
├── CLAUDE.md
│
├── docs/                   # 结构化文档
│   ├── README.md           # 文档导航
│   ├── product.md          # Layer 2
│   ├── development.md      # Layer 3
│   ├── design.md           # Layer 4
│   ├── decisions.md        # Layer 4
│   │
│   ├── database/           # Layer 5 - 专项技术（子目录）
│   │   ├── schema.md
│   │   ├── optimization.md
│   │   └── README.md
│   │
│   ├── ui-guidelines/      # Layer 3 - 开发规范（子目录）
│   │   ├── material3-design-system.md
│   │   ├── button-style-guide.md
│   │   └── ...
│   │
│   └── guides/             # Layer 6 - 辅助工具
│       └── doc-maintenance-guide.md
│
├── tools/                  # Layer 6 - 工具文档
│   └── vocabulary_builder/
│       └── README.md
│
├── scripts/                # Layer 6/7 - 脚本文档
│   └── README.md
│
└── .claude/skills/         # Layer 7 - Skill 文档
    └── code-review/
        └── SKILL.md

Step 4：同步更新导航

必须更新的文档：

1. docs/README.md（导航文件）

在对应的 Layer 章节添加条目：

markdown

### Layer 5 - 专项技术（6个）

| 文档 | 说明 |
|------|------|
| [database/](database/) | 数据库设计文档（Schema、优化、README） |
| [deployment/](deployment/) | 部署配置指南（Supabase、Edge Function） |
| **[api-design.md](api-design.md)** | **API 设计规范（新增）** ⬅️ 添加这行

2. CHANGELOG.md（Unreleased 章节）

markdown

## [Unreleased]

### Added
- API 设计规范文档 `docs/api-design.md`

3. CLAUDE.md（如果是核心文档）

仅当文档是 Claude 需要频繁参考的核心文档时更新（如开发规范、架构设计）。

示例：

markdown

## 核心文档（6个）⭐ 必读

| 文档 | 内容 | 更新频率 | 备注 |
|------|-----|---------|------|
| [api-design.md](docs/api-design.md) | API 设计规范 | API 变更时 | 新增 |

Step 5：提交和验证

提交前检查

bash

# 1. 检查命名规范
ls -1 docs/api-design.md  # 确认文件存在且命名正确

# 2. 检查导航更新
grep "api-design.md" docs/README.md  # 确认导航已更新

# 3. 检查 CHANGELOG
grep "api-design.md" CHANGELOG.md  # 确认变更已记录

# 4. 运行文档一致性检查
bash scripts/doc-consistency-check.sh

Git 提交

bash

# 1. 暂存文件
git add docs/api-design.md
git add docs/README.md
git add CHANGELOG.md

# 2. 提交（pre-commit hook 会自动检查）
git commit -m "docs: 新增 API 设计规范文档

- 新增 docs/api-design.md（API 设计规范和最佳实践）
- 更新 docs/README.md 导航（Layer 5）
- 更新 CHANGELOG.md

🤖 Generated with [Claude Code](https://claude.com/claude-code)

Co-Authored-By: Claude Sonnet 4.5 <noreply@anthropic.com>"

Pre-commit hook 会自动检查

✅ 命名规范（kebab-case）
✅ 导航更新（docs/README.md）
✅ 文档一致性（断链、版本号）
💡 层级归属建议

如果检查失败：

bash

# 查看错误信息
# 修复问题后重新提交

# 或跳过检查（需在 PR 中说明原因）
git commit --no-verify -m "..."

3.2 修改现有文档流程

何时需要更新其他文档

触发条件 → 必须更新的文档：

修改内容	必须同步更新
数据库表结构	`docs/database/schema.md`, `CLAUDE.md`, `CHANGELOG.md`
架构设计	`docs/design.md`, `docs/decisions.md`, `CLAUDE.md`, `CHANGELOG.md`
核心功能	`docs/product.md`, `docs/plans/backlog.md`, `CHANGELOG.md`
API 接口	`docs/api-design.md`, `CHANGELOG.md`
配置变更	`docs/*-setup-guide.md`, `CHANGELOG.md`

详细规则见：CLAUDE.md - 文档同步检查清单

保持文档间引用一致性

检查方法：

bash

# 1. 查找所有引用当前文档的地方
grep -r "api-design.md" docs/ CLAUDE.md README.md

# 2. 如果文档重命名或移动，更新所有引用
# 例如：api-design.md → api-guidelines.md

find docs/ CLAUDE.md README.md -type f -name "*.md" -exec \
  sed -i '' 's/api-design\.md/api-guidelines.md/g' {} +

# 3. 验证断链
bash scripts/doc-consistency-check.sh

3.3 删除/归档文档流程

归档原则

不删除，而是归档，保留历史决策过程。

归档位置：docs/archived_YYYY-MM-DD/

bash

# 创建归档目录（如果不存在）
mkdir -p docs/archived_2026-01-28

# 移动过时文档
git mv docs/old-api-design.md docs/archived_2026-01-28/

# 在归档目录创建 README.md 说明归档原因
cat > docs/archived_2026-01-28/README.md << 'EOF'
# 归档文档说明

**归档日期**：2026-01-28
**归档原因**：API 设计规范已重构，旧版本不再适用

## 归档文档列表

- `old-api-design.md` - 旧版 API 设计规范（已被 `docs/api-design.md` 替代）
EOF

更新所有引用

bash

# 1. 查找所有引用
grep -r "old-api-design.md" docs/ CLAUDE.md README.md

# 2. 删除或替换引用
# 方式1：删除引用
# 方式2：替换为新文档引用
# 方式3：添加"已归档"注释

# 3. 更新导航（docs/README.md）
# 从对应层级删除条目

# 4. 更新 CHANGELOG.md

CHANGELOG.md 示例：

markdown

## [Unreleased]

### Removed
- 归档旧版 API 设计规范（`docs/old-api-design.md` → `docs/archived_2026-01-28/`）

🎯 层级归属决策指南

典型案例分析（10个实例）

案例1：新增"性能优化指南"

文件名：performance-optimization.md

分析过程：

能否合并？docs/database/optimization.md 仅针对数据库，不能合并
层级判断：性能优化属于专项技术 → Layer 5
命名：kebab-case ✅
位置：docs/performance-optimization.md

结论：✅ docs/performance-optimization.md（Layer 5）

案例2：新增"代码审查规范"

文件名：code-review-guide.md

分析过程：

能否合并？docs/development.md 已有代码规范章节，可以扩展
如果必须独立：代码规范属于开发规范 → Layer 3

结论：

✅ 优先：扩展 docs/development.md 添加"代码审查规范"章节
⚠️ 次选：独立文档 docs/code-review-guide.md（Layer 3）

案例3：新增"用户调研报告 2026"

文件名：user-research-2026.md

分析过程：

能否合并？独立报告，不能合并
层级判断：用户研究属于产品业务 → Layer 2
命名：kebab-case ✅
位置：docs/user-research-2026.md

结论：✅ docs/user-research-2026.md（Layer 2）

案例4：新增"Flutter 组件测试指南"

文件名：flutter-testing-guide.md

分析过程：

能否合并？测试规范可以扩展到 docs/development.md
如果必须独立：测试规范属于开发规范 → Layer 3

结论：

✅ 优先：扩展 docs/development.md 添加"测试规范"章节
⚠️ 次选：独立文档 docs/flutter-testing-guide.md（Layer 3）

案例5：新增"GitHub Actions 工作流说明"

文件名：github-actions.md

分析过程：

能否合并？独立的 CI/CD 配置说明
层级判断：CI/CD 属于自动化维护 → Layer 7
位置建议：放在配置目录下 .github/workflows/README.md

结论：✅ .github/workflows/README.md（Layer 7）

案例6：新增"Clean Architecture 迁移方案"

文件名：clean-architecture-migration.md

分析过程：

能否合并？重大架构变更，应该独立文档
层级判断：架构设计 → Layer 4

结论：✅ docs/clean-architecture-migration.md（Layer 4）

案例7：新增"Supabase Edge Function 部署"

文件名：supabase-edge-function-guide.md

分析过程：

能否合并？已有 docs/deployment/edge-function-deployment-guide.md，应该扩展
如果必须独立：专项技术 → Layer 5

结论：

✅ 优先：扩展现有文档 docs/deployment/edge-function-deployment-guide.md
❌ 避免：创建重复文档

案例8：新增"词汇构建工具使用说明"

文件名：vocabulary-builder-usage.md

分析过程：

位置判断：工具说明应放在工具目录下 → Layer 6
位置：tools/vocabulary_builder/README.md

结论：✅ tools/vocabulary_builder/README.md（Layer 6）

案例9：新增"技术决策：选择 Riverpod"

文件名：decision-riverpod.md

分析过程：

能否合并？单个技术决策应该使用 ADR 格式记录到 docs/decisions.md
层级判断：技术决策 → Layer 4

结论：

✅ 优先：在 docs/decisions.md 添加 ADR 条目
❌ 避免：创建独立文档（文档碎片化）

案例10：新增"Material 3 按钮样式规范"

文件名：button-style-guide.md

分析过程：

能否合并？UI 规范已有子目录 docs/ui-guidelines/
层级判断：UI 规范属于开发规范 → Layer 3
位置：docs/ui-guidelines/button-style-guide.md

结论：✅ docs/ui-guidelines/button-style-guide.md（Layer 3）

边界案例处理

案例A：跨层级文档

问题：文档同时涉及架构设计（Layer 4）和专项技术（Layer 5）

示例：database-architecture.md

解决方案：

判断主要内容：架构设计 > 技术实现 → Layer 4
如果平衡：拆分为两个文档
- docs/design.md 扩展"数据库架构设计"章节（Layer 4）
- docs/database/implementation.md 技术实现细节（Layer 5）

案例B：文档数量超过警戒阈值

问题：Layer 5 已有 10 个文档，需要新增第 11 个

解决方案：

审查现有文档：是否有重复/可合并的文档？

创建子目录组织：

docs/
├── api/              # API 相关（子目录）
│   ├── design.md
│   ├── authentication.md
│   └── endpoints.md
├── database/         # 数据库相关（已有）
└── performance/      # 性能相关（子目录）

重新归类：部分文档是否归属错误？

案例C：命名冲突

问题：docs/testing.md 和 docs/testing-guide.md 同时存在

解决方案：

合并文档：内容相似时合并为一个
明确区分：
- docs/testing.md → 测试策略和方法论
- docs/testing-guide.md → 测试操作指南
重命名：
- docs/testing-strategy.md - 测试策略
- docs/testing-guide.md - 测试指南

📐 命名规范详解

kebab-case 规范（docs/）

定义：小写字母 + 连字符

bash

✅ 正确示例
api-design.md
database-migration-guide.md
performance-optimization.md
clean-architecture-migration.md
user-research-2026.md

❌ 错误示例
ApiDesign.md              # PascalCase
api_design.md             # snake_case
API-Design.md             # 包含大写
api design.md             # 包含空格
apiDesign.md              # camelCase

正则表达式验证：

bash

# 检查文件是否符合 kebab-case
if [[ "$file" =~ ^[a-z0-9]+(-[a-z0-9]+)*\.md$ ]]; then
  echo "✅ 符合 kebab-case"
else
  echo "❌ 不符合 kebab-case"
fi

UPPER_CASE 规范（根目录）

定义：大写字母 + 下划线（行业惯例）

bash

✅ 正确示例（根目录）
README.md
CHANGELOG.md
docs/plans/backlog.md
QUICKSTART.md
CLAUDE.md
USER_NOTES.md

❌ 错误示例（根目录）
readme.md                 # 应该大写
Changelog.md              # 应该全部大写
change-log.md             # 应该使用下划线

特殊命名约定

1. schema.md - 数据库表结构

bash

✅ docs/database/schema.md
❌ docs/database/database-schema.md   # 冗余
❌ docs/database/tables.md            # 不够明确

2. xxx-guide.md - 指南类文档

bash

✅ api-design-guide.md
✅ testing-guide.md
✅ deployment-guide.md

⚠️ 注意：guide 是后缀，不是前缀
❌ guide-api-design.md

3. xxx-setup-guide.md - 配置指南

bash

✅ supabase-setup-guide.md
✅ firebase-setup-guide.md

❌ setup-supabase.md      # guide 应作为后缀

4. README.md - 目录说明

bash

✅ docs/README.md                      # 文档导航
✅ docs/database/README.md             # 数据库文档总览
✅ tools/vocabulary_builder/README.md  # 工具说明

注意：README.md 在根目录和 docs/ 下都使用 UPPER_CASE

🤖 自动化机制使用

Claude 自动提醒机制

触发条件1：新文档创建

触发：使用 Write 工具创建 *.md 文件

Claude 响应：

✅ 新文档创建：docs/api-design.md

📋 文档归档检查清单：
□ 确认层级归属（必选）：
  推荐：Layer 5（专项技术）
  理由：文件名包含 "api"

□ 命名规范检查：
  ✅ 符合 kebab-case

□ 需要同步更新：
  1. docs/README.md → 在 Layer 5 章节添加条目
  2. CHANGELOG.md → Unreleased 章节
  3. CLAUDE.md（如果是核心文档）

是否现在一起更新？

触发条件2：大量文档修改

触发：单次会话修改 5+ 个 *.md 文件

Claude 响应：

⚠️ 检测到大量文档修改（8个）

建议运行文档一致性检查：
bash scripts/doc-consistency-check.sh

是否现在运行检查？

触发条件3：文档数量超标

触发：某层文档数量超过警戒阈值

警戒阈值：

Layer 1: 3个（不允许新增）
Layer 2: 6个
Layer 3: 15个
Layer 4: 4个
Layer 5: 10个
Layer 6: 15个
Layer 7: 10个

Claude 响应：

⚠️ 文档数量警告：
Layer 5 当前有 11 个文档，超过警戒阈值（10个）

建议操作：
1. 审查是否有重复/可合并的文档
2. 考虑创建子目录组织（如 Layer 5 的 database/）
3. 考虑部分文档重新归类

Git Hooks 工作原理

Pre-commit Hook 流程

bash

# 位置：.git/hooks/pre-commit

执行流程：
1. 检测新增的 Markdown 文件（git diff --cached --name-only --diff-filter=A）
2. 对每个新文件执行：
   - 检查1：命名规范（docs/ 下必须 kebab-case）
   - 检查2：导航更新（新增 docs/*.md 必须同步更新 docs/README.md）
   - 提示：层级归属建议（根据文件名关键词）
3. 运行文档一致性检查脚本（scripts/doc-consistency-check.sh）
4. 检查通过 → 允许提交
5. 检查失败 → 拦截提交，显示错误信息

检查示例

场景1：新增文档但未更新导航

bash

$ git commit -m "docs: 新增 API 设计规范"

🔍 运行文档架构维护检查...

📝 Step 1/2: 新增文档规范检查...
  🆕 检测到新文档：
     - docs/api-design.md
       💡 建议归属：Layer 5（专项技术）
       ⚠️ 未更新导航：请在 docs/README.md 中添加文档说明
          提示：在对应层级（Layer 1-7）章节添加条目

❌ 新文档规范检查失败
   请修复上述问题后再提交
   或使用 'git commit --no-verify' 跳过检查（需在PR中说明原因）

场景2：命名不规范

bash

$ git commit -m "docs: 新增 API 设计规范"

🔍 运行文档架构维护检查...

📝 Step 1/2: 新增文档规范检查...
  🆕 检测到新文档：
     - docs/API_Design.md
       ❌ 命名规范错误：docs/ 下应使用 kebab-case
          示例：api-design.md, database-guide.md

❌ 新文档规范检查失败
   请修复上述问题后再提交

如何处理检查失败

方式1：修复问题（推荐）

bash

# 1. 根据错误提示修复问题
# 例如：重命名文件
git mv docs/API_Design.md docs/api-design.md

# 2. 更新导航
vim docs/README.md  # 添加新文档条目

# 3. 重新提交
git add docs/api-design.md docs/README.md
git commit -m "docs: 新增 API 设计规范

- 新增 docs/api-design.md
- 更新 docs/README.md 导航"

方式2：跳过检查（需在 PR 中说明原因）

bash

git commit --no-verify -m "docs: 新增 API 设计规范（临时提交）"

# 注意：
# 1. 仅在紧急情况下使用
# 2. 必须在 PR 中说明跳过原因
# 3. 后续必须修复问题

✅ 维护检查清单

日常检查清单

每次提交前执行：

bash

□ 文档命名符合规范（kebab-case 或 UPPER_CASE）
□ 新增文档已更新 docs/README.md 导航
□ 已更新 CHANGELOG.md（Unreleased 章节）
□ 运行文档一致性检查：bash scripts/doc-consistency-check.sh
□ Pre-commit hook 检查通过

季度审查清单

每季度（Q1/Q2/Q3/Q4）执行一次：

bash

□ 文档数量统计（各层是否超标）
□ 文档质量审查（重复、过时、归属不当）
□ 导航完整性（docs/README.md 是否包含所有文档）
□ 维护机制效果（Git hooks、Claude 提醒是否正常）
□ 架构演进决策（是否需要调整层级定义）

审查脚本：

bash

# 生成文档架构审查报告
bash scripts/doc-architecture-review.sh

# 输出示例：
# ========================================
# 文档架构审查报告 - 2026 Q1
# ========================================
#
# Layer 1: 3 个文档 ✅
# Layer 2: 4 个文档 ✅
# Layer 3: 10 个文档 ✅
# Layer 4: 2 个文档 ✅
# Layer 5: 11 个文档 ⚠️ 超过警戒阈值（10个）
# Layer 6: 7+ 个文档 ✅
# Layer 7: 6+ 个文档 ✅
#
# 建议操作：
# - Layer 5 超标，建议创建子目录组织

检查命令和脚本

1. 文档一致性检查

bash

# 运行完整检查
bash scripts/doc-consistency-check.sh

# 检查内容：
# - Schema 版本号一致性
# - 文档断链检查
# - 数据一致性验证

2. 统计各层文档数量

bash

# 快速统计
echo "Layer 1: $(ls -1 README.md QUICKSTART.md docs/README.md 2>/dev/null | wc -l)"
echo "Layer 2: $(ls -1 docs/product.md docs/USER_NOTES.md docs/plans/backlog.md CHANGELOG.md 2>/dev/null | wc -l)"
echo "Layer 3: $(($(find docs/ui-guidelines/ -name "*.md" 2>/dev/null | wc -l) + 2))"
echo "Layer 4: $(ls -1 docs/design.md docs/decisions.md 2>/dev/null | wc -l)"
echo "Layer 5: $(find docs/database/ docs/deployment/ -name "*.md" 2>/dev/null | wc -l)"

3. 查找最近修改的文档

bash

# 最近7天修改的文档
find docs/ -name "*.md" -mtime -7 -exec ls -lh {} \;

# 按修改时间排序
find docs/ -name "*.md" -exec ls -lt {} + | head -20

4. 检查断链

bash

# 查找所有 Markdown 链接
grep -r "\[.*\](.*\.md)" docs/ CLAUDE.md README.md

# 验证链接有效性
for link in $(grep -roh "\[.*\](\(.*\.md\))" docs/ | sed 's/.*(\(.*\))/\1/'); do
  if [ ! -f "$link" ]; then
    echo "❌ 断链：$link"
  fi
done

5. 验证 Pre-commit Hook

bash

# 检查 hook 是否可执行
ls -la .git/hooks/pre-commit

# 手动运行 hook（测试）
.git/hooks/pre-commit

# 输出：
# 🔍 运行文档架构维护检查...
# ...

❓ 常见问题 FAQ

Q1：如何判断文档应该放在哪层？

A：使用5步决策法：

先看内容主题：
- 产品/业务 → Layer 2
- 开发规范 → Layer 3
- 架构设计 → Layer 4
- 专项技术 → Layer 5
- 工具辅助 → Layer 6
- 自动化 → Layer 7
再看读者对象：
- 产品经理/用户 → Layer 2
- 开发者（日常） → Layer 3
- 架构师 → Layer 4
- 技术专家 → Layer 5
- 工具使用者 → Layer 6
- DevOps/维护者 → Layer 7
参考文件名关键词（见 CLAUDE.md 第340-349行）
查看典型案例（本文档"层级归属决策指南"章节）
仍然不确定？
- 询问 Claude（自动提供建议）
- 团队讨论
- 优先选择更通用的层级

Q2：文档数量超过警戒阈值怎么办？

A：3种解决方案：

方案1：创建子目录组织（推荐）

bash

# 示例：Layer 5 有 10+ 个文档
docs/
├── api/                    # API 相关子目录
│   ├── design.md
│   ├── authentication.md
│   └── endpoints.md
├── database/               # 数据库相关（已有）
│   ├── schema.md
│   └── optimization.md
└── performance/            # 性能相关子目录
    ├── optimization.md
    └── profiling.md

方案2：合并相关文档

bash

# 合并前
docs/api-design.md
docs/api-authentication.md
docs/api-endpoints.md

# 合并后
docs/api-guide.md  # 包含设计、认证、端点三部分

方案3：重新归类文档

bash

# 审查是否有文档归属错误
# 例如：testing-guide.md 误放在 Layer 5，应该移到 Layer 3
git mv docs/testing-guide.md docs/development-testing.md

Q3：如何处理跨层级的文档？

A：拆分为多个文档，或选择主要层级：

情况1：内容可拆分

bash

# 文档：database-architecture.md（跨 Layer 4 和 Layer 5）

# 拆分为：
docs/design.md                    # Layer 4 - 架构设计理念
docs/database/implementation.md   # Layer 5 - 技术实现细节

情况2：内容不可拆分

选择主要层级：

70% 架构设计 + 30% 技术实现 → Layer 4
30% 架构设计 + 70% 技术实现 → Layer 5

Q4：命名冲突如何解决？

A：3种方式：

方式1：合并文档（相似内容）

bash

# 冲突
docs/testing.md
docs/testing-guide.md

# 解决：合并为一个
docs/testing-guide.md  # 包含策略 + 指南

方式2：明确区分（不同角度）

bash

# 冲突
docs/api-design.md
docs/api-guide.md

# 解决：重命名明确职责
docs/api-design-principles.md  # 设计原则和理念
docs/api-usage-guide.md        # 使用指南和示例

方式3：使用子目录（同一主题）

bash

# 冲突
docs/database-schema.md
docs/database-optimization.md
docs/database-migration.md

# 解决：创建子目录
docs/database/
├── README.md
├── schema.md
├── optimization.md
└── migration.md

Q5：如何处理临时文档和草稿？

A：使用专门的草稿目录：

bash

# 创建草稿目录
docs/drafts/

# 命名规则：使用日期前缀
docs/drafts/2026-01-28-api-design-draft.md

# 不纳入导航，不受 pre-commit hook 检查
# 草稿完成后移到正式位置
git mv docs/drafts/2026-01-28-api-design-draft.md docs/api-design.md

Q6：文档更新后如何确保 Claude 知道？

A：3个方法：

方法1：更新 CLAUDE.md（核心文档）

markdown

## 核心文档（6个）⭐ 必读

| 文档 | 内容 | 更新频率 | 备注 |
|------|-----|---------|------|
| [api-design.md](docs/api-design.md) | API 设计规范 | API 变更时 | 新增 |

方法2：在文档中添加元数据

markdown

---
last_updated: 2026-01-28
version: 2.0
---

# API 设计规范

方法3：使用 CHANGELOG.md

markdown

## [Unreleased]

### Added
- API 设计规范文档 `docs/api-design.md`（Claude 会在新会话开始时读取）

Q7：如何批量重命名文档？

A：使用 Git 和脚本：

bash

# 单个文件重命名
git mv docs/old-name.md docs/new-name.md

# 批量重命名（kebab-case 转换）
for file in docs/*.md; do
  newname=$(echo "$file" | sed 's/_/-/g' | tr '[:upper:]' '[:lower:]')
  if [ "$file" != "$newname" ]; then
    git mv "$file" "$newname"
    echo "Renamed: $file → $newname"
  fi
done

# 更新所有引用
find docs/ CLAUDE.md README.md -type f -name "*.md" -exec \
  sed -i '' 's/old-name\.md/new-name.md/g' {} +

Q8：Pre-commit Hook 太严格怎么办？

A：根据情况调整：

临时跳过（紧急情况）：

bash

git commit --no-verify -m "..."
# 必须在 PR 中说明原因

调整 Hook 规则（团队讨论后）：

bash

# 编辑 .git/hooks/pre-commit
vim .git/hooks/pre-commit

# 例如：放宽命名规范检查
# 将错误改为警告（HAS_ERROR=0 改为 HAS_WARNING=1）

禁用特定检查：

bash

# 在 .git/hooks/pre-commit 中注释掉某些检查
# 例如：禁用导航更新检查
# if ! git diff --cached --name-only | grep -q "^docs/README\.md$"; then
#   echo "⚠️ 未更新导航"
# fi

💡 最佳实践

1. 文档原子化原则

定义：每个文档应该专注于单一主题，避免大而全的"百科全书"式文档。

优点：

✅ 易于维护（修改范围小）
✅ 易于查找（主题明确）
✅ 易于重用（模块化）

反例：

bash

❌ docs/everything-about-api.md  # 100KB，包含设计、认证、端点、测试、部署

正例：

bash

✅ docs/api-design-principles.md  # 15KB，专注于设计原则
✅ docs/api-authentication.md     # 10KB，专注于认证
✅ docs/api-endpoints.md          # 20KB，专注于端点定义

如何判断是否需要拆分：

文档超过 50KB → 考虑拆分
包含 3+ 个独立主题 → 考虑拆分
目录层级超过 4 层 → 考虑拆分

2. 文档更新与代码同步提交

原则：代码变更和文档更新应该在同一个 commit 中完成。

好处：

✅ 保持文档与代码同步
✅ Code Review 时一起审查
✅ 避免遗漏文档更新

示例：

bash

# ✅ 正确：代码和文档一起提交
git add lib/core/api/authentication.dart
git add docs/api-authentication.md
git commit -m "feat: 实现 JWT 认证

- 新增 JWT 认证服务
- 更新 API 认证文档

🤖 Generated with [Claude Code](https://claude.com/claude-code)

Co-Authored-By: Claude Sonnet 4.5 <noreply@anthropic.com>"

# ❌ 错误：先提交代码，文档稍后补
git commit -m "feat: 实现 JWT 认证"  # 遗漏文档

3. 使用 Claude 辅助维护

场景1：创建新文档时

用户：我需要创建一个 API 设计规范文档
Claude：我检测到你要创建新文档，让我帮你确认：

📋 文档归档检查清单：
□ 推荐层级：Layer 5（专项技术）
□ 推荐文件名：docs/api-design.md（kebab-case）
□ 需要更新：docs/README.md, CHANGELOG.md

是否现在一起创建？

场景2：修改代码后

用户：我刚修改了数据库表结构
Claude：⚠️ 检测到数据库变更，需要更新以下文档：
□ docs/database/schema.md - 更新表结构定义
□ CLAUDE.md - 更新"项目当前状态"章节
□ CHANGELOG.md - 记录本次变更

是否现在一起更新这些文档？

场景3：大量修改后

Claude：⚠️ 检测到大量文档修改（8个）

建议运行文档一致性检查：
bash scripts/doc-consistency-check.sh

是否现在运行检查？

4. 定期文档审查

月度审查（简化版）：

bash

# 1. 查看最近修改的文档
find docs/ -name "*.md" -mtime -30 -exec ls -lh {} \;

# 2. 检查文档一致性
bash scripts/doc-consistency-check.sh

# 3. 审查 CHANGELOG.md 的 Unreleased 章节

季度审查（完整版）：

bash

# 1. 生成文档架构审查报告
bash scripts/doc-architecture-review.sh

# 2. 审查各层文档数量是否合理

# 3. 检查是否有过时文档需要归档

# 4. 验证自动化机制是否正常
#    - Claude 自动提醒
#    - Pre-commit hook

# 5. 团队讨论架构演进
#    - 是否需要调整层级定义
#    - 是否需要新的文档类型

5. 文档模板化

为常见文档类型创建模板：

模板1：技术决策记录（ADR）

markdown

# ADR-XXX: [决策标题]

**日期**：YYYY-MM-DD
**状态**：提议中 / 已接受 / 已废弃
**决策者**：[姓名]

## 背景

[描述问题和上下文]

## 决策

[我们决定做什么]

## 理由

[为什么做这个决策]

## 后果

**优点**：
- [列出优点]

**缺点**：
- [列出缺点]

**风险**：
- [列出风险]

## 替代方案

[考虑过哪些其他方案，为什么不选]

## 相关决策

- [ADR-001](decisions.md#adr-001)

模板2：工具使用指南

markdown

# [工具名称] 使用指南

## 简介

[1-2句话描述工具的用途]

## 前置条件

- [依赖项1]
- [依赖项2]

## 安装

\`\`\`bash
[安装命令]
\`\`\`

## 使用方法

### 基本用法

\`\`\`bash
[基本命令]
\`\`\`

### 高级用法

[更复杂的场景]

## 常见问题

### Q1：[问题]
A：[解答]

## 故障排查

[常见错误和解决方案]

## 相关文档

- [文档1](link)

6. 使用 Git 分支保护重要文档

对于核心文档（CLAUDE.md, design.md 等）：

bash

# 创建 feature 分支进行大改
git checkout -b feature/update-architecture-docs

# 修改文档
vim docs/design.md

# 提交并创建 PR
git add docs/design.md
git commit -m "docs: 重构架构设计文档"
git push origin feature/update-architecture-docs

# PR Review 后再合并到主分支

好处：

✅ 重要文档变更经过 Code Review
✅ 避免误操作破坏文档
✅ 保留完整的变更历史

📚 附录

A. 完整的命令参考

文档创建

bash

# 创建新文档
touch docs/new-document.md

# 使用模板创建
cp docs/templates/guide-template.md docs/new-guide.md

文档查找

bash

# 按文件名查找
find docs/ -name "*api*"

# 按内容查找
grep -r "关键词" docs/ --include="*.md"

# 按修改时间查找
find docs/ -name "*.md" -mtime -7  # 最近7天

文档验证

bash

# 运行文档一致性检查
bash scripts/doc-consistency-check.sh

# 检查命名规范
find docs/ -name "*.md" | grep -E "[A-Z_]"  # 查找不符合 kebab-case 的文件

# 检查断链
grep -roh "\[.*\](\(.*\.md\))" docs/ | sed 's/.*(\(.*\))/\1/' | while read link; do
  [ ! -f "$link" ] && echo "❌ $link"
done

文档统计

bash

# 统计文档数量
find docs/ -name "*.md" | wc -l

# 统计文档总大小
du -sh docs/

# 统计各层文档数量
echo "Layer 1: $(ls -1 README.md QUICKSTART.md docs/README.md 2>/dev/null | wc -l)"
# ... (见"维护检查清单"章节)

Git 操作

bash

# 查看文档变更
git status
git diff docs/

# 暂存文档
git add docs/new-document.md
git add docs/README.md
git add CHANGELOG.md

# 提交文档
git commit -m "docs: 新增文档

🤖 Generated with [Claude Code](https://claude.com/claude-code)

Co-Authored-By: Claude Sonnet 4.5 <noreply@anthropic.com>"

# 重命名文档
git mv docs/old-name.md docs/new-name.md

B. 脚本列表和说明

1. scripts/doc-consistency-check.sh

功能：检查文档一致性

检查内容：

Schema 版本号一致性
文档断链
数据一致性

使用方法：

bash

bash scripts/doc-consistency-check.sh

2. scripts/doc-architecture-review.sh

功能：生成文档架构审查报告（季度审查）

输出内容：

各层文档数量统计
超标警告
建议操作

使用方法：

bash

bash scripts/doc-architecture-review.sh > reports/doc-review-2026-Q1.txt

注意：此脚本可能不存在，需要创建。

3. .git/hooks/pre-commit

功能：Git 提交前自动检查

检查内容：

新增文档命名规范
导航更新检查
层级归属提示
调用文档一致性检查脚本

使用方法：

bash

# 自动运行（git commit 时）
git commit -m "..."

# 手动测试
.git/hooks/pre-commit

# 跳过检查
git commit --no-verify -m "..."

4. scripts/test-doc-maintenance.sh

功能：测试文档维护机制（可选，需要创建）

测试场景：

场景1：新文档创建流程
场景2：命名规范检查
场景3：导航更新检查

使用方法：

bash

bash scripts/test-doc-maintenance.sh

C. 相关文档链接

核心文档

CLAUDE.md - 项目总览和 Claude 指令
docs/README.md - 文档导航（7层架构）
CHANGELOG.md - 变更日志

规范文档

docs/development.md - 代码规范和开发指南
docs/design.md - 架构设计
docs/decisions.md - 技术决策记录（ADR）

指南文档

QUICKSTART.md - 5分钟快速开始

📞 联系和反馈

如有任何问题或建议，请：

提交 Issue（推荐）：在项目 Issue 中描述问题
更新文档：发现错误直接修改并提交 PR
团队讨论：重大变更前先团队讨论

最后更新：2026-01-28 维护者：项目团队 文档版本：v1.0

文档架构维护指南 ​

📖 文档简介 ​

目的 ​

使用场景 ​

7层文档架构概览 ​

🚀 快速参考（5分钟速查） ​

新增文档决策树 ​

常见场景快速查找表 ​

命令速查卡片 ​

📋 详细流程 ​

3.1 新增文档流程 ​

Step 1：决策是否需要新文档 ​

Step 2：确定层级归属 ​

Layer 1（项目入口）- ❌ 不允许新增 ​

Layer 2（产品业务）- ⚠️ 谨慎新增 ​

Layer 3（开发规范）- ✅ 允许新增 ​

Layer 4（架构设计）- ⚠️ 优先记录到 decisions.md ​

Layer 5（专项技术）- ✅ 允许新增 ​

Layer 6（辅助工具）- ✅ 允许新增 ​

Layer 7（自动化维护）- ✅ 允许新增 ​

Step 3：命名和放置 ​

命名规范 ​

放置位置 ​

Step 4：同步更新导航 ​

1. docs/README.md（导航文件） ​

2. CHANGELOG.md（Unreleased 章节） ​

3. CLAUDE.md（如果是核心文档） ​

Step 5：提交和验证 ​

提交前检查 ​

Git 提交 ​

Pre-commit hook 会自动检查 ​

3.2 修改现有文档流程 ​

何时需要更新其他文档 ​

保持文档间引用一致性 ​

3.3 删除/归档文档流程 ​

归档原则 ​

更新所有引用 ​

🎯 层级归属决策指南 ​

典型案例分析（10个实例） ​

案例1：新增"性能优化指南" ​

案例2：新增"代码审查规范" ​

案例3：新增"用户调研报告 2026" ​

案例4：新增"Flutter 组件测试指南" ​

案例5：新增"GitHub Actions 工作流说明" ​

案例6：新增"Clean Architecture 迁移方案" ​

案例7：新增"Supabase Edge Function 部署" ​

案例8：新增"词汇构建工具使用说明" ​

案例9：新增"技术决策：选择 Riverpod" ​

案例10：新增"Material 3 按钮样式规范" ​

边界案例处理 ​

案例A：跨层级文档 ​

案例B：文档数量超过警戒阈值 ​

案例C：命名冲突 ​

📐 命名规范详解 ​

kebab-case 规范（docs/） ​

UPPER_CASE 规范（根目录） ​

特殊命名约定 ​

1. schema.md - 数据库表结构 ​

2. xxx-guide.md - 指南类文档 ​

3. xxx-setup-guide.md - 配置指南 ​

4. README.md - 目录说明 ​

🤖 自动化机制使用 ​

Claude 自动提醒机制 ​

触发条件1：新文档创建 ​

触发条件2：大量文档修改 ​

触发条件3：文档数量超标 ​

Git Hooks 工作原理 ​

Pre-commit Hook 流程 ​

检查示例 ​

如何处理检查失败 ​

✅ 维护检查清单 ​

日常检查清单 ​

季度审查清单 ​

检查命令和脚本 ​

1. 文档一致性检查 ​

2. 统计各层文档数量 ​

3. 查找最近修改的文档 ​

4. 检查断链 ​

5. 验证 Pre-commit Hook ​

❓ 常见问题 FAQ ​

文档架构维护指南

📖 文档简介

目的

使用场景

7层文档架构概览

🚀 快速参考（5分钟速查）

新增文档决策树

常见场景快速查找表

命令速查卡片

📋 详细流程

3.1 新增文档流程

Step 1：决策是否需要新文档

Step 2：确定层级归属

Layer 1（项目入口）- ❌ 不允许新增

Layer 2（产品业务）- ⚠️ 谨慎新增

Layer 3（开发规范）- ✅ 允许新增

Layer 4（架构设计）- ⚠️ 优先记录到 decisions.md

Layer 5（专项技术）- ✅ 允许新增

Layer 6（辅助工具）- ✅ 允许新增

Layer 7（自动化维护）- ✅ 允许新增

Step 3：命名和放置

命名规范

放置位置

Step 4：同步更新导航

1. docs/README.md（导航文件）

2. CHANGELOG.md（Unreleased 章节）

3. CLAUDE.md（如果是核心文档）

Step 5：提交和验证

提交前检查

Git 提交

Pre-commit hook 会自动检查

3.2 修改现有文档流程

何时需要更新其他文档

保持文档间引用一致性

3.3 删除/归档文档流程

归档原则

更新所有引用

🎯 层级归属决策指南

典型案例分析（10个实例）

案例1：新增"性能优化指南"

案例2：新增"代码审查规范"

案例3：新增"用户调研报告 2026"

案例4：新增"Flutter 组件测试指南"

案例5：新增"GitHub Actions 工作流说明"

案例6：新增"Clean Architecture 迁移方案"

案例7：新增"Supabase Edge Function 部署"

案例8：新增"词汇构建工具使用说明"

案例9：新增"技术决策：选择 Riverpod"

案例10：新增"Material 3 按钮样式规范"

边界案例处理

案例A：跨层级文档

案例B：文档数量超过警戒阈值

案例C：命名冲突

📐 命名规范详解

kebab-case 规范（docs/）

UPPER_CASE 规范（根目录）

特殊命名约定

1. schema.md - 数据库表结构

2. xxx-guide.md - 指南类文档

3. xxx-setup-guide.md - 配置指南

4. README.md - 目录说明

🤖 自动化机制使用

Claude 自动提醒机制

触发条件1：新文档创建

触发条件2：大量文档修改

触发条件3：文档数量超标

Git Hooks 工作原理

Pre-commit Hook 流程

检查示例

如何处理检查失败

✅ 维护检查清单

日常检查清单

季度审查清单

检查命令和脚本

1. 文档一致性检查

2. 统计各层文档数量

3. 查找最近修改的文档

4. 检查断链

5. 验证 Pre-commit Hook

❓ 常见问题 FAQ