ドキュメント標準
すべてのページを検索可能で、初心者が読め、エージェントやメンテナーにとって正確にすること。階層、作成ルール、予算、スロップチェックリストは docs/AGENTS.md にあります。このスキルはそれらを適用するためのワークフローを担当します。事実ごとに一つの所有者を維持します：ソース、テスト、生成カタログ、README、ガイド、エージェントノートはそれぞれ独自の種類の真実を保持します。これはガイダンスであり、チェックリストではありません。
ワークフロー
要求されたスコープごとにこの順序に従ってください。一般的な読者のパスは簡潔に保ちますが、失敗、所有権、制限、その他の必須契約を削除して単語数を減らしてはいけません。
- ルートおよびサブツリーの
AGENTS.mdファイル、docs/AGENTS.md、対象ページ、そのソースとテスト、およびそのナビゲーション所有者を読みます。 - ページを一つの主要なジョブと読者に従って分類します：クイックスタート、ユーザータスクガイド、コントリビューター向けチュートリアル、アーキテクチャ概要、モジュールリファレンス、生成リファレンス、エージェント命令、決定記録、またはスクラッチ。
- ページを最も近い所有者に配置します。モジュール契約はモジュールのコードの隣に置きます。クロスモジュールの学習、ユーザー、開発者、アーキテクチャ資料には
docs/を使用します。 - 詳細を書く前に、読者の開始状態、観察可能な結果、起こりそうな失敗、回復パス、および次の有用な深さを定義します。
- ページ構造 で指定された順序で書きます：タイトル、概要、目次、ユーザー向けコンテンツ、開発者向けコンテンツ、オプションの Further Exploration。
- プロファイルが
surfaces.bilingual-docsを有効にしている場合、同じパスで対応するドキュメントを更新し、見出し、リスト、表、コード、リンクを行ごとに揃えます。 - すべての主張をコード、テスト、ジェネレーター、パッケージメタデータ、または現在の決定者に対して検証し、ページが指示する操作を実行します（以下のファクトチェック手順を参照）。派生物より先に所有者を更新します。
- プロファイルの
commands.docs-checkとgit diff --checkを実行し、完全な差分を一度正確さのために、もう一度簡潔さと適合性のために読み直します。
ファクトチェック手順：テストし、仮定しない
ドキュメントは今日の製品の振る舞いを述べ、操作に関する主張の許容可能な証拠はそれを実行したことだけです。これはすべての新しいページと、コマンド、デフォルト、エラー、出力、またはプラットフォームの違いを主張するすべての新しい段落に適用されます。
- インストールや使用ガイダンスを書く前に主題を分類します。 フォルダ名ではなく、事実（マニフェスト、エントリポイント、エクスポート）を読みます。ライブラリ、プラグイン、CLI、サービスはそれぞれ異なる使用パスを持ちます。別の種類のために書かれたガイダンスを決してコピーしないでください。
- 主張されたすべての操作を現在のチェックアウトに対して実行します。 ページに表示される通りに各コマンド、構成スニペット、例を正確に実行します。観察したことだけを書き留め、警告や失敗モードも含めます。主張が資格情報や利用できないネットワークに依存する場合は、その旨を述べ、動作を断定する代わりに検証責任者を指名します。
- 再現できなかったものは削除します。 記憶、類推、または隣接する README からコマンド、フィールド、デフォルト、または振る舞いを持ち込まないでください。主張が再現に失敗した場合、テストではなく主張を修正します。
- 古いドキュメントを最新のデフォルトブランチと照合します。 既存のページを改訂する前に、デフォルトブランチに対して取得して比較します。古い記述は古い散文ではなく、コードに基づいて修正します。
文体ルール
- 概要は主題の機能を述べます。 概要とユーザー向けセクションは、読者がその主題で何ができるか（成果、選ぶタイミング、主なコスト）を説明し、内部のアイデンティティや登録については決して述べません。読者が構成、コマンド、または公開APIで直接使用する場合を除き、ソース識別子は省略します。
- 開発者セクションは説明し、列挙しません。 開発者の詳細には、設計コンセプト、アーキテクチャ、おおよそのデータフローが含まれ、どのように機能するかを理解するのに十分であり、正確な詳細のためにコードにリンクします。完全なAPIカタログ、列リスト、またはAPIドキュメントの再記述はありません。
- 現在の状態のみ。 通常のドキュメントは現在のコードベースを説明します。履歴はエージェントノート、事後分析、リリースノート、アップグレードガイドに属します。
- 管理された技術英語。 あいまいさが振る舞いを変える可能性がある場合、各文に明示的な行為者と一つの主要なアクションを与えます。概念ごとに一つの用語を再利用します。積み重なった指示は分割します。法性と例外を保持します。ページ構造 を参照してください。
品質基準
- 簡潔： 一般的なパスには、その成果に必要な事実のみが含まれます。完全な真実は1つのリンクまたは詳細レイヤー先にあります。
- 直感的： 前提条件は依存する概念の前に置かれ、一つの次のアクションが明らかで、見出しには読者が検索する用語を使用します。
- 親切： 読者は成功を認識でき、行動する前にリスクを理解し、起こりそうな失敗から回復でき、より深く進むかどうかを選択できます。
- 正確： 各耐久性のある主張には一つの所有者と、そのリスクに見合った検証パスがあります。
- エージェントが読める： 安定した見出し、アンカー、用語、所有権は、コーパス全体をロードすることなく対象を絞った検索をサポートします。
- 初心者に完全： リポジトリのコンテキストがないエンジニアでも、3～5のリンクされたページを通じて関連するアーキテクチャや機能を再構築できます。
網羅的なリファレンスに一律の単語制限を適用しないでください。エントリパスの長さ、ルックアップごとにスキャンされる無関係な資料、最大のセクションを測定し、検索コストが高い場合は既存のドメイン所有者によって分割します。
コーパスの監査
スコープ内のすべての人間向けドキュメント（エージェントノートは除く）に docs/AGENTS.md の作成順序を適用します：ドキュメントを見つけ、その主題を述べます。許可される詳細を設定し、より深い説明は所有する子に移動します。パスではなく意図された使用法からチュートリアルまたはリファレンスを分類します。実質的な混合形式は分割します。移動は、同じ変更内ですべてのインバウンドリンクが修復された場合にアトミックです。生成カタログは手動で編集されません。
次に、docs/AGENTS.md のスロップチェックリストを、最も安価なプローブから探します。trim-cot-leakage を使用して推論トランスクリプトの漏洩を探し、特徴的なフレーズを検索して重複ルールを探し、手書きのカタログを信頼できる所有者に置き換え、実装されたエージェントノートから仕様書の言葉を削除します。散文を削除すると、その説明ではなく約束された振る舞いが変わる場合は、最初に振る舞いの変更を提案します (find-simplifications を参照)。すべての負荷のかかるルールは、できれば1～3行とその根拠へのリンクとして保持します。
詳細リファレンス
- ページ構造とスタイル：ページ順序、セクションの進行、折りたたみ、管理された技術英語、強調。
- レビュー基準：初心者テスト、エビデンスレビュー、README レビュー。
文レベルの契約範囲と編集判断には prose-standard を使用します。