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: 获取当前文档目录结构

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 → 大模块文档（索引）→ 小模块文档（详细）
   • 大模块文档负责：概述 + 引用子文档链接
   • 小模块文档负责：具体规范内容

层级引用示例：

# 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: 检查文档长度

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

wc -l <文档路径>

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

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

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

需要更新的情况：

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

操作原则：最小改动

• 只修改文档链接列表部分
• 保持现有格式和缩进
• 不修改其他章节

Step 6: 验证

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

文档风格指南

标题规范

# 一级标题（文档名）

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

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

代码示例规范

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

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

文件路径规范

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

文档质量要求

核心原则

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

✅ 好文档的特征

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

❌ 差文档的特征

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

参考模板

好的规范文档结构：

# 功能/模块名

> 一句话说明

---

## 核心规范

### 规范 1：XXX

**规则**：具体要求

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

// ❌ 错误写法
反例代码

规范 2：YYY

...

代码位置

常见问题

Q: ... A: ...

## 注意事项

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