| name | docs-manager |
| description | 文档管理专家，负责维护项目的 docs/ 目录和 CLAUDE.md 索引。用户通过 slash command 主动触发，可能的场景包括：根据技术文档整理规范文档、根据代码整理规范文档、新功能开发后补充文档、修改代码后更新文档。 |
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: 获取当前文档目录结构
tree docs
通过目录树判断是否已有相关文档：
- 已存在相关文档 → 进入"补充模式"
- 不存在相关文档 → 进入"新增模式"
Step 3a: 补充模式
原则：最小改动，不做非必要改动
- 先读取现有文档全文
- 分析需要补充的内容应该放在哪个位置
- 选择合适的方式：
- 在现有章节追加内容
- 新增章节
- 修改现有描述使其更准确
- 保持文档风格一致
Step 3b: 新增模式
- 根据 tree 输出的目录结构，确定合适的分类目录
- 如需新增分类目录，先确认是否合理
- 创建文档，遵循项目风格：
- 使用中文
- 标题层级清晰
- 包含必要的代码示例
- 说明文件路径时使用相对路径
Step 3c: 拆分模式
核心原则：拆分的目的是让 code agent 按需读取，避免读到大量无关内容。
判断是否需要拆分：
-
使用场景是否一致（最重要）
- 写某个功能时，这些章节是否需要一起参考？
- 如果是 → 不拆分，即使超过 800 行
- 如果不是 → 考虑拆分
-
主题是否紧密相关
- 内容是否属于同一个知识领域？
- 例：DATABASE.md 的 Schema + Migration + 操作 → 紧密相关，不拆
-
行数作为辅助参考
- 超过 800 行时考虑是否有不同使用场景的内容
- 不是硬性拆分标准
拆分示例：
# UI_PATTERNS.md 的拆分分析
章节 1-7（头像、标签、图标）→ 写列表/卡片组件时需要
章节 8-11（管理端页面、表格）→ 写管理后台时需要
章节 12（思考过程）→ 写对话组件时需要
分析：使用场景有差异，但内容都是 UI 规范，可以保持一个文档
结论：暂不拆分，通过章节标题定位即可
拆分策略：
-
按使用场景拆分（推荐）
- 不同功能开发时需要的内容 → 拆分
- 原文档保留概述 + 链接索引
-
层级引用结构
- CLAUDE.md → 大模块文档（索引）→ 小模块文档（详细）
- 大模块文档负责：概述 + 引用子文档链接
- 小模块文档负责：具体规范内容
层级引用示例：
# 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 个
- 文档间存在明显的子分类关系
- 新增文档不确定放哪个分类
整理策略：
-
增加子目录
# 整理前
docs/features/
├── agent-edit.md
├── agent-list.md
├── agent-config.md
└── ...
# 整理后
docs/features/agent-management/
├── README.md # 概述 + 索引
├── AGENT_EDIT.md # 编辑功能
└── AGENT_CONFIG.md # 配置功能
-
使用 archive 子目录
- 历史文档、实施记录放入
archive/
- 保持主目录简洁
- 示例：
docs/features/observability/archive/
-
README.md 作为目录索引
- 每个功能目录都应有
README.md
- 列出该目录下所有文档的简介和链接
Step 4: 检查文档长度
在完成内容编写后，检查文档行数：
wc -l <文档路径>
| 行数 | 状态 | 处理方式 |
|---|
| < 300 | ✅ 良好 | 无需处理 |
| 300-600 | ⚠️ 关注 | 检查使用场景是否一致 |
| 600-1000 | ⚠️ 评估 | 分析是否有不同使用场景的内容 |
| > 1000 | ❌ 强烈建议拆分 | 大概率存在可拆分内容 |
注意：行数只是参考，核心判断标准是"使用场景一致性"。
Step 5: 检查是否需要更新 CLAUDE.md
⚠️ 对 CLAUDE.md 的改动务必慎重，只能修改文档索引部分，不可修改其他无关内容。
需要更新的情况：
- 新增了文档 → 在对应分类下添加链接
- 删除了文档 → 移除对应链接
- 文档功能有重大变化 → 更新该文档的简短说明
- 拆分了文档 → 更新原文档描述，添加新文档链接
操作原则：最小改动
- 只修改文档链接列表部分
- 保持现有格式和缩进
- 不修改其他章节
Step 6: 验证
- 检查新文档/修改的文档格式是否正确
- 确认链接路径正确
- 如果修改了 CLAUDE.md，确认索引结构完整
文档风格指南
标题规范
# 一级标题（文档名）
## 二级标题（主要章节）
### 三级标题（子章节）
代码示例规范
- 明确指定语言：```typescript / ```bash
- 包含文件路径注释（如果是项目代码）
export function XxxPage() { ... }
文件路径规范
- 使用相对于项目根目录的路径
- 示例：
apps/web/src/components/ 而非绝对路径
文档质量要求
核心原则
文档是精简的规范文档，目的是让 AI/开发者按规范写代码，保证风格一致。
✅ 好文档的特征
- 有具体规范 - 告诉读者"怎么写"，而非"是什么"
- 有代码示例 - 可直接复制使用的示例代码
- 有禁止事项 - 明确 ❌ 禁止的写法
- 精简不废话 - 每句话都有存在价值
❌ 差文档的特征
- 只是功能介绍 - 只说"有什么功能"，不说"怎么写"
- 缺乏代码示例 - 全是文字描述，没有可参考的代码
- 过于冗长 - 大段解释，没有重点
- 信息重复 - 在多处重复相同内容
参考模板
好的规范文档结构：
# 功能/模块名
> 一句话说明
---
## 核心规范
### 规范 1：XXX
**规则**：具体要求
```tsx
// ✅ 正确写法
代码示例
// ❌ 错误写法
反例代码
规范 2：YYY
...
代码位置
| 模块 | 路径 | 说明 |
|---|
| 前端页面 | pages/xxx/ | ... |
| 后端服务 | services/xxx.ts | ... |
常见问题
Q: ...
A: ...
## 注意事项
- 文档是给 AI Agent 和开发者看的，要简洁明了
- 避免冗余，一个信息只在一处记录
- 优先记录"怎么做"而非"是什么"
- 规范类文档要有具体示例
- 功能文档要说明核心代码路径
