Community研究＆データ分析github.com

brmdias/best-practice

ベストプラクティスドキュメント作成ワークフローを自動化 - ナレッジベース、ドキュメント、コード、コミュニティの調査、結果統合、ドキュメント生成、INDEX更新までを効率化します。

best-practice とは？

このスキルは、TAMナレッジベースにおけるベストプラクティスドキュメントの完全なワークフローを自動化します。手動で2〜4時間かかる作業を10〜15分に短縮します。開発者は`/best-practice <トピック名>`または`/bp <トピック名>`コマンドを使用して起動できます。スキルは11のステップを実行します：トピックの検証と重複チェック、ナレッジベース、公式ドキュメント、製品コード、GitHub Issues、Jiraチケットの調査（オプションでコミュニティ検索も）、結果の統合とユーザー確認、TEMPLATE.mdに従ったベストプラクティスドキュメントの生成、INDEX.mdの更新、完了レポートの表示です。このスキルはClaude Code、Cursor、Codex、CopilotなどのRunlayer対応AIエージェントプラットフォームで動作します。各ステップは詳細な資料調査と品質チェックを確実に行い、信頼性の高いドキュメントを生成します。

対応✓Claude Code~Codex CLI~Cursor
npx skills add https://github.com/brmdias/automation-tam-kb-skills/tree/HEAD/skills/best-practice

Installed? Explore more 研究＆データ分析 skills: affaan-m/uspto-database, affaan-m/scholar-evaluation, affaan-m/literature-review · View all 6 →

オリジナルを見る→すべてのスキルを見る

お気に入りのAIに質問する

このエージェントスキルを事前に読み込んだ状態で新しいチャットを開きます。

OpenAIChatGPTClaudeClaudeGeminiGeminiGrokGrokPerplexityPerplexityDeepSeekDeepSeek

ドキュメント

ベストプラクティスドキュメンテーションスキル

TAMナレッジベースでのベストプラクティスドキュメント作成の完全なワークフローを自動化し、手動での2〜4時間の作業を10〜15分に短縮します。

使用方法

/best-practice <トピック名>
/bp <トピック名>

例:

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

このスキルの機能

ベストプラクティスドキュメント作成の完全なワークフローを実行します:

  1. 検証と既存チェック - 重複を防ぎ、更新を処理
  2. ナレッジベースの調査 - 類似の調査、ベストプラクティス、顧客事例を検索
  3. ドキュメント検索 - 公式ガイダンスとバージョン情報を検索
  4. 製品コード検索 - 技術詳細とデフォルト値を確認（該当する場合）
  5. GitHub検索 - コミュニティのIssue、バグ、機能リクエストを検索
  6. Jira検索 - 内部開発チケットと修正バージョンを特定
  7. コミュニティ検索 - 必要に応じて外部ソースをWebFetch（オプション）
  8. 結果の統合 - ユーザー確認のための調査サマリーを提示
  9. ドキュメント生成 - TEMPLATE.mdの構造に従ってベストプラクティスを作成
  10. INDEX.mdの更新 - カテゴリ、アルファベット順テーブル、クイックリファレンスに追加
  11. 完了報告 - 次のステップを含む包括的なサマリー

指示

このスキルが呼び出されたら、以下の手順に従います:

ステップ 1: 引数の解析と検証

引数からトピック名を抽出:

  • 必須: トピック名（例: "webhook-timeout-patterns"）
  • まだケバブケースでない場合は変換
  • トピックが80文字を超える場合、「トピックが広すぎるようです。分割を検討してくださいか？」と警告

トピックが指定されていない場合:

  • エラー: "Usage: /best-practice "
  • 例を表示

ステップ 2: 既存のベストプラクティスの確認

類似する名前の既存のベストプラクティスを検索:

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

判断ロジック:

  • 完全一致: ユーザーに確認: 「ベストプラクティスが <file> に存在します。(1) 既存を更新、(2) 異なる焦点で新規作成、(3) キャンセル？」
  • 部分一致: リストを表示し、確認: 「類似のものが見つかりました: <files>。(1) いずれかを更新、(2) 新規作成、(3) キャンセル？」
  • 一致なし: 作成を続行

ユーザーが更新を選択した場合、後でWriteではなくEditを使用するためにファイル名をメモ

ステップ 3: ナレッジベースの検索

トピック名から検索キーワードを抽出（ハイフンを削除し、用語に分割）

ベストプラクティスを検索:

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

調査を検索:

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

顧客プロファイルを検索（関連する場合）:

Grep pattern="<keywords>" path="customers/" output_mode="files_with_matches"

顧客プロファイルが見つかった場合は、それらを読んでコンテキストを収集

収集してメモ:

  • 関連するベストプラクティス（「関連ベストプラクティス」セクション用）
  • 調査例（「実世界の例」セクション用）
  • 類似ドキュメントからの一般的なタグ（メタデータ用）
  • 該当する場合の顧客コンテキスト

ステップ 4: 公式ドキュメントの検索

Grep pattern="<keywords>" 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 Issueの検索（Runlayerコネクタ経由）

Runlayerコネクタを介してGitHubをクエリ — この環境ではgh CLIは利用できません。search_toolsを呼び出してGitHub Issue検索ツールを見つけ、execute_toolを使用してrundeck/rundeckとrundeckpro/rundeckproで <keywords> をオープンおよびクローズドのIssue全体で検索します。ghへのシェル呼び出しは行わないでください。

収集してメモ:

  • 既知のIssueやバグ
  • 機能リクエストとコミュニティフィードバック
  • 回避策とコミュニティソリューション
  • 引用のためのIssue番号

GitHubコネクタが利用できない場合は、その旨をメモして続行

ステップ 7: Jira RUNプロジェクトの検索（Runlayerコネクタ経由）

Runlayerコネクタを介してJiraをクエリします。search_toolsを呼び出してJira Issue検索ツールを見つけ、execute_toolを返された正確なtool_nameと引数で使用します。mcp__atlassian__* ツールを直接呼び出さないでください。以下と同等のパラメータを使用します。

jql: "project=RUN AND (summary ~ \"<keywords>\" OR description ~ \"<keywords>\") 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=<keywords>"
  prompt: "<topic>に関する議論を見つけてください。抽出項目: 報告された問題、提案された解決策、推奨されたパターン、一般的な問題"

収集してメモ:

  • コミュニティソリューションとパターン
  • 一般的な落とし穴と問題
  • 実装のバリエーション
  • 重要: 未確認の主張にはフラグを立て、公式ドキュメントと照合して確認

ステップ 9: 結果の統合とユーザー確認

すべての調査結果を分析:

  1. パターンを特定 ソース全体で
  2. 推奨事項を決定: 正当性とともに主要なアプローチ
  3. 代替案を特定: 他のアプローチと主要アプローチが推奨される理由
  4. 実装を抽出: コード例を含むステップバイステップ
  5. 利点とトレードオフを文書化
  6. メタデータを選択:
    • 製品エリア: 以下のカテゴリから決定:
      • 🎯 ジョブ設計とオーケストレーション
      • 🖥️ ノード管理とターゲティング
      • 🔐 セキュリティとアクセス制御
      • 📊 パフォーマンスとスケーリング
      • 🔗 統合とWebhook
      • 🏗️ アーキテクチャとデプロイメント
      • 📝 ドキュメントとメンテナンス
    • 対象バージョン: Jira/ドキュメントから（「Rundeck 5.6.0+」のように具体的、または控えめに「全バージョン」）
    • タグ: 類似BPからの既存タクソノミーを使用（ステップ3で見つかったタグをスキャン）、最大3〜8タグ

調査サマリーをユーザーに提示:

# 調査サマリー: <トピック名>

## 見つかったソース
- ナレッジベース: X件の調査、Y件のベストプラクティス
- ドキュメント: Nページ
- GitHub: P件のIssue
- Jira: Q件のチケット
- コミュニティ: [検索した場合]

## 推奨アプローチ
[調査に基づく主要推奨事項の1〜2段落のサマリー]

## 特定された主要パターン
- [調査からのパターン1]
- [調査からのパターン2]
- [調査からのパターン3]

## 提案メタデータ
- **製品エリア:** [決定されたカテゴリ]
- **対象バージョン:** [調査からのバージョン]
- **タグ:** #tag1 #tag2 #tag3 [類似BPから]

## 品質チェック
- ✓ [X] 件のソースを発見（最低4推奨）
- ✓ [Y] 個のコード/設定例が利用可能
- ✓ [Z] 件の実世界の例を発見

ドキュメントを生成しますか？

ユーザーの確認を待ちます。 ユーザーは以下を行うことができます:

  • 確認して続行
  • メタデータやアプローチの変更をリクエスト
  • 追加調査を依頼
  • ワークフローをキャンセル

ユーザーの確認なしに生成に進まないでください。

ステップ 10: ベストプラクティスドキュメントの生成

ユーザーが確認したら、ドキュメントを生成:

  1. テンプレートを参照用に読み取り:
Read file_path="best-practices/TEMPLATE.md"
  1. すべてのセクションを調査内容で埋める:

ヘッダー（1〜6行目）:

# [タイトルケースのトピック名]

**最終更新日:** 2026-04-20
**製品エリア:** [ステップ9から]
**対象バージョン:** [ステップ9から]
**タグ:** #tag1 #tag2 #tag3 [ステップ9から]

---

ユースケース / シナリオ:

  • 誰がいつこれが必要になるか（調査とドキュメントから）
  • どのような問題を解決するか？
  • どのシナリオでこれが関連するか？

推奨事項:

  • 明確で実行可能なガイダンス（「何をすべきか」）
  • 統合からの主要アプローチ
  • 複数のオプションがある場合はテーブルを含めることも可能

実装:

  • ステップバイステップの方法
  • 該当する場合は複数のパターン（パターン1、パターン2など）
  • ドキュメントとコード調査からのコード例
# 実際のYAML/設定例を含める
# 調査で見つかったコードスニペットを使用

これが機能する理由:

  • コードとドキュメント調査からの技術的説明
  • 基礎となる原則やメカニズム
  • このアプローチが効果的な理由

利点:

  • 調査結果からの番号付きリスト
  • 具体的な利点（パフォーマンス、セキュリティ、保守性など）
  • 可能な場合は定量化

トレードオフ / 注意点:

  • 調査で特定された制限
  • パフォーマンスに関する考慮事項
  • これが適用されない可能性がある状況
  • ⚠️ 矛盾する情報が見つかった場合はフラグを立てる

検討された代替案:

  • 調査で見つかった他のアプローチ
  • 推奨アプローチが好まれる理由
  • 代替案の方が適している場合

実世界の例:

  • 調査へのリンク: [顧客/ケース](../investigations/YYYY-MM-DD-description.md)
  • ない場合: 「まだ調査は文書化されていません。このベストプラクティスは[公式ドキュメント/コード分析/コミュニティパターン]に基づいています。」

関連ベストプラクティス:

  • KB検索からの関連ドキュメントへのリンク
  • 形式: [タイトル](./filename.md) - 簡単な説明

公式ドキュメント:

  • ドキュメントリポジトリファイルへのリンク
  • 番号によるGitHub Issue
  • キーによるJiraチケット
  • 公式ウェブサイトへのリンク
  1. 書き込み前の品質チェック:
  • ✓ 4つのメタデータフィールドすべてが入力されている
  • ✓ 既存タクソノミーからの3〜8タグ
  • ✓ テンプレートのすべてのセクションが存在
  • ✓ 少なくとも1つのコード/設定例
  • ✓ 少なくとも2つのソースが引用されている
  • ✓ 適切なマークダウン形式
  1. ドキュメントを書き込む:

新規作成の場合:

Write file_path="best-practices/<kebab-topic-name>.md" content="<generated-content>"

既存の更新の場合（ステップ2から）:

Edit file_path="best-practices/<existing-filename>.md"

構造を保持しながら関連セクションを更新

ステップ 11: INDEX.mdの更新

  1. 現在のINDEXを読み取り:
Read file_path="best-practices/INDEX.md"

  1. 主要カテゴリを決定 以下のオプションから（絵文字を正確に使用）:

    • 🎯 ジョブ設計とオーケストレーション
    • 🖥️ ノード管理とターゲティング
    • 🔐 セキュリティとアクセス制御
    • 📊 パフォーマンスとスケーリング
    • 🔗 統合とWebhook
    • 🏗️ アーキテクチャとデプロイメント
    • 📝 ドキュメントとメンテナンス

  2. Editツールを使用して3つのセクションを更新:

a) カテゴリセクション: 適切なカテゴリを見つけ（例: "### 🎯 ジョブ設計とオーケストレーション"）、エントリを追加:

- [タイトル](./filename.md) - 一行説明 #tag1 #tag2 #tag3

カテゴリ内でアルファベット順に挿入

b) 全ベストプラクティス（アルファベット順）テーブル: 正しいアルファベット順の位置を見つけて挿入:

| [タイトル](./filename.md) | カテゴリ [& サブカテゴリ（該当する場合）] | 2026-04-20 | [関連ケースまたは「N/A」] |

c) ユースケース別クイックリファレンスセクション: 一般的なユースケースを反映した「〜する必要がある」エントリを2〜4つ追加:

- **...特定の問題/タスク** → [タイトル](./filename.md)

アルファベット順に並べて保持

  1. 「最終更新日」を更新: 上部の日付を変更:
**最終更新日:** 2026-04-20
  1. Editツールで更新を実行: 各変更にEditを使用（互いに近い場合は結合）:
Edit file_path="best-practices/INDEX.md" old_string="<existing-text>" new_string="<updated-text>"

ステップ 12: 完了報告

包括的な完了サマリーを提供:

✅ ベストプラクティスが正常に作成されました！

## ドキュメント詳細
**タイトル:** [フルタイトル]
**ファイル:** best-practices/<filename>.md
**カテゴリ:** [主要カテゴリ]
**タグ:** #tag1 #tag2 #tag3

## 調査サマリー
- ナレッジベース: X件の調査、Y件のベストプラクティス
- ドキュメント: Nページ
- GitHub: P件のIssue
- Jira: Q件のチケット
- コミュニティ: [検索した場合]
- **合計ソース:** [件数]

## 完了したドキュメントセクション
✓ ユースケース / シナリオ
✓ [件数]パターンの推奨事項
✓ [件数]のコード例を含む実装
✓ これが機能する理由
✓ [件数]の利点をリスト
✓ [件数]のトレードオフを文書化
✓ [件数]の検討された代替案
✓ 実世界の例: [リンクまたは「ドキュメント保留中」]
✓ [件数]の関連ベストプラクティスにリンク
✓ [件数]の公式ドキュメント参照

## INDEX.mdが更新されました
✓ [カテゴリ名]に追加
✓ アルファベット順テーブルに行[N]として追加
✓ [件数]のクイックリファレンスエントリを追加
✓ 「最終更新日」を更新

## 次のステップ
1. ドキュメントを確認: best-practices/<filename>.md
2. 該当する場合はサンドボックスで実装をテスト
3. チームと共有: `/share-kb "<タイトル>" best-practices/<filename>.md`
4. 該当する場合は関連顧客プロファイルからリンク

これが新規作成ではなく更新の場合:

✅ ベストプラクティスが正常に更新されました！

## 更新されたドキュメント
**タイトル:** [フルタイトル]
**ファイル:** best-practices/<filename>.md
[残りのサマリーは更新シナリオに合わせて調整]

品質ガイドライン

調査品質

  • 最低4つのソースカテゴリ（KB、ドキュメント、コード、外部トラッカー）を検索
  • コード/ドキュメント参照には特定のファイルパスを記載
  • GitHub Issueを番号でリンク（#1234）
  • Jiraチケットをキーでリンク（RUN-1234）
  • コミュニティの主張を公式ソースと照合して確認
  • 未確認または矛盾する情報にはフラグを立てる

ドキュメント品質

  • 明確さ: 各セクションはすぐに実践可能または情報豊富であること
  • 完全性: テンプレートのすべてのセクションが埋められていること（TODOなし）
  • エビデンスベース: すべての推奨事項はソースに裏付けられていること
  • 実用的: 単なる散文ではなく、実際のコード/設定例を含めること
  • 正直さ: トレードオフと注意点を文書化すること

Individual skills in this repo

This repo contains 1 individual skill — each has its own dedicated page.

brmdias/investigate

Run full investigation workflow for customer issue - searches knowledge base, documentation, code, and external trackers, then recommends test environment

関連スキル

affaan-m/uspto-database

USPTO patent and trademark data workflow for official record lookup, PatentSearch queries, TSDR checks, assignment data, and reproducible IP research logs.

community

affaan-m/scholar-evaluation

Structured scholarly-work evaluation for papers, proposals, literature reviews, methods sections, evidence quality, citation support, and research-writing feedback.

community

affaan-m/literature-review

Systematic literature-review workflow for academic, biomedical, technical, and scientific topics, including search planning, source screening, synthesis, citation checks, and evidence logging.

community

affaan-m/everything-claude-code

The agent harness performance optimization system. Skills, instincts, memory, security, and research-first development for Claude Code, Codex, Opencode, Cursor and beyond.

community

forrestchang/andrej-karpathy-skills

Agent skill repository discovered by 10x-chat research.

community

langgenius/backend-code-review

Review backend code for quality, security, maintainability, and best practices based on established checklist rules. Use when the user requests a review, analysis, or improvement of backend files (e.g., `.py`) under the `api/` directory. Do NOT use for frontend files (e.g., `.tsx`, `.ts`, `.js`). Supports pending-change review, code snippets review, and file-focused review.

community
← More 研究＆データ分析 skills