blueprint-curate-docs

/blueprint:curate-docs

将库或项目文档整理为 .claude/rules/ 条目，为 AI Agent 优化内容——提供简洁、可操作且考虑常见陷阱的上下文，这些内容会自动加载到会话中，也可在 PRP 中引用。

注意： 较早版本的 blueprint 会将这些条目写入 docs/blueprint/ai_docs/。该位置已弃用——.claude/rules/ 是整理后 AI 上下文的规范位置，因为 Claude Code 会原生加载规则，并将其分享给每位贡献者。

用法：/blueprint:curate-docs [library-name] 或 /blueprint:curate-docs project:[pattern-name]

何时使用此技能

在以下情况下使用此技能……	在以下情况下使用替代方式……
记录库的常见陷阱，以便在 PRP/上下文中复用	为临时任务阅读原始文档
将项目模式编纂为规则	一次性使用库
在 .claude/rules/ 下构建知识库	开展常规库调研

上下文

• 规则目录：!find . -maxdepth 2 -type d -name rules -path '*/.claude/*'
• 现有规则：!find . -maxdepth 3 -path '*/.claude/rules/*' -name "*.md" -type f
• 规则路径覆盖项：!find . -maxdepth 3 -path '*/docs/blueprint/manifest.json' -exec jq -r '.structure.generated_rules_path // ".claude/rules/"' {} +
• 依赖中的库：!find . -maxdepth 1 \( -name package.json -o -name pyproject.toml -o -name requirements.txt \) -exec grep -m1 "^$1[\":@=]" {} +

参数

解析 $ARGUMENTS：

• library-name：要记录的库名称（例如，redis、pydantic）
  • 位置：$RULES_DIR/lib-[library-name].md
  • 或使用 project:[pattern-name] 指定项目模式
  • 位置：$RULES_DIR/[pattern-name].md

如果已设置，$RULES_DIR 为 docs/blueprint/manifest.json 中的 structure.generated_rules_path，否则为 .claude/rules/。

执行

执行完整的文档整理工作流：

步骤 1：确定目标并检查现有规则

1. 解析参数，确定目标是库还是项目模式
2. 解析 $RULES_DIR（manifest 中的 structure.generated_rules_path，默认为 .claude/rules/）
3. 检查 $RULES_DIR 中是否已存在针对该库/模式的规则
4. 如果存在 → 询问：原位更新还是跳过？
5. 检查项目依赖中的库版本

步骤 2：调研并收集文档

对于库：

• 查找官方文档 URL
• 搜索与项目用例相关的具体章节
• 查找已知问题和常见陷阱（WebSearch："{library} common issues"、"{library} gotchas"）
• 使用 WebFetch 提取关键章节

对于项目模式：

• 在代码库中搜索模式实现：grep -r "{pattern}" src/
• 确定其使用位置和方式
• 记录约定和变体
• 从项目中提取真实代码示例

步骤 3：提取关键信息

1. 用例：此库/模式在项目中的使用方式和原因
2. 常见操作：最频繁的用法
3. 我们使用的模式：项目特定实现（附文件引用）
4. 配置：此项目中的配置方式
5. 常见陷阱：特定版本的行为、常见错误、性能隐患、安全注意事项

常见陷阱的来源：GitHub issues、Stack Overflow、团队经验、官方文档警告。

步骤 4：创建规则条目

在 $RULES_DIR/lib-[library-name].md 或 $RULES_DIR/[pattern-name].md 创建文件（参见 REFERENCE.md）。

绝不要覆盖人工编写的规则。 如果目标名称的文件已存在，且并非由此技能生成，请使用不同的名称（例如 lib-[library-name]-gotchas.md），或询问用户。

包含模板中的所有章节：Quick Reference、Patterns We Use、Configuration、Gotchas、Testing、Examples。

总长度控制在 200 行以内。

第 5 步：添加代码示例

添加可直接复制粘贴的代码片段，来源包括：

• 项目代码库（注明实际文件和行号）
• 官方文档示例
• Stack Overflow 解决方案
• 个人实现经验

第 6 步：更新任务注册表

更新 docs/blueprint/manifest.json 中的任务注册表条目：

jq --arg now "$(date -u +%Y-%m-%dT%H:%M:%SZ)" \
  --argjson processed "${ITEMS_PROCESSED:-0}" \
  --argjson created "${ITEMS_CREATED:-0}" \
  '.task_registry["curate-docs"].last_completed_at = $now |
   .task_registry["curate-docs"].last_result = "success" |
   .task_registry["curate-docs"].stats.runs_total = ((.task_registry["curate-docs"].stats.runs_total // 0) + 1) |
   .task_registry["curate-docs"].stats.items_processed = $processed |
   .task_registry["curate-docs"].stats.items_created = $created' \
  docs/blueprint/manifest.json > tmp.json && mv tmp.json docs/blueprint/manifest.json

第 7 步：验证并保存

1. 确认条目少于 200 行
2. 确认所有代码示例准确无误
3. 确认注意事项包含解决方案
4. 保存文件
5. 报告完成情况，并提供规则路径，以便 PRP 引用

Agentic 优化

上下文	命令
确定规则目录	jq -r '.structure.generated_rules_path // ".claude/rules/"' docs/blueprint/manifest.json
列出现有规则	ls .claude/rules/ 2>/dev/null
检查库版本	grep "{library}" package.json pyproject.toml 2>/dev/null | head -1
搜索模式	使用 grep 在 src/ 中搜索项目模式
快速调研	对于常见问题，使用 WebSearch，而非获取文档

---

规则模板、章节指南和示例条目请参阅 REFERENCE.md。