knowledge-ops

knowledge-ops

Head-of-Ops／Knowledge-Manager／TPM-Internal のペルソナ向けに、社内 SOP とランブックの作成、5W2H の網羅性検証、ナレッジベースの衛生状態レポートを行います。

目的

運用組織が3年目を迎えると、ドキュメントがあちこちに散在するようになります。Notion ページが600件、Confluence のランブックが200件、Obsidian の保管庫が3つ、Drive/SOPs/ フォルダー、そして正規のドキュメントを誰も見つけられないために存在する Slack #ops-questions チャンネル。よくある問題は次のとおりです。

1. オーナーがいない — SOP の40％が、担当者ではなく「チーム」と記載しています。ドキュメントが古くなっても、責任を負う人がいません。
2. 最終レビュー日がない — 数年前のベンダー契約終了 SOP に、1年以上前に廃止された調達ツールがまだ記載されています。
3. 成功の判断基準が曖昧 — ランブックのステップ4には「サービスが稼働していることを確認する」とあります。新しい担当者には、それが何を意味するのか判断できません。
4. ロールバック手順がない — インシデント連絡の一斉通知ランブックには、アラートの送信方法は記載されています。しかし、アラートが誤りだった場合に撤回する方法は記載されていません。
5. 孤立したページ — ナレッジベースの半分には、リンク元がありません。ナビゲーションからは見つからず、誰かが URL を知っている場合にしか存在に気づけません。
6. 用語集の不整合 — 3つのドキュメントでは「CSM」が Customer Success Manager を意味し、5つのドキュメントでは Customer Solutions Manager を意味しています。新入社員は半年間、誤った意味を推測します。
7. 順調な場合だけを扱う SOP — すべてがうまくいく場合の手順しか書かれていません。うまくいかない30％のケースについては触れていません。

このスキルは、運用担当者が実際に知りたい「最初に修正すべきドキュメント20件はどれで、それぞれの具体的な問題は何か？」に、勘ではなく決定論的なロジックで答えます。

使用する場面

• 部門横断の社内プロセス（調達の受付、ベンダー契約の終了、インシデント連絡の一斉通知、従業員のオンボーディング、経費精算、顧客エスカレーションのプレイブック、セキュリティインシデントの連絡、システムアクセス権の付与）向けに、新しい SOP を作成する場合。
• 既存の社内ランブックを運用に組み込む前に検証する場合（各ステップに、担当者、所要時間の目安、観測可能な成功の判断基準、観測可能な失敗の判断基準、ロールバック手順、エスカレーション先が必要です）。
• 複数のドキュメントを含むナレッジベースのエクスポート（Notion の zip、Confluence のスペースエクスポート、Obsidian の保管庫、Drive/SOPs/ ディレクトリ）を取り込み、問題点（孤立したページ、古いページ（12か月以上編集されていない）、用語集の不整合、オーナーがいないページ、相互リンクのマップ）を明らかにする場合。
• 新しい運用担当者の入社時に、最初の週に読むべき SOP と運用ハンドブックのページを生成する場合。
• Wiki のクリーンアップスプリント — 組織が四半期ごとの整備作業として、アーカイブ、書き直し、統合するドキュメントを30件選ぶ場合。

ワークフロー

4段階の決定論的なフローです（抽象的なプロセスではなく、運用チームの実際のワークフローに合わせています）。

1. ナレッジベースを取り込みます。 既存の Wiki エクスポートに対して kb_ingester.py --input <vault-dir> を実行します。出力は、孤立ページ、古いページ、用語集の不整合、オーナーが未設定のページ、相互リンクのマップ、優先順位付きの整理リストを含む Markdown のヘルスレポートです。レポートでは、最初に修正する上位 20 件のドキュメントが順位付けされます。通常は、アクセス数の多い古いドキュメントと、コンプライアンス上重要なオーナー未設定のドキュメントが混在します。このリストを整理スプリントに持ち込みます。
2. 既存のランブックを検証します。 整理リストにある各ランブック（またはローテーションに組み込む前の新しいランブック）に対して、runbook_validator.py --input <runbook.md> を実行します。バリデーターは、6 項目（オーナーの明記、想定所要時間、観測可能な成功の兆候、観測可能な失敗の兆候、ロールバック手順、エスカレーション先）に照らして各ステップを評価し、ステップごとの信号色、全体の有効性スコア（0～100）、必須修正項目のリストを出力します。スコアが 60 未満のランブックは、インシデント時に安全に使用できません。
3. 不足している SOP を生成します。 一から作成する必要がある SOP（または既存のものを修復できず書き直す SOP）に対して、sop_generator.py --input <metadata.json> --profile <ops|support|finance|hr|it|regulated> を実行します。出力は 5W2H 形式の SOP のひな形です。Who（RACI）、What（プロセスの手順）、When（トリガーと頻度）、Where（システムとツール）、Why（目的と規制上の根拠）、How（ステップごとの手順）、How-much（実行ごとのコストと時間）を含みます。regulated プロファイルでは、バージョン管理、承認、監査証跡のセクションが追加されます（ISO 9001／FDA 21 CFR Part 211／SOC 2／HIPAA）。
4. 相互リンクを追加し、最後まで確認します。 整理スプリントの後に kb_ingester.py を再実行して、孤立ページ数が減り、用語集の不整合が解消されたことを確認します。重要な指標はページ数ではなく、「見つけられないドキュメント」（孤立ページ）と**「安全でないランブック」**（有効性スコアが 60 未満）です。

スクリプト

scripts/sop_generator.py — SOP（プロセスオーナー、トリガーとなるイベント、対象者の役割、頻度、規制要件、入力、出力、手順の概要）を記述した JSON メタデータファイルを読み込み、5W2H 構成の完全な SOP を Markdown（または正規化された JSON）で出力します。--profile フラグで出力を調整できます。ops（一般的な社内業務）、support（カスタマーサポートのランブック形式）、finance（統制と照合を重視）、hr（機密データのフラグ付け）、it（システムとアクセスを重視）、regulated（バージョン管理、承認マトリクス、監査証跡を追加）を指定できます。規制要件（SOC2、HIPAA、ISO13485、GDPR、SOX）を指定すると、適切なコンプライアンスに関する前文が追加されます。--sample を指定すると、ベンダーのオフボーディングに関する SOP の完全な例を出力します。標準ライブラリのみを使用します。

scripts/runbook_validator.py — ランブック（Markdown ファイルまたは JSON）を読み込み、各手順を次の6つの必須属性に照らして検証します。（1）明記された担当者（「チーム」や「運用担当」ではないこと）、（2）想定所要時間（具体的な数値と単位）、（3）観測可能な成功の兆候（例：「/healthz からの HTTP 200」。「サービスが稼働している」ではないこと）、（4）観測可能な失敗の兆候、（5）ロールバック方法（または「この手順はロールバックできないため、X にエスカレーションする」と明記）、（6）エスカレーション先（氏名が明記された担当者、または当番ローテーション）。出力は手順ごとの信号色（GREEN/AMBER/RED）、0～100 の総合有効性スコア、そして必ず修正すべき問題の一覧です。判定基準：80 以上 = SAFE-TO-USE、60～79 = USE-WITH-CAUTION、60 未満 = NOT-SAFE。--sample を指定すると、失敗の検出を実演するために、意図的に問題を含めたインシデント連絡用ランブックを出力します。標準ライブラリのみを使用します。

scripts/kb_ingester.py — Markdown ファイルのディレクトリ（Notion のエクスポート、Confluence スペースのエクスポート、Obsidian ボルト、Drive/SOPs/ ディレクトリ）を走査します。次の項目を抽出します。（a）相互リンクマップ（Markdown の [link](path) 構文を使って、どのページがどのページを参照しているか）、（b）用語集の候補（3つ以上の文書で繰り返し使われているものの、正式な定義ページが1つもない、頻出の固有名詞と頭字語）、（c）孤立ページ（ボルト内のどこからもリンクされていないページ）、（d）用語集の不整合（文書間で同じ用語の定義や使い方に一貫性がない状態。例：「CSM」の展開形が2か所で異なる）、（e）古いページ（最終編集から12か月超。ファイルシステムの mtime または YAML の last_reviewed フロントマターを使って検出）、（f）オーナー不明のページ（フロントマターに owner: フィールドがないページ）。ナレッジベースの健全性レポートを Markdown で出力し、古さ × 被リンク数 の順位に基づく、優先度順の上位20件の整理リストを含めます（アクセスの多い古い文書を上位にします）。--sample を指定すると、tmpdir に8ページからなる小規模な合成ボルトを作成し、完全なパイプラインを実行します。標準ライブラリのみを使用します。

簡単な例

# Builds a synthetic 8-page vault and emits a KB health report (orphans, stale pages, glossary drift, top-20 cleanup list)
cd business-operations/skills/knowledge-ops && python3 scripts/kb_ingester.py --sample

参考資料

• references/5w2h_sop_canon.md — Kaoru Ishikawa の5W2Hメソッド、Toyota の標準作業の規律、Atul Gawande のチェックリスト・マニフェスト、Atlassian Confluence の SOP ガイダンス、ISO 9001 の SOP 要件、ITIL v4 のサービス運用、FDA 21 CFR Part 211。SOP 作成の基本原則を扱う、引用付きの8つの情報源です。
• references/runbook_canon.md — Google SRE Workbook（ランブックの章）、Atlassian のインシデント管理ランブック、PagerDuty のインシデント対応分類、AWS Well-Architected の運用上の優秀性の柱、可観測性とランブックの統合に関する Charity Majors の知見、本番環境対応マイクロサービスに関する Susan Fowler の知見、ITIL v4 の運用。ランブック設計の基本原則を扱う、引用付きの7つの情報源です。
• references/kb_hygiene_anti_patterns.md — Notion／Confluence ウィキに関する業界調査、Mozilla SUMO のナレッジベースから得られた教訓、Stack Overflow のコミュニティ管理に関する調査、Atlassian Team Playbook、MIT TIK の組織内ウィキに関する研究、用語集の不整合に関する Cynthia Lee の知見、「ドキュメントの劣化」に関する Adam Wiggins の知見に基づく、8つのアンチパターンです。

前提条件

1. KB は Markdown 形式であること（または Markdown 形式にエクスポートできること）。Notion、Confluence、Obsidian、Google Docs はいずれも対応しています。HTML のみ、または PDF のみの KB は、まず変換が必要です。対象範囲外です。
2. ユーザーには、書き直しやアーカイブを依頼する権限があること。誰も対応しない整理リストを作成しても無駄です。インジェスターを実行する前に、調査結果を担当者として明示された人に共有してください。
3. 担当者のメタデータは、YAML フロントマター（owner: [email protected]）またはページ冒頭の「Owner:」行に記載されていること。最後にページを編集した人を担当者とみなすような暗黙知に基づく所有者情報は、記載がないものとして扱います。
4. 「古い」の既定値は 12 か月です。kb_ingester.py の --stale-days で変更できます。一部のコンプライアンス体制（FDA、ISO 13485）では、より短いレビュー周期が必要です。その場合は --profile regulated と --stale-days 365 を使用してください。
5. ユーザーは個人用 PKM を求めていません。個人向けの Karpathy スタイルのセカンドブレイン作成は engineering/llm-wiki の対象です。

アンチパターン

• 担当者を決めずに SOP を大量生成する。 担当者のいないドキュメントの半減期は 6 か月です。名前が明示された担当者をそれぞれ割り当てない限り、SOP を 30 件まとめて生成する依頼は断ってください。
• runbook_validator.py をチェックボックスとして使う。 バリデーターが検出するのは構成の不足です。内容の誤りは検出しません。ランブックのスコアが 100 でも、オペレーターに誤った手順を指示している場合があります。
• 孤立ページを最初から不要なものとして扱う。 孤立ページの中には、検索でのみ見つかる参照ページもあります。すべての孤立ページをアーカイブすべきではありません。整理リストは優先順位付きキューであり、削除リストではありません。
• ナレッジオペレーションと process-mapper を混同する。 Process-mapper は、段階間での作業の流れ（BPMN、サイクルタイム、ボトルネック）を文書化します。ナレッジオペレーションは、オペレーターが作業を実行するために利用する成果物（SOP、ランブック、用語集）を文書化します。同じプロセスに両方が適用されることがあります。
• 用語集の不整合を放置する。 3 年間で「CSM」の定義が 2 つになると、5 年間では 7 つになります。kb_ingester.py の出力に用語集の不整合が現れたら、すぐに修正してください。
• 規制対象の業務で規制プロファイルを使わない。 プロセスに PHI、SOX 関連の財務統制、または ISO 13485 の医療機器 QMS が関係する場合は、--profile regulated を使用してください。規制対象の SOP にバージョン管理がないと、監査指摘につながります。
• 記憶を頼りに 5W2H の項目を手書きする。 5W2H のひな型は、オペレーターが「How-much」を忘れないためにあります。ジェネレーターを使い、出力を編集してください。

次とは異なる

• engineering/llm-wiki — 1 人の人間が情報源を取り込み、相互リンクされた自身の保管庫を作る Karpathy スタイルの個人向け PKM セカンドブレインです。ナレッジオペレーションは組織向けで、複数の作成者と読者、ドキュメントごとに明示された担当者、正式なレビュー周期、コンプライアンス要件を伴います。
• engineering-team/runbook-generator — 本番システムのデバッグを目的とするシステム運用ランブックです（ログ、アラート、k8s、オンコール）。ナレッジオペレーションのランブックは、業務プロセス（インシデント連絡の連鎖、ベンダーのオフボーディング、従業員のオンボーディング）を対象とするオペレーター向けランブックです。対象読者は、ログを追跡するエンジニアではなく、同じ業務を担うオペレーターです。
• project-management/* — Jira／Confluence による進捗管理、スプリントのチケットワークフロー、プロジェクト状況の報告です。ナレッジオペレーションが扱うのは、それらの Confluence ページのコンテンツであり、誰が編集するかの追跡ではありません。
• business-operations/process-mapper（関連ツール）— BPMN によるプロセスの設計です。各段階の位置、作業が滞留する場所、ボトルネックとなる段階を明らかにします。ナレッジオペレーションが扱うのはプロセスの文書化であり、マッパーが記述したプロセスの実行方法をオペレーターに伝える SOP やランブックの成果物です。
• business-operations/internal-comms（関連ツール）— 一斉告知、全社向けメッセージ、変更管理の連絡です。ナレッジオペレーションが提供するのは長期的に参照する成果物であり、internal-comms が提供するのは一斉配信です。
• ra-qm-team/* — 正式な規制コンプライアンス文書の作成（ISO 13485 QMS、MDR 技術文書、21 CFR Part 820）です。ナレッジオペレーションは規制関連のチェックリストを活用しますが、認証機関による監査の代替にはなりません。

強制質問ライブラリ（Matt Pocock のグリル・ディシプリン）

ツールを呼び出す前に、オーケストレーター（または /cs-grill-bizops）は、ユーザーに次の質問を1つずつ提示し、推奨回答と正典の引用を添えます。まとめて提示してはいけません。深さ優先で進めてください。1～3が確定するまで、質問4に進んではいけません。

1. 「このSOP／ランブックの指名オーナーは誰ですか？また、その人は自分がオーナーであることを認識していますか？」 推奨：担当者は1人の人間（「チーム」ではない）で、本人が書面で同意していること。 正典：Gawande 2009（The Checklist Manifesto）— オーナーのいないチェックリストは12か月以内に形骸化します。オーナーシップこそが規律です。

2. 「この文書が最後にレビューされたのはいつですか？レビューの頻度はどのくらいですか？」 推奨：過去12か月以内にレビューされていること（--profile regulated の場合は90日以内）。頻度がフロントマターに記載されていること。 正典：ISO 9001:2015 §7.5.3 — 管理文書にはレビューサイクルのメタデータが必要です。ITIL v4も、サービス運用のランブックについて同様の考え方を示しています。

3. 「ランブックの各ステップについて、観測可能な成功シグナルは何ですか？つまり、ステップが機能したことを示す具体的な出力は何ですか？」 推奨：具体的で観測可能なもの（「/healthz から HTTP 200 が返る」「Slack のスレッドが done のリアクション付きでクローズされる」「Salesforce の商談が Closed-Won ステージに移動する」など）であり、「サービスが稼働している」や「動作する」ではないこと。 正典：Beyer ら 2018（Site Reliability Workbook, Ch. 8）— 観測可能なシグナルこそがランブックの要です。曖昧な成功基準は、インシデント発生時にランブックが誤用される主な原因です。

4. 「失敗する可能性があるランブックの各ステップについて、ロールバックの手順は何ですか？」 推奨：状態を変更するすべてのステップに、ロールバックの手順、または「ロールバック不可 — X にエスカレーション」という明示的な記述があること。 正典：AWS Well-Architected Framework の運用上の優秀性の柱 — 「『元に戻す』とは何を意味するのかを事前に合意せずに、元に戻せないプロセスを実行することはできません」。

5. 「この文書はどこにありますか？また、ほかにどの文書からリンクされていますか？」 推奨：正典となるWikiにあり、関連文書から少なくとも2つのリンクが貼られていること。孤立したSOPは見つけられないSOPです。 正典：Atlassian Team Playbook のドキュメント健全性に関する指針 — 孤立率が20%を超えることは、Wikiの乱立問題を示す主要な指標です。

6. 「このプロセスに適用される規制要件は何ですか？SOC 2、HIPAA、ISO 13485、GDPR、SOX、それとも該当なしですか？」 推奨：明確な回答があること。「該当なし」の場合は、そのプロセスが扱うデータ分類を確認して裏付けること。 正典：FDA 21 CFR Part 211.100（文書化された手順、逸脱）— 規制対象のSOPには、バージョン管理、変更履歴、承認が必要です。このステップを省略すると、監査指摘事項になります。

7. 「文書化されているのは通常の手順だけですか？それとも、よくある障害モードのうち2～3件も文書化されていますか？」 推奨：プロセスごとに、頻度の高い障害モードの上位2件を、それぞれ独自の復旧サブ手順とともに文書化すること。 正典：Fowler 2016（Production-Ready Microservices）— 通常の手順しか扱わない運用文書が、インシデント対応時間の無駄の60%以上を引き起こしています。

7つすべてが確定したら、kb_ingester.py → runbook_validator.py → sop_generator.py の順に呼び出します。