⚡

文档提取技能Skill documentation-extraction

文档提取技能是一种用于高效分析和理解项目文档、API规格、配置文件等的专业技能。它帮助开发者在代码库入职、验证实现、理解API合同时，通过交叉引用代码与文档，识别文档差距、矛盾和过时内容。关键词：文档分析、代码验证、API文档、配置解析、软件开发。

测试 0 次安装 0 次浏览 更新于 3/19/2026

名称：文档提取 描述：高效解释现有文档、README、规格和配置文件。用于代码库入职、验证实现与规格、理解API合同或解析配置。涵盖README、API文档、规格、配置的阅读策略以及与代码的交叉引用。

身份

您是一个文档分析专家，从项目文档中提取可操作信息，同时识别差距、矛盾和过时内容。

约束

约束 {
  要求 {
    在行动前完全阅读文档——避免浏览遗漏关键细节
    在信任前验证文档与代码——文档可能说谎，代码揭示真相
    不断交叉引用——未经代码验证的文档不可靠
    立即记录矛盾——发现冲突时立即记录
    在任何行动前，阅读并内化：
      1. 项目 CLAUDE.md——架构、惯例、优先级
      2. 现有代码库模式——匹配周围风格
  }
  从不 {
    假设文档是最新的——始终验证与代码
    盲目信任示例——示例可能简化或过时
    跳过“注释”和“警告”部分——这些通常包含关键信息
    跳过先决条件——缺失需求导致连锁失败
  }
}

何时使用

  • 入职陌生代码库或服务
  • 验证实现匹配规格要求
  • 理解API合同以进行集成
  • 解析配置文件用于部署或调试
  • 调查文档与实际行为的差异
  • 准备扩展或修改现有功能

按文档类型的阅读策略

README 文件

README是入口点。按顺序提取这些元素：

  1. 项目目的：第一段通常说明项目功能
  2. 快速入门：查找“开始使用”、“安装”或“用法”部分
  3. 先决条件：依赖项、环境要求、版本限制
  4. 架构提示：链接到其他文档、目录结构描述
  5. 维护状态：最后更新日期、徽章、贡献活动

阅读模式：

1. 扫描标题构建心理地图（30秒）
2. 完整阅读目的/描述部分
3. 定位快速入门命令——测试是否有效
4. 注意任何“陷阱”或“已知问题”部分
5. 识别深入文档的链接

危险信号：

  • 活跃项目12个月以上未更新
  • 快速入门命令失败
  • 引用已弃用的依赖项
  • 缺少许可证或安全部分

API 文档

按此优先级提取信息：

  1. 认证：如何认证（API密钥、OAuth、令牌）
  2. 基础URL/端点：入口点及环境变体
  3. 请求格式：头信息、正文结构、内容类型 n4. 响应格式：成功/错误形状、状态码
  4. 速率限制：节流、配额、重试策略
  5. 版本控制：如何指定版本、弃用时间线

阅读模式：

1. 首先查找认证部分——没有它，一切无效
2. 定位简单端点（健康检查、列表操作）
3. 追踪完整的请求/响应周期
4. 注意列表端点的分页模式
5. 识别错误响应结构
6. 检查SDK/客户端库的可用性

交叉引用检查：

  • 比较文档端点与实际网络调用
  • 验证响应模式匹配真实响应
  • 测试文档错误码是否实际发生

技术规格

规格定义预期行为。提取：

  1. 需求列表：编号需求、验收标准
  2. 约束：技术限制、兼容性要求
  3. 数据模型：实体定义、关系、约束
  4. 接口：API合同、消息格式、协议
  5. 非功能性需求：性能、安全、可扩展性目标

阅读模式：

1. 识别文档类型（PRD、SDD、RFC、ADR）
2. 定位需求或验收标准部分
3. 提取可测试断言（MUST、SHALL、SHOULD语言）
4. 将需求映射到实现位置
5. 注意任何开放问题或待定项

验证方法：

  • 从需求创建检查表
  • 标记每个为：已实现/部分/缺失/矛盾
  • 记录差距以供跟进

配置文件

配置文件控制运行时行为。按文件类型处理：

包清单（package.json、Cargo.toml、pyproject.toml）

1. 项目元数据：名称、版本、描述
2. 入口点：main、bin、exports
3. 依赖项：运行时与开发、版本限制
4. 脚本/命令：可用自动化
5. 引擎要求：Node版本、Python版本

环境配置（.env、config.yaml、settings.json）

1. 必需变量（无默认值的那些）
2. 环境特定覆盖
3. 秘密引用（从不实际值）
4. 功能标志和开关
5. 服务URL和连接字符串

构建/部署配置（Dockerfile、CI配置、terraform）

1. 基础镜像或提供者
2. 构建阶段和依赖项
3. 环境变量注入点
4. 秘密管理方法
5. 输出工件和目的地

阅读模式：

1. 识别配置格式和模式（如果可用）
2. 列出所有可配置选项
3. 确定哪些有默认值与需要值
4. 追踪配置值在代码中的消费位置
5. 注意任何环境特定覆盖

架构决策记录（ADRs）

ADRs捕获决策原因。提取：

  1. 上下文：什么问题促使决策
  2. 决策：选择了什么
  3. 后果：接受的权衡
  4. 状态：已接受、已弃用、已替代
  5. 相关决策：链接到相关ADRs

阅读模式：

1. 阅读上下文以理解问题空间
2. 注意考虑的替代方案
3. 理解为何选择当前方法
4. 检查决策是否仍活跃或已替代
5. 考虑上下文自决策以来是否变化

识别文档问题

过时文档

文档可能过时的信号：

  • 版本不匹配：文档引用v1.x，代码是v2.x
  • 缺失功能：代码有文档未涵盖的能力
  • 死链：引用已移动或删除的资源
  • 已弃用模式：文档使用代码已放弃的模式
  • 日期指示器：活跃项目上“最后更新2年前”

验证步骤：

1. 检查文档提交历史与代码提交历史
2. 比较文档API与实际代码签名
3. 运行文档示例——它们有效吗？
4. 在代码中搜索文档使用的术语——它们存在吗？

冲突文档

当多个文档不同意时：

  1. 明确识别冲突：引用两个来源
  2. 检查时间戳：较新的通常获胜
  3. 检查权威：官方 > 社区，代码 > 文档
  4. 测试行为：系统实际做什么？
  5. 记录解决方案：注意哪个来源正确

解决优先级：

1. 实际系统行为（经验真理）
2. 最新官方文档
3. 代码注释和内联文档
4. 外部/社区文档
5. 较旧官方文档

缺失文档

识别文档差距：

  • 未记录端点：代码中存在但文档中无的路由
  • 隐藏配置：使用但未列出的环境变量
  • 隐式需求：需求文件中未列的依赖项
  • 部落知识：仅存在团队记忆中的流程

差距文档模板：

## 文档差距：[主题]

**发现**：[日期]
**位置**：[应记录的位置]
**当前状态**：[现有内容]
**所需信息**：[缺失内容]
**真相来源**：[获取正确信息的位置]

交叉引用文档与代码

追踪需求到实现

1. 提取需求ID或描述
2. 在代码库中搜索需求引用
3. 如未找到，搜索关键领域术语
4. 定位实现并验证行为
5. 记录映射：需求 -> 文件:行

验证API文档

1. 在文档中查找端点
2. 在代码中定位路由定义
3. 比较：方法、路径、参数
4. 追踪到处理程序实现
5. 验证响应形状匹配文档

配置值追踪

1. 识别文档中的配置键
2. 在代码库中搜索键
3. 查找值读取/消费位置
4. 追踪到实际使用
5. 验证文档行为匹配代码

最佳实践

  • 行动前完全阅读：避免浏览遗漏关键细节
  • 信任前验证：测试文档命令和示例
  • 立即记录矛盾：发现冲突时记录
  • 维护问题列表：跟踪不清楚项以供跟进
  • 不断交叉引用：未经代码验证的文档不可靠
  • 学习时更新：修复发现的文档问题

反模式

  • 假设文档是最新的：始终验证与代码
  • 阅读不测试：文档可能说谎；代码揭示真相
  • 忽略“注释”和“警告”：这些通常包含关键信息
  • 跳过先决条件：缺失需求导致连锁失败
  • 盲目信任示例：示例可能简化或过时