最佳实践文档技能 (Best Practice Documentation Skill)

自动化 TAM 知识库中最佳实践文档的完整编写流程，将 2-4 小时的手动工作减少到 10-15 分钟。

用法 (Usage)

/best-practice <主题名称>
/bp <主题名称>

示例：

/bp webhook-timeout-patterns
/best-practice runner-disk-management
/bp ansible-integration-patterns

本技能的功能 (What This Skill Does)

执行完整的最佳实践文档工作流程：

验证并检查现有文档 - 确保无重复，处理更新
研究知识库 - 查找类似的调查、最佳实践、客户示例
搜索文档 - 查找官方指南和版本信息
搜索产品代码 - 验证技术细节和默认值（相关时）
搜索 GitHub - 查找社区问题、错误和功能请求
搜索 Jira - 定位内部开发工单和修复版本
社区搜索 - 如有需要，WebFetch 外部来源（可选）
综合发现 - 向用户呈现研究摘要以确认
生成文档 - 遵循 TEMPLATE.md 结构创建最佳实践
更新 INDEX.md - 添加到分类、字母顺序表和快速参考中
报告完成 - 包含后续步骤的全面摘要

指令 (Instructions)

当调用此技能时，请遵循以下步骤：

步骤 1：解析参数并验证

从参数中提取主题名称：

必填项：主题名称（例如 "webhook-timeout-patterns"）
如果不是 kebab-case 格式，则转换为该格式
如果主题长度超过 80 个字符，则警告："主题似乎过于宽泛，请考虑拆分？"

如果未提供主题：

错误："用法: /best-practice <主题名称>"
显示示例

步骤 2：检查现有最佳实践

搜索具有相似名称的现有最佳实践：

Glob pattern="*${keywords}*" path="best-practices/"

决策逻辑：

精确匹配： 询问用户："最佳实践已存在于 <file>。(1) 更新现有文档，(2) 创建具有不同侧重点的新文档，(3) 取消？"
部分匹配： 列出它们，询问："找到相似文档：<files>。(1) 更新其中一个，(2) 创建新文档，(3) 取消？"
无匹配： 继续创建流程

如果用户选择更新，请记录文件名，以便后续使用 Edit 而不是 Write。

步骤 3：搜索知识库

从主题名称中提取搜索关键词（去除连字符，拆分为术语）。

搜索最佳实践：

Grep pattern="<关键词>" path="best-practices/" output_mode="content" -C 3 head_limit=50

搜索调查 (Investigations)：

Grep pattern="<关键词>" path="investigations/" output_mode="content" -C 3 head_limit=50

搜索客户资料（如果相关）：

Grep pattern="<关键词>" path="customers/" output_mode="files_with_matches"

如果找到了客户资料，请读取它们以收集上下文。

收集并记录：

相关的最佳实践（用于“相关最佳实践”部分）
调查示例（用于“真实世界示例”部分）
来自相似文档的常用标签（用于元数据）
适用的客户上下文

步骤 4：搜索官方文档

Grep pattern="<关键词>" path="repositories/docs/" output_mode="content" -C 2 head_limit=30

收集并记录：

官方指南和建议
特定版本的信息
配置参考和选项
已知的限制或注意事项

步骤 5：搜索产品代码（有条件）

何时搜索：

主题涉及特定的功能行为
需要默认配置值
了解性能特征
验证技术约束

Grep pattern="<component|class>" path="repositories/rundeckpro/" output_mode="content" head_limit=30

收集并记录：

默认配置值
实现细节和行为
技术约束或限制
特定版本的逻辑

步骤 6：搜索 GitHub Issues（通过 Runlayer 连接器）

通过 Runlayer 连接器查询 GitHub — 此环境中不可使用 gh CLI。调用 search_tools 定位 GitHub issue 搜索工具，然后调用 execute_tool 搜索 rundeck/rundeck 和 rundeckpro/rundeckpro 中与 <关键词> 相关的已打开和已关闭 issues。不要通过 shell 调用 gh。

收集并记录：

已知问题或错误
功能请求和社区反馈
临时解决方案和社区解决方案
用于引用的 Issue 编号

如果 GitHub 连接器不可用，请记录并继续。

步骤 7：搜索 Jira RUN 项目（通过 Runlayer 连接器）

通过 Runlayer 连接器查询 Jira。调用 search_tools 定位 Jira issue 搜索工具，然后使用返回的确切 tool_name 和参数调用 execute_tool。不要直接调用 mcp__atlassian__* 工具。使用等效于以下内容的参数：

jql: "project=RUN AND (summary ~ \"<关键词>\" OR description ~ \"<关键词>\") ORDER BY updated DESC"
maxResults: 15

收集并记录：

内部开发工单
修复版本和发布信息
开发状态和上下文
用于引用的 Jira 键（RUN-XXXX）

错误处理： 如果 Jira 连接器不可用，请记录“Jira 搜索不可用”并继续。

步骤 8：社区搜索（可选/按需）

触发条件：

在步骤 3-7 中找到的相关来源少于 3 个
新颖或新兴的模式尚未完善文档
用户指示需要更广泛的研究

WebFetch with parameters:
  url: "https://groups.google.com/g/rundeck-discuss/search?q=<关键词>"
  prompt: "查找关于 <主题> 的讨论。提取：报告的问题、建议的解决方案、推荐的模式、常见问题"

收集并记录：

社区解决方案和模式
常见陷阱和问题
实现变体
重要： 标记未经证实的声明，并与官方文档进行验证

步骤 9：综合发现并获取用户确认

分析所有研究发现：

识别跨来源的模式
确定建议： 主要方法及理由
识别替代方案： 其他方法以及为什么首选主要方法
提取实现： 带代码示例的逐步操作
记录收益和权衡
选择元数据：
- 产品领域： 从以下类别中确定：
  - 作业设计与编排
  - 节点管理与目标设定
  - 安全性与访问控制
  - 性能与扩展
  - 集成与 Webhooks
  - 架构与部署
  - 文档与维护
- 适用版本： 来自 Jira/文档（具体说明，如“Rundeck 5.6.0+”或保守的“所有版本”）
- 标签： 使用来自类似最佳实践的现有分类（扫描步骤 3 中发现的标签），最多 3-8 个标签

向用户展示研究摘要：

# 研究摘要：<主题名称>

## 来源发现
- 知识库：X 个调查，Y 个最佳实践
- 文档：N 页
- GitHub：P 个问题
- Jira：Q 个工单
- 社区：[如已搜索]

## 推荐方法
[基于研究的 1-2 段主要建议摘要]

## 识别的关键模式
- [来自研究的模式 1]
- [来自研究的模式 2]
- [来自研究的模式 3]

## 建议的元数据
- **产品领域：** [确定的类别]
- **适用版本：** [来自研究的版本]
- **标签：** #标签1 #标签2 #标签3 [来自类似最佳实践]

## 质量检查
- ✓ [X] 个来源已找到（建议至少 4 个）
- ✓ [Y] 个代码/配置示例可用
- ✓ [Z] 个真实世界示例已找到

准备好生成文档了吗？

等待用户确认。 用户可以：

确认并继续
请求更改元数据或方法
要求进行额外研究
取消工作流程

未经用户确认，请勿进入生成阶段。

步骤 10：生成最佳实践文档

一旦用户确认，生成文档：

读取模板以供参考：

Read file_path="best-practices/TEMPLATE.md"

使用研究内容填充所有部分：

标题（第 1-6 行）：

# [标题大小写主题名称]

**最后更新日期：** 2026-04-20
**产品领域：** [来自步骤 9]
**适用版本：** [来自步骤 9]
**标签：** #标签1 #标签2 #标签3 [来自步骤 9]

---

用例/场景：

描述何时需要此实践（来自调查和文档）
它解决了什么问题？
这个实践适用于哪些场景？

建议：

清晰、可操作的指导（“该怎么做”）
综合得出的主要方法
如果有多个选项，可以包含表格

实现：

分步操作指南
如果适用，提供多种模式（模式 1、模式 2 等）
来自文档和代码研究的代码示例

# 包含实际的 YAML/配置示例
# 使用研究中发现的代码片段

为什么这有效：

来自代码和文档研究的技术解释
底层原理或机制
为什么这种方法有效

收益：

来自研究结果的编号列表
具体优势（性能、安全性、可维护性等）
尽可能量化

权衡/注意事项：

研究中发现的限制
性能考虑
此实践可能不适用的情况
⚠️ 如果发现冲突信息，请标记

已考虑的替代方案：

研究中发现的其他方法
为什么推荐的方法更优
替代方案何时可能更好

真实世界示例：

指向调查的链接：[客户/案例](../investigations/YYYY-MM-DD-description.md)
如果没有："尚未有记录的调查。此最佳实践基于[官方文档/代码分析/社区模式]。"

相关最佳实践：

来自知识库搜索的相关文档链接
格式：[标题](./filename.md) - 简要描述

官方文档：

指向文档仓库文件的链接
按编号引用的 GitHub 问题
按键引用的 Jira 工单
官方网站链接

写入前的质量检查：

✓ 所有 4 个元数据字段已填充
✓ 来自现有分类的 3-8 个标签
✓ 所有模板部分均已存在
✓ 至少 1 个代码/配置示例
✓ 至少引用 2 个来源
✓ 正确的 Markdown 格式

写入文档：

如果是新建：

Write file_path="best-practices/<kebab-主题名称>.md" content="<生成内容>"

如果是更新现有文档（来自步骤 2）：

Edit file_path="best-practices/<现有文件名>.md"

在保留结构的同时更新相关部分。

步骤 11：更新 INDEX.md

读取当前 INDEX：

Read file_path="best-practices/INDEX.md"

从以下选项中确定主要类别（请完全按照所示使用表情符号）：
- 🎯 作业设计与编排
- 🖥️ 节点管理与目标设定
- 🔐 安全性与访问控制
- 📊 性能与扩展
- 🔗 集成与 Webhooks
- 🏗️ 架构与部署
- 📝 文档与维护
使用 Edit 工具更新三个部分：

a) 类别部分： 找到相应的类别（例如 "### 🎯 作业设计与编排"）并添加条目：

- [标题](./filename.md) - 单行描述 #标签1 #标签2 #标签3

在类别内按字母顺序插入。

b) 所有最佳实践（按字母顺序）表格： 找到正确的字母位置并插入：

| [标题](./filename.md) | 类别 [及次要类别（如果适用）] | 2026-04-20 | [相关案例或“N/A”] |

c) 按用例快速参考部分： 添加 2-4 个反映常见用例的“我需要...”条目：

- **...特定问题/任务** → [标题](./filename.md)

保持字母顺序排序。

更新“最后更新日期”： 更改顶部的日期：

**最后更新日期：** 2026-04-20

使用 Edit 工具执行更新： 使用 Edit 工具进行每项更改（如果它们彼此靠近，可以合并）：

Edit file_path="best-practices/INDEX.md" old_string="<现有文本>" new_string="<更新后的文本>"

步骤 12：报告完成

提供全面的完成摘要：

✅ 最佳实践已成功创建！

## 文档详情
**标题：** [完整标题]
**文件：** best-practices/<文件名>.md
**类别：** [主要类别]
**标签：** #标签1 #标签2 #标签3

## 研究摘要
- 知识库：X 个调查，Y 个最佳实践
- 文档：N 页
- GitHub：P 个问题
- Jira：Q 个工单
- 社区：[如已搜索]
- **总来源数：** [计数]

## 已完成的文档部分
✓ 用例/场景
✓ 包含 [计数] 种模式的建议
✓ 包含 [计数] 个代码示例的实现
✓ 为什么这有效
✓ 列出 [计数] 项收益
✓ 记录 [计数] 项权衡
✓ 考虑了 [计数] 个替代方案
✓ 真实世界示例：[链接或“待定文档”]
✓ 链接了 [计数] 个相关最佳实践
✓ 引用了 [计数] 个官方文档

## INDEX.md 已更新
✓ 已添加到 [类别名称]
✓ 已添加到字母顺序表格（第 [N] 行）
✓ 已添加 [计数] 个快速参考条目
✓ 已更新“最后更新日期”

## 后续步骤
1. 在 best-practices/<文件名>.md 审阅文档
2. 如果适用，在沙箱中测试实现
3. 与团队分享：`/share-kb “<标题>” best-practices/<文件名>.md`
4. 如果适用，链接到相关的客户资料

如果是更新而不是创建：

✅ 最佳实践已成功更新！

## 更新后的文档
**标题：** [完整标题]
**文件：** best-practices/<文件名>.md
[为更新场景调整其余摘要]

质量指南 (Quality Guidelines)

研究质量

搜索至少 4 个来源类别（知识库、文档、代码、外部跟踪器）
为代码/文档引用指定具体的文件路径
按编号链接到 GitHub 问题 (#1234)
按键链接到 Jira 工单 (RUN-1234)
对照官方来源验证社区声明
标记未经验证或冲突的信息

文档质量

清晰度： 每个部分都应立即可操作或提供信息
完整性： 所有模板部分均已填充（无 TODO）
基于证据： 所有建议均有来源支持
实用性： 包含真实的代码/配置示例，而不仅仅是文字描述
诚实性： 文档中明确记录权衡和注意事项

brmdias/best-practice

best-practice 是什么？

在你喜欢的 AI 中提问

文档

最佳实践文档技能 (Best Practice Documentation Skill)

用法 (Usage)

本技能的功能 (What This Skill Does)

指令 (Instructions)

步骤 1：解析参数并验证

步骤 2：检查现有最佳实践

步骤 3：搜索知识库

步骤 4：搜索官方文档

步骤 5：搜索产品代码（有条件）

步骤 6：搜索 GitHub Issues（通过 Runlayer 连接器）

步骤 7：搜索 Jira RUN 项目（通过 Runlayer 连接器）

步骤 8：社区搜索（可选/按需）

步骤 9：综合发现并获取用户确认

步骤 10：生成最佳实践文档

步骤 11：更新 INDEX.md

步骤 12：报告完成

质量指南 (Quality Guidelines)

研究质量

文档质量

Individual skills in this repo

brmdias/investigate

相关技能

affaan-m/uspto-database

affaan-m/scholar-evaluation

affaan-m/literature-review

affaan-m/everything-claude-code

forrestchang/andrej-karpathy-skills

langgenius/backend-code-review