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

OpenClaw ドキュメントリファクタリング は何をしますか？

概要

ユーザーが対象のOpenClawドキュメントページを指定し、書き換え、リファクタリング、再編成、分割、短縮、または改善を依頼した場合にこのスキルを使用します。

このスキルは technical-documentation スキルを基盤としています。スタイル、ページタイプ、構造、例、発見容易性、および検証については、technical-documentation スキルを使用してください。このスキルは、大規模なドキュメントリファクタリング中に正確な動作情報を失わないために必要な書き換えワークフローを追加します。

入力

必須:

• 対象のドキュメントページパス（例: docs/plugins/codex-harness.md）。

オプション:

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

対象ページが見つからないか不明な場合は、編集を開始する前に簡潔な質問を1つ行ってください。それ以外の場合は、先に進んでください。

作業契約

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

書き換えを、動作に関する事実を破棄する許可とは見なさないでください。既存の内容は、保持、検証、移動、または明示的に廃止してください。不正確なドキュメントは、冗長なドキュメントよりも悪質です。

以下の分割を推奨します:

• トピックまたはガイドページは、80/20パス、読者が下すべき決定、安全なセットアップ、最小限の信頼性のある検証、一般的な障害、および詳細へのリンクをカバーします。
• リファレンスページは、網羅的なフィールド、デフォルト値、列挙型、制限、優先順位ルール、API契約、狭い内部動作、およびまれなデバッグ詳細をカバーします。
• トラブルシューティングページは、観測可能な症状から始めて、チェック、原因、修正にマッピングします。

ワークフロー

1. ドキュメント標準を読み込む

最初に ../technical-documentation/SKILL.md を読んでください。そのページタイプ、スタイル、例、ナビゲーション、および検証ガイダンスをリファクタリング全体に適用します。

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

2. ページを分類する

編集前に、technical-documentation から意図されたページタイプを決定します。

現在のページがページタイプを混在させている場合は、メインのページタイプを選択し、他の内容の属する場所を計画します:

• 網羅的な契約は、既存または新しいリファレンスページに移動します。
• 症状ベースの内容は、既存または新しいトラブルシューティングページに移動します。
• 狭いセットアップワークフローは、メインパスを中断する場合にガイドに移動します。
• 簡潔なルーティング、決定、および安全に関する詳細は、読者がワークフローを完了するために必要な場合、メインページに残します。

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

書き換え前に、古いページから作業用インベントリを作成します。以下を含めます:

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

各事実に対して、以下のいずれかの結果を選択します:

• リファクタリングされた対象ページに保持する。
• 特定の既存ページに移動する。
• 特定の新しいページに移動する。
• 現在のソースが廃止または範囲外であることを証明しているため、削除する。

デフォルト値、権限、ポリシー、タイムアウト動作、または安全性の姿勢を、名前や意図から推測しないでください。それらを検証してください。

4. 真実のソースを見つける

動作に敏感な各主張について、最も近い権威あるソースを使用します:

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

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

5. 移動する内容を計画する

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

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

真実の重複を避けてください。同じ契約が複数の場所に現れる場合は、正規のページを1つ選択し、そこにリンクします。

6. 書き換える

以下の順序で書き換えます:

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

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

ユーザーが明示的にドラフトを要求しない限り、「TODO」、「TBD」、「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
• スキーマ、生成された設定ドキュメント、APIドキュメント、または生成されたベースラインが影響を受ける場合の生成ドキュメントチェック

実行可能な場合は、ページからコマンドと例を実行してください。動作に敏感な主張を検証できない場合は、その主張を削除するか、作業中レポートに不確実性を記載するか、不足しているソースを尋ねてください。

最終レポート

以下を報告します:

• 対象ページで何が変更されたか。
• どの詳細が移動し、その移動先ページはどこか。
• 動作に敏感な主張を裏付けるために、どのような真実のソースチェックが実行されたか。
• どの検証が実行され、無関係な理由で失敗したものはどれか。

長い書き換え日記を含めないでください。残存リスクがある場合にのみ、それらを先頭に記載してください。