NemoClawドキュメントへの貢献

このガイドでは、NemoClawのドキュメントの執筆、編集、レビュー方法を説明します。ユーザー向けの動作に影響するコード変更を行った場合は、同じPRで関連ドキュメントも更新してください。

エージェントスキルの活用

AIコーディングエージェント（Cursor、Claude Code、Codexなど）を使っている場合、リポジトリにはドキュメント作業を自動化するスキルが含まれています。ゼロから書く前にまず試してみてください。

スキルは.agents/skills/にあり、以下のスタイルガイドに自動的に従います。使うには、エージェントに実行を依頼してください。例：「v0.2.0以降にマージされた内容をドキュメントに反映して」。

ドキュメントを更新すべきタイミング

以下に該当する変更を行った場合、ドキュメントを更新してください：

• CLIコマンドやフラグの追加、削除、リネーム。
• デフォルト動作や設定の変更。
• ユーザーが操作する新機能の追加。
• ドキュメントの記述が不正確だったバグの修正。
• API、プロトコル、ポリシースキーマの変更。

ローカルでのドキュメントビルド

ドキュメントをビルドして出力を確認します。

ビルドコマンド：

make docs

ローカルでサーブし、変更時に自動リビルド：

make docs-live

執筆規約

フォーマット

• ドキュメントにはMyST Markdown（Sphinx互換のCommonMarkスーパーセット）を使用します。
• 各ページはYAMLフロントマター（title、description、topics、tags、content type）で始めます。
• フロントマターの後にSPDXライセンスヘッダーを含めます。

フロントマターテンプレート

---
title:
  page: "NemoClawページタイトル — コンテキスト付きサブタイトル"
  nav: "短いナビタイトル"
description: "ページの一文要約。"
keywords: ["主要キーワード", "二次キーワードフレーズ"]
topics: ["generative_ai", "ai_agents"]
tags: ["openclaw", "openshell", "relevant", "tags"]
content:
  type: concept | how_to | get_started | tutorial | reference
  difficulty: technical_beginner | technical_intermediate | technical_advanced
  audience: ["developer", "engineer"]
status: published
---

ページ構成

1. title.pageの値と一致するH1見出し。
2. そのページで扱う内容を示す1〜2文のイントロダクション。
3. H2とH3でタスクまたはコンセプトごとにセクションを整理。各セクションは読者を導く導入文で始めます。
4. ページ下部に関連ページへのリンクを含む「次のステップ」セクション。

スタイルガイド

同僚に説明するように書いてください。直接的、具体的、簡潔に。

文体

• 能動態を使う。「CLIがgatewayを作成する」であり、「gatewayがCLIによって作成される」ではありません。
• 読者を「あなた」と呼びます。
• 現在時制を使う。「コマンドがエラーを返す」であり、「コマンドがエラーを返すでしょう」ではありません。
• 事実を述べる。「簡単に」「もちろん」などの曖昧な修飾は避けます。

避けるべきパターン

以下のパターンはLLM生成テキストによく見られ、技術系読者の信頼を損ねます。レビュー時に削除してください。

フォーマットルール

• すべての文を句点で終える。
• ソースファイルでは1文1行（diffの可読性向上）。
• CLIコマンド、ファイルパス、フラグ、パラメータ名、値にはcode書式を使用。
• CLIサンプルのコードブロックにはconsole言語を指定。コマンドの前に$を付ける：

  $ nemoclaw onboard

• 構造化された比較には表を使用。表はシンプルに（ネストした書式は避ける）。
• コールアウトにはブロック引用の注意書き（> **注意：**、> **警告：**）を使用。太字ではなく。
• ネストした注意書きは避ける。
• セクションタイトルに番号を振らない。
• タイトルにコロンを使わない。
• コロンはリストの導入にのみ使用。

用語リスト

以下を統一的に使用してください：

ドキュメント変更の提出

1. プロジェクトの規約に従ってブランチを作成。
2. 変更を実施。
3. make docsでローカルビルドし、出力を確認。
4. docs:をconventional commitタイプとしてPRを作成。

docs: update quickstart for new onboard wizard

ドキュメント変更がコード変更を伴う場合は同じPRにまとめ、コード変更のcommitタイプを使用：

feat(cli): add policy-add command

ドキュメントPRのレビュー

ドキュメントのレビュー時：

• 上記のスタイルガイドが守られているか確認。
• LLM生成パターン（過剰な太字、ダッシュ、フィラー）に注意。
• コードサンプルが正確で実行可能か検証。
• 相互参照とリンクが壊れていないか確認。
• ローカルビルドでレンダリングを確認。