openclaw-refactor-docs

OpenClaw リファクタリング用ドキュメント

概要

ユーザーから対象となる OpenClaw ドキュメントページが示され、書き換え、リファクタリング、再構成、分割、短縮、または改善を求められた場合は、このスキルを使用します。

このスキルは technical-documentation を基盤としています。スタイル、ページの種類、構成、例、見つけやすさ、検証については、そのスキルを使用してください。このスキルでは、大規模なドキュメントのリファクタリング中に正確な動作情報が失われるのを防ぐための書き換えワークフローを追加します。

入力

必須：

• docs/plugins/codex-harness.md のような、対象ドキュメントページのパス。

任意：

• トピックページ、ガイド、リファレンス、トラブルシューティングなど、希望するページの種類。
• メインページの短縮、詳細のリファレンスページへの移動、現在の CLI の動作との整合など、具体的な目標。
• 関連するソースファイル、スキーマ、コマンド、テスト、仕様、PR。

対象ページが見つからない、または曖昧な場合は、編集前に簡潔な質問を1つしてください。それ以外の場合は、そのまま進めてください。

作業上の契約

対象ページを、明示された範囲内でより有用、簡潔、かつ包括的なものにリファクタリングします。

書き換えを、動作に関する事実を削除する許可とみなしてはいけません。既存の内容は保持、検証、移動するか、明示的に廃止してください。誤ったドキュメントは、冗長なドキュメントよりも問題です。

次のように分割することを推奨します。

• トピックページやガイドでは、主要な利用手順、読者が判断する必要のある項目、安全なセットアップ、最小限で信頼できる検証、よくある失敗、関連ページへのリンクを扱います。
• リファレンスページでは、網羅的なフィールド、デフォルト値、列挙値、制限、優先順位のルール、API の契約、詳細な内部仕様、まれなデバッグ情報を扱います。
• トラブルシューティングページでは、観測可能な症状を起点に、確認項目、原因、解決方法を示します。

ワークフロー

1. ドキュメント標準を確認する

まず ../technical-documentation/SKILL.md を読みます。リファクタリング全体を通じて、ページの種類、スタイル、例、ナビゲーション、検証に関するガイダンスを適用してください。

利用可能な場合は pnpm docs:list を実行し、その後、対象ページと、リファクタリングに必要な可能性が高いエントリーポイント、リファレンス、関連ページのみを読みます。

2. ページの種類を分類する

編集前に、technical-documentation に基づいて、想定するページの種類を決めます。

現在のページで複数の種類が混在している場合は、メインとなるページの種類を選び、他の内容の移動先を計画します。

• 網羅的な契約事項は、既存または新規のリファレンスページに移します。
• 症状に基づく内容は、既存または新規のトラブルシューティングページに移します。
• メインの流れを妨げる個別のセットアップ手順は、ガイドに移します。
• 読者がワークフローを完了するために必要な、簡潔な案内、判断、安全に関する詳細は、メインページに残します。

3. 既存の事実を保持し、監査する

書き換える前に、元のページから作業用の項目一覧を作成します。次の内容を含めてください。

• 設定フィールド、フラグ、コマンド、スラッシュコマンド、環境変数、デフォルト値、列挙値、null 許容値、制約。
• 優先順位のルール、フォールバック動作、上限、制限、レート制限、タイムアウト、ライフサイクルの状態、キュー動作、互換性のルール。
• 認証、権限、承認、サンドボックス、安全性、プライバシー、破壊的な操作に関する動作。
• セットアップ要件、対応バージョン、依存関係、オペレーティングシステム、認証情報、アカウント要件。
• エラーメッセージ、トラブルシューティングの症状、診断、復旧手順。
• 例、期待される出力、コマンドのルーティング表、相互リンク。

各事実について、次のいずれかを選びます。

• リファクタリング後の対象ページに残す。
• 既存の特定のページに移す。
• 新規作成する特定のページに移す。
• 現在のソースにより古い、または対象範囲外であることが確認できるため削除する。

名前や意図から、デフォルト値、権限、ポリシー、タイムアウトの動作、安全性に関する方針を推測してはいけません。必ず検証してください。

4. 信頼できる情報源を見つける

振る舞いに影響する各主張について、最も近い権威ある情報源を使用します。

• 設定フィールドについては、公開スキーマ、プラグインマニフェスト、生成された設定ドキュメント、またはエクスポートされた型。
• コマンドとフラグについては、CLI の実装、スラッシュコマンドのハンドラー、ヘルプテキスト、およびコマンドのテスト。
• ライフサイクル、キューイング、権限、フォールバック、タイムアウト、およびプロバイダーの動作については、ランタイムのソースとテスト。
• API とプラグインのサーフェスについては、プロトコルドキュメント、SDK ファサード、およびコントラクトテスト。
• 既存のドキュメントは、対象が純粋に概念的な場合を除き、二次的な証拠としてのみ使用します。

ページがリファレンスを約束している場合は、その表をスキーマ、マニフェスト、CLI ヘルプ、生成されたドキュメント、またはエクスポートされた型と比較します。公開フィールド、デフォルト、優先順位ルール、上限、または副作用の欠落は、正確性のバグです。

5. 移動する資料を計画する

対象ページから詳細を移動する場合は、編集する前に移動先を記録します。

• 既存ページ: ページ名とセクションを指定します。
• 新規ページ: ページタイプ、スラッグ、タイトル、frontmatter の概要、doc-schema-version: 1、および read_when ヒントを選択します。
• 対象ページ: 読者がより詳細な情報を必要とする箇所に、短い概要とリンクを残します。

真実の重複は避けます。同じコントラクトが複数の箇所に現れる場合は、1 つの正規ページを選び、そこへリンクします。

6. 書き直す

次の順序で書き直します。

1. 最初の画面で、読者が何をできるか、そしてこのページがなぜ存在するかに答えるようにします。
2. 推奨されるパスを代替案より前に置きます。
3. 意思決定と一般的な運用上の詳細のみをメインフローに残します。
4. 網羅的な表とまれな詳細は、計画したリファレンスページに移動します。
5. 読者がコマンド、設定パス、ハーネス、プラグイン、プロバイダー、またはリファレンスを選択するのに役立つ場合は、簡潔なルーティング表を保持します。
6. トラブルシューティングは、内部の推測ではなく、観察可能な症状から追加します。
7. 関連する概念、ガイド、リファレンス、診断、および隣接するツールへのリンクを追加します。

リファクタリングが移行、作成、または実質的に書き直すすべてのドキュメントページの YAML frontmatter に doc-schema-version: 1 を追加します。これはドキュメントページファイルにのみ適用し、docs.json、用語集 JSON、その他の非ページメタデータには適用しません。移行したページが生成される場合は、生成された出力を手で編集するのではなく、再生成してもマーカーが保持されるようにジェネレーターを更新します。

ユーザーが明示的にドラフトを求めない限り、"TODO"、"TBD"、"see docs" のようなプレースホルダーを残さないでください。

7. 旧版と新版を比較する

編集後、旧ページと新ページを比較します。

• 振る舞いに影響するすべての事実が、情報源に基づく理由をもって保持、移動、または意図的に削除されたことを確認します。
• メインページが 80/20 のシナリオをエンドツーエンドでカバーしていることを確認します。
• リファレンスページが、主張する範囲に対して網羅的であり続けていることを確認します。
• 対象ページからのリンクが、移動した詳細に到達することを確認します。
• 見出しが安定しており、検索可能で、アクション指向であることを確認します。

リファクタリングが関連する資料を意図的に削除した場合は、最終レポートでそれがどこへ移動したか、またはなぜ削除されたかを述べます。

8. 検証する

影響を受けたサーフェスに対して、最も小さく信頼できるドキュメントチェックを実行します。

• pnpm docs:list
• git diff --check -- <touched-files>
• 対象を絞った pnpm exec oxfmt --check --threads=1 <touched-files>
• pnpm docs:check-mdx
• pnpm docs:check-links
• リンクテキスト、ナビゲーション、ラベル、または用語集のサーフェスが変更された場合は pnpm docs:check-i18n-glossary
• スキーマ、生成された設定ドキュメント、API ドキュメント、または生成されたベースラインが影響を受ける場合は、生成ドキュメントのチェック

可能な限り、ページのコマンドと例を実行します。振る舞いに影響する主張を検証できない場合は、その主張を削除するか、作業中レポートに不確実性を記録するか、不足している情報源を求めます。

最終レポート

次を報告します。

• 対象ページで何が変更されたか。
• どの詳細が移動し、その移動先ページはどこか。
• 振る舞いに影響する主張をどの情報源チェックが裏付けたか。
• どの検証が実行され、無関係な理由で何が失敗したか。

長々とした書き直しの日記は含めないでください。残存するリスクがある場合のみ、それを先頭に置きます。