write-openspec-docs

OpenSpec のドキュメントを書く

これから OpenSpec のユーザードキュメントを作成します。writing.md を読み、ここで作成するすべての内容のスタイル基準にしてください。要点は次のとおりです。すぐに適用してください。

• ページはエッセイではなく、情報を探すための場所です。読者が答えを見つけられるかどうかは構成で決まり、文章は読みやすさを決めるにすぎません。各セクションは答えから始め、話の流れを追う書き方はしないでください。
• 概要を作る前にページの種類を決めてください。ガイドは読者の作業に沿って構成し、リファレンスは製品の構造を反映させ、正確なフィールド名、コマンド名、ファイル名を見出しとして使ってください。リファレンスには網羅性が必要です。複数の事実を一つの文、セル、段落に詰め込まないでください。
• 答えになる最短の形で書いてください。簡潔なページを拡張するのは簡単ですが、冗長なページを削るのは書き直しになります。簡単な言葉をできるだけ少なく使ってください。一行で収まる考えは一行で書きます。多くの読者が読み飛ばす詳細はリンク先に置き、ペイロード（コマンド、実際の出力、失敗と対処法）は省略せずに載せてください。
• 文は単純に、構成は賢くしてください。明白な文を書きます（主語、動詞、目的語を示し、実際に起きることを述べます）。別の事実を詰め込んだり、ひねった表現にしたりしないでください。大げさな形容詞、前置き、ダッシュは使わないでください。
• 一つの箇所には一つの役割を持たせてください。一文に一つの事実、リストの導入文ではリストの内容だけを予告し、各セクションでは読者の質問または検索対象を一つだけ扱います。関連する事実にも、それぞれ独立した箇所を用意し、別の箇所に便乗させないでください。
• 読者が確認できる情報を基準にしてください。パスやフォルダーを先に示し、概念は補足説明として添え、実際の出力はありのままに示します。
• 固定のテンプレートはありません。一覧では、まずすべての項目を挙げたリストを示し、その後、各項目をそれぞれ独立した単位で説明します。リスト内に説明を書き込まないでください。手順には番号付きリストを使います（番号は順序を示します。一覧には箇条書きを使います）。一つの考えや理由は、短い文章で示します。
• 重要な事実はすべて、ひと目で見つけられる形式で示してください。コードフェンス、番号付きの太字リード文、**用語**: 事実 の箇条書き、表、ファイルツリーを使います。段落の途中にだけ記載してはいけません。
• 仕上げる前に、最後の確認を二つ行ってください。検索性：質問や正確な製品名を、ページをざっと見るだけで見つけられますか？ひと目でわかるか：レンダリングしたページを形として確認し、最後まで読めそうに見えますか、それとも読むのが大変そうに見えますか？表の多い変更は、デスクトップと狭い画面の両方で確認してください。問題があれば、必要性のない箇所に内容を置いています。レビューに任せず、今すぐ直してください。

基本ルール

• 作成を始める前に no-ai-slop スキルを読み込んでください。このスキルは一般的なスロップのパターンを扱い、writing.md は OpenSpec のドキュメントに特有の見た目や文体を定めています。
• 編集前に対象ページを最後まで読んでください。
• 実際の事実のみを記載してください。フラグ、パス、出力はソースにあるとおりにします。主張を簡単に確認できない場合でも記載しますが、その内容を示すときに未確認であると明記してください。もっともらしい文で不足を埋めてはいけません。
• 事実は一つのページに記載し、それ以外のページではそのページにリンクしてください。ドキュメントツリーの README では、ページ構成と構造上の不変条件を定めています。構成を変更したり、ページを追加したりする前に確認してください。
• リファレンスページの場合は、文章を書き始める前にソースから仕様を洗い出してください。writing.md のリファレンス作成手順に従ってください。
• どのような見せ方や文体にするか迷ったら、具体例に合わせてください。セクションの構成と一覧には docs-lab/start/setup.md、複数手順のタスクには docs-lab/start/installation.md の「アンインストール」を参考にします。

完了時

変更内容をユーザーに示し、未確認の主張があれば明記してください。

ユーザーが、根拠を重視した詳細な執筆セッション（すべてのコマンドを実行し、各セクションを一度に一つずつ作成し、正式なチェックポイントを設けること）を求めた場合は、full-process.md に従ってください。