# Docs Manager

> 文档管理专家，负责维护项目的 docs/ 目录和 CLAUDE.md 索引。用户通过 slash command 主动触发，可能的场景包括：根据技术文档整理规范文档、根据代码整理规范文档、新功能开发后补充文档、修改代码后更新文档。

- Skill: `stvlynn/docs-manager` (Agent Skill)
- Install (CLI): `npx skillmds@latest add stvlynn/docs-manager`
- Raw SKILL.md: https://api.skillmd.com/api/skills/stvlynn/docs-manager/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Coding & Dev Tools
- Author: stvlynn (https://skillmd.com/u/stvlynn)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/stvlynn/docs-manager

---


# Docs Manager

> **Skill Directory**: `.agents/skills/docs-manager/`
> All bundled resource paths below (scripts, references, assets) are relative to this directory.

## 职责

维护项目文档，确保文档与代码实现保持一致。文档是代码仓库的核心和灵魂。

## 工作流程

### Step 1: 理解用户需求

明确用户想要记录什么内容：
- 新功能/模块的文档？
- 现有功能的补充说明？
- 代码规范/约定？![alt text]![alt text]
- 技术方案/架构设计？

### Step 2: 获取当前文档目录结构

```bash
tree docs
```

通过目录树判断是否已有相关文档：
- **已存在相关文档** → 进入"补充模式"
- **不存在相关文档** → 进入"新增模式"

### Step 3a: 补充模式

原则：**最小改动，不做非必要改动**

1. 先读取现有文档全文
2. 分析需要补充的内容应该放在哪个位置
3. 选择合适的方式：
   - 在现有章节追加内容
   - 新增章节
   - 修改现有描述使其更准确
4. 保持文档风格一致

### Step 3b: 新增模式

1. 根据 tree 输出的目录结构，确定合适的分类目录
2. 如需新增分类目录，先确认是否合理
3. 创建文档，遵循项目风格：
   - 使用中文
   - 标题层级清晰
   - 包含必要的代码示例
   - 说明文件路径时使用相对路径

### Step 3c: 拆分模式

**核心原则**：拆分的目的是让 code agent 按需读取，避免读到大量无关内容。

**判断是否需要拆分**：

1. **使用场景是否一致**（最重要）
   - 写某个功能时，这些章节是否需要一起参考？
   - 如果是 → 不拆分，即使超过 800 行
   - 如果不是 → 考虑拆分

2. **主题是否紧密相关**
   - 内容是否属于同一个知识领域？
   - 例：DATABASE.md 的 Schema + Migration + 操作 → 紧密相关，不拆

3. **行数作为辅助参考**
   - 超过 800 行时**考虑**是否有不同使用场景的内容
   - 不是硬性拆分标准

**拆分示例**：

```
# UI_PATTERNS.md 的拆分分析

章节 1-7（头像、标签、图标）→ 写列表/卡片组件时需要
章节 8-11（管理端页面、表格）→ 写管理后台时需要
章节 12（思考过程）→ 写对话组件时需要

分析：使用场景有差异，但内容都是 UI 规范，可以保持一个文档
结论：暂不拆分，通过章节标题定位即可
```

**拆分策略**：

1. **按使用场景拆分**（推荐）
   - 不同功能开发时需要的内容 → 拆分
   - 原文档保留概述 + 链接索引

2. **层级引用结构**
   - CLAUDE.md → 大模块文档（索引）→ 小模块文档（详细）
   - 大模块文档负责：概述 + 引用子文档链接
   - 小模块文档负责：具体规范内容

**层级引用示例**：

```markdown
# CLAUDE.md 中
- [意图控制](docs/features/intent-control/README.md) - 意图识别与路由

# docs/features/intent-control/README.md 中
## 详细文档
- [Intent Router](INTENT_ROUTER.md) - Two-Pass 意图路由引擎
- [意图配置](INTENT_CONFIG.md) - 意图库管理
```

### Step 3d: 目录整理模式

**触发条件**：
- 某分类下文档超过 5 个
- 文档间存在明显的子分类关系
- 新增文档不确定放哪个分类

**整理策略**：

1. **增加子目录**
   ```
   # 整理前
   docs/features/
   ├── agent-edit.md
   ├── agent-list.md
   ├── agent-config.md
   └── ...

   # 整理后
   docs/features/agent-management/
   ├── README.md          # 概述 + 索引
   ├── AGENT_EDIT.md      # 编辑功能
   └── AGENT_CONFIG.md    # 配置功能
   ```

2. **使用 archive 子目录**
   - 历史文档、实施记录放入 `archive/`
   - 保持主目录简洁
   - 示例：`docs/features/observability/archive/`

3. **README.md 作为目录索引**
   - 每个功能目录都应有 `README.md`
   - 列出该目录下所有文档的简介和链接

### Step 4: 检查文档长度

**在完成内容编写后，检查文档行数**：

```bash
wc -l <文档路径>
```

| 行数 | 状态 | 处理方式 |
|------|------|----------|
| < 300 | ✅ 良好 | 无需处理 |
| 300-600 | ⚠️ 关注 | 检查使用场景是否一致 |
| 600-1000 | ⚠️ 评估 | 分析是否有不同使用场景的内容 |
| > 1000 | ❌ 强烈建议拆分 | 大概率存在可拆分内容 |

**注意**：行数只是参考，核心判断标准是"使用场景一致性"。

### Step 5: 检查是否需要更新 CLAUDE.md

**⚠️ 对 CLAUDE.md 的改动务必慎重，只能修改文档索引部分，不可修改其他无关内容。**

**需要更新的情况：**
- 新增了文档 → 在对应分类下添加链接
- 删除了文档 → 移除对应链接
- 文档功能有重大变化 → 更新该文档的简短说明
- 拆分了文档 → 更新原文档描述，添加新文档链接

**操作原则：最小改动**
- 只修改文档链接列表部分
- 保持现有格式和缩进
- 不修改其他章节

### Step 6: 验证

1. 检查新文档/修改的文档格式是否正确
2. 确认链接路径正确
3. 如果修改了 CLAUDE.md，确认索引结构完整

## 文档风格指南

### 标题规范

```markdown
# 一级标题（文档名）

## 二级标题（主要章节）

### 三级标题（子章节）
```

### 代码示例规范

- 明确指定语言：\`\`\`typescript / \`\`\`bash
- 包含文件路径注释（如果是项目代码）

```typescript
// apps/web/src/pages/xxx/index.tsx
export function XxxPage() { ... }
```

### 文件路径规范

- 使用相对于项目根目录的路径
- 示例：`apps/web/src/components/` 而非绝对路径

## 文档质量要求

### 核心原则

文档是**精简的规范文档**，目的是让 AI/开发者按规范写代码，保证风格一致。

### ✅ 好文档的特征

1. **有具体规范** - 告诉读者"怎么写"，而非"是什么"
2. **有代码示例** - 可直接复制使用的示例代码
3. **有禁止事项** - 明确 ❌ 禁止的写法
4. **精简不废话** - 每句话都有存在价值

### ❌ 差文档的特征

1. **只是功能介绍** - 只说"有什么功能"，不说"怎么写"
2. **缺乏代码示例** - 全是文字描述，没有可参考的代码
3. **过于冗长** - 大段解释，没有重点
4. **信息重复** - 在多处重复相同内容

### 参考模板

好的规范文档结构：

```markdown
# 功能/模块名

> 一句话说明

---

## 核心规范

### 规范 1：XXX

**规则**：具体要求

```tsx
// ✅ 正确写法
代码示例

// ❌ 错误写法
反例代码
```

### 规范 2：YYY

...

---

## 代码位置

| 模块 | 路径 | 说明 |
|------|------|------|
| 前端页面 | `pages/xxx/` | ... |
| 后端服务 | `services/xxx.ts` | ... |

---

## 常见问题

Q: ...
A: ...
```

## 注意事项

- 文档是给 AI Agent 和开发者看的，要简洁明了
- 避免冗余，一个信息只在一处记录
- 优先记录"怎么做"而非"是什么"
- 规范类文档要有具体示例
- 功能文档要说明核心代码路径