dsh-doc

DeepSeek Harness ドキュメント

概要

DeepSeek Harness のドキュメント標準では、すべてのページを検索可能で、初めて読む人にも理解しやすく、エージェントやメンテナーにとって十分に正確なものにし、ドキュメントサイトをリポジトリ内の Markdown のテスト済みの投影として維持します。まずリポジトリの AGENTS.md ファイルと実行済みのゲートを適用し、その後、このワークフローに従って、種別に対応するメタデータ、段階的な詳細、行単位で対応するバイリンガルページ、コーパス監査、ウェブサイトへの公開を進めます。事実ごとに所有者を一つに保ちます。ソース、テスト、生成されたカタログ、パッケージの README、ガイド、Agent Notes、スクラッチ資料は、それぞれ固有の種類の情報を保持します。session-persistence-jsonl の README ペアを、この形式の参考例とします。

目次

• ワークフロー
• 事実確認の手順：思い込みではなくテストする
• 種別システムとテンプレート
• 文体のルール
• 品質基準
• コーパスを監査する
• 語数の予算
• ウェブサイトへの公開
• 詳細な参考資料
• 検証
• 開発者向け注記

ワークフロー

依頼された範囲ごとに、次の手順に従います。読者がたどる一般的な流れは簡潔に保ちますが、語数を減らすためだけに、失敗、所有者、制限事項、その他の必須要件を削除してはいけません。

1. ルートと、より具体的な AGENTS.md、ドキュメント標準、対象ページ、そのソースとテスト、ナビゲーションの所有者、バイリンガル記録を読みます。
2. ページの主な役割と読者を分類します。製品のクイックスタート、ユーザー向けタスクガイド、コントリビューター向けチュートリアル、アーキテクチャ概要、パッケージ／サブシステムのリファレンス、生成されたリファレンス、エージェント向け指示、決定記録、またはスクラッチ資料のいずれかです。
3. ページを最も近い所有者のもとに配置します。パッケージの要件はパッケージのコードのそばに置きます。パッケージをまたぐ学習資料、ユーザー向け資料、開発者向け資料、アーキテクチャ資料、議論資料、期限付きのスクラッチ資料には docs/ を使用します。
4. 詳細を書く前に、読者の開始状態、観察可能な成果、起こりそうな失敗、復旧方法、次に役立つ詳細レベルを定義します。
5. YAML メタデータを追加または修正します。このドキュメントの役割に対応するテンプレートに沿って kind を割り当てます。その後、ドキュメントの種類が許す範囲で、Summary、Table of Contents、ユーザー向けの内容、開発者向けの内容、任意の Further Exploration、最後の Dev Note の順に記述します。
6. 同じ作業の中で、バイリンガルの対応ページも更新します。見出し、リスト、表、コード、リンク、フロントマターのレイアウト、物理的な行数を一致させます。
7. すべての記述を、コード、テスト、ジェネレーター、パッケージメタデータ、または現在の決定所有者に照らして検証し、事実確認の手順に従って、ページで説明している操作を実行します。派生成果物を更新する前に、所有者を更新します。
8. 対象を絞ったチェックを実行し、続いて pnpm run test:docs、pnpm run doc-sync、pnpm run lint、git diff --check を実行します。正確性を確認し、次に簡潔さとリポジトリへの適合性を確認するため、差分全体を読み直します。

事実確認の手順：推測せず、テストする

ドキュメントには製品の現在の動作を記載します。操作に関する主張を裏付ける証拠として認められるのは、実際に実行した結果だけです。この手順は、操作、コマンド、デフォルト、エラー、またはプラットフォームによる違いを記載するすべての新規ドキュメントおよび新規段落で必須です。

1. インストール手順を書く前に、対象を分類します。 フォルダー名ではなく、事実を確認してください。package.json で dsh.bundle.patch の宣言を調べ、エントリーファイルでプラグインの形を確認します（apply のエクスポート、またはデフォルトのサービスエクスポートがあればプラグイン、プレーンなモジュール API ならライブラリです）。バンドルは dsh plugin --profile <name> add <package> でインストールし、このコマンドでプロファイルレイヤーが有効になるパッケージの形はバンドルだけです。プラグインは cordis.yml の行としてマウントします。ライブラリは独自のインストール手順を持たない依存関係です。特殊なステータスを持つパッケージ（ライブラリ、バンドル）には、それぞれ専用の README テンプレートを使用してください。適用されないインストール手順を載せたプラグイン用 README を使ってはいけません。
2. 記載するすべての操作を、現在のチェックアウトで実行します。 各 CLI コマンド、設定スニペット、プロファイルまたはパッチの例を、ドキュメントに記載するのとまったく同じ内容で実行してください。実際に確認できたことだけを書き留め、出力、警告、失敗時の動作は正確に記録します。利用できないキーやネットワークに依存する主張については、動作を断定せず、その旨と検証担当者を記載してください。
3. 再現できなかった内容は削除します。 記憶、類推、隣接するパッケージの README を根拠に、コマンド、フィールド、デフォルト値、動作を引き継いではいけません。主張を再現できなかった場合は、テストではなく主張を修正してください。
4. 古いドキュメントを最新の master と照合します。 既存ページを改訂する前に git fetch origin を実行し、該当セクションを origin/master と比較してください。ペアリング用サイドカーでは、どちら側についても最後に確認済みのテキストを復元できます。master 上の記述が古くても誤りであることに変わりはありません。古い文章ではなく、コードに照らして修正してください。
5. 編集のたびにペアを再記録します。 ペアとなる編集を行うたびに pnpm run verify-translation-pairing --write <pair> を再実行し、サイドカーに確認済みのペアを反映します。

kind システムとテンプレート

kind フロントマター項目は、README テンプレートを正確に 1 つ選択します。メタデータリファレンスにある各 kind は、templates/ 内のテンプレートファイル 1 つに対応し、各テンプレートも正確に 1 つの kind に対応します。ドキュメントチェックでは、同じ機械的な根拠から期待される kind を導き出します。

• package-group → templates/package-group.md：パッケージグループのマップ（packages/README.md、packages/<group>/README.md）。グループ全体の概要を示し、直下のパッケージを整理して、それぞれのパッケージが管理する詳細情報にリンクします。
• package-reference → templates/package-reference.md：Cordis プラグインまたはサービスパッケージ。マウント設定、設定テーブル、折りたたまれた実装、Model Experience、Known Limitations を、ゲートが管理する形式で記述します。
• package-library → templates/package-library.md：プラグインのインターフェースを持たないパッケージ。利用側のエントリーポイントを示し、プロファイルへのインストール手順とマウント設定は含めません。
• package-bundle → templates/package-bundle.md：dsh.bundle.patch を宣言するパッケージ。検証済みの dsh plugin インストール手順、レイヤーのセマンティクス、パッチドキュメントを記述します。
• persistence-change → templates/persistence-change.md：docs/persistence-changes/ 内の日付付き記録。検出された型の移行を認め、ルートごとの移行前型と生成された移行後スキーマを記述します。
• persistence-release → templates/persistence-release.md：docs/persistence-changes/releases/ 内の固定タグ。互換性を認めることなく、再構築された過去の型を比較します。
• persistence-format → templates/persistence-format.md：docs/persistence-changes/historical-formats/ 内の過去の Session 形式のチェックポイント。完全なスキーマを記載し、現在のライターが既存のカタログを使用することを示します。
• upgrade-guide → templates/upgrade-guide.md：docs/upgrade-guide/v<version>/<item>/guide.md と、その中国語版。外部から認識できる 1 つの破壊的変更に対する移行手順を記述し、dsh-create-upgrade-guide が管理します。

執筆前にテンプレートを開き、ひな形とルールに従ってください。テンプレートには、その kind の定義、ページの構成、各セクションで確認すべき事項が記載されています。新しい kind を追加する場合は、必ず専用のテンプレートファイル、リポジトリ内での位置づけの文書化または担当者の明示、その kind にドキュメントを対応づける専用チェックをセットで追加してください。

文体ルール

これらのルールは、各セクションで記述できる内容を定めます。人が読むすべてのページに適用され、特にパッケージの README では厳守してください。

• 概要では対象が何をするかを説明します。 冒頭の Summary とユーザー向けセクションでは、対象を使ってユーザーやエージェントができること（成果、メリット、選ぶべき場面、主なコスト）を説明してください。対象の役割、種類、内部的なアイデンティティは説明しないでください。パッケージの概要で「それが何か」を説明する場合は、読者から見える機能だけを指し、Cordis における役割、登録、内部コンポーネントは含めません。読者が設定、コマンド、公開 API で直接使用しない限り、ソース識別子は省略してください。「seam は ctx.x を登録し、x/event レコードを追加します」はアイデンティティの説明です。「メッセージごとにメモを保存でき、再起動後もそのメモが残ります」は対象ができることの説明です。
• 開発者向けセクションでは説明し、列挙はしません。 折りたたみ式の実装内容では、パッケージの動作を理解できるように、全体的な設計の考え方、アーキテクチャ、概略的なデータフローを説明し、正確な詳細はコードへのリンクで示してください。折りたたみ内に API の全件一覧、カラムの完全な一覧、イベントペイロードの列挙、JSDoc の言い換えを含めないでください。
• Dev Note だけは未整理の内容を記載できます。 断片的なアイデア、メモ書き、未決定の方針、測定結果の断片、作業中の仮説は、最終的な Dev Note にのみ記載し、明示的に非公式な情報として示してください。それ以外のすべてのセクションでは、推敲済みの現状の説明を記載してください。
• 現状のみを記述します。 通常のドキュメントでは、現在のコードベースについて説明してください。専用の persistence-change、persistence-release、persistence-format の各記録では、過去の型の証拠を保持します。リリース比較とフォーマットのチェックポイントでは、互換性を主張せず、確認された履歴を説明してください。upgrade-guide では、そのバージョンディレクトリのリリースから次のリリースへの変更を説明してください。Agent Notes と事後分析では、それぞれの履歴上の対象範囲を保持します。
• 統制された技術英語を使用します。 曖昧さによって動作が変わり得る場合は、各文で行為者を明示し、主要な動作を一つにしてください。概念ごとに用語を統一し、直接的な動詞を優先し、重なり合った指示や条件は分けてください。法性や例外はそのまま保ってください。ページのスタイルリファレンスにある、認証を受けていない ASD-STE100 準拠の規律を適用してください。正確さが損なわれる場合は、無理に文を短くしないでください。

品質基準

レビューでは、以下の定義を使用してください。各セクションは、サブセクションや網羅的な詳細に入る前に、概要を示す短い段落から始めてください。

• 簡潔： 一般的な手順には、目的の結果に必要な情報だけを含めます。網羅的な情報には、直接リンクまたは詳細レイヤーを一つたどればアクセスできるようにします。
• 直感的： 前提条件を、それに依存する概念より先に説明します。次に行う操作が明確で、見出しには読者が検索する用語を使用します。
• 親しみやすい： 読者が成功を確認でき、実行前にリスクを理解でき、起こりやすい失敗から復旧でき、さらに詳しく読み進めるかを選べるようにします。
• 正確： 永続的な主張には、それぞれ責任の所在と、リスクに見合った検証方法を示します。
• エージェントが読み取りやすい： メタデータ、安定した見出し、アンカー、用語、責任の所在、現状か提案かの区別により、コーパス全体を読み込まなくても、目的に合った情報を検索できるようにします。
• 初学者にも十分： リポジトリの予備知識がないプロのエンジニアが、関連するアーキテクチャや機能を、リンクされた3〜5ページを通じて把握できるようにします。

網羅的なリファレンスに一律の語数制限を適用しないでください。情報への到達経路の長さ、1件の情報を探す際に読む無関係な内容の量、最大セクションの大きさ、見出し数、ページサイズを評価してください。情報の検索コストが高い場合は、既存のドメインオーナーごとに分割してください。

コーパスを監査する

担当する規約を読み、要約し直さないでください。階層、チュートリアル／リファレンスの形式、分類、上限、避けるべき表現のチェックリストについては docs/AGENTS.md、Agent Note のライフサイクルについては .agents/notes/README.md、日英ペアのルールについては docs/i18n/README.md、常時適用される指示については root AGENTS.md を参照してください。監査と編集では .agents/notes/archived/ を除外してください。アーカイブされたノートは変更不可の履歴です。

標準の執筆手順を、対象となる人間向けの文書すべてに適用してください（Agent Note は対象外です）。まず文書の場所を特定し、その文書自体の主題を明確にします。許容される詳細度を定め、より詳しい説明は担当する下位文書に移してリンクします。パスではなく想定用途に基づいて、チュートリアルかリファレンスかを分類します。チュートリアルの場合は、前提知識と難易度に沿って概念を並べます。実質的に異なる形式が混在している場合は分割します。次に、配置上の制約を確認します。ペアになっている文書を編集するたびに、対になる文書の更新と --write による再記録が必要です。生成されるカタログは手作業で編集してはいけません。ファイルの移動は、すべての参照元リンクを同じ変更内で修正する、不可分な作業です。

構造の確認後、手軽に実行できる調査から順に、避けるべき表現のチェックリストを確認します。推論トランスクリプトの漏出には dsh-trim-cot-leakage を使用し、特徴的な語句を grep で検索して重複するルールを見つけます。手書きのカタログやステータス一覧は、正式な管理元への参照に置き換えます。実装済みの Agent Note からは、移行計画と未来形の仕様表現を削除します。pnpm run verify-doc-budgets --list と単語数のスキャンで、基準から外れた文書を測定します。文章の削除によって、説明ではなく約束された動作が変わる場合は、まず動作の変更を提案してください（dsh-find-simplifications に従ってください）。動作の根幹をなすルールはすべて残し、できれば根拠へのリンクを添えて1〜3行にまとめます。不要な推論を移すためだけに、新たな説明を作成してはいけません。

単語数の上限

pnpm run verify-doc-budgets は、常時参照される文書を scripts/doc-budgets.manifest.json の上限と比較します。チェックに失敗した場合は、docs/AGENTS.md に記載された「移動、簡潔化、上限引き上げ」の順序に従ってください。上限はガードレールであり、削減目標ではありません。目標以下の場合は、少なくとも5%の余裕を残してください。上限を引き上げるのは、その語数分の余地が必要な場合に限り、PR ではマニフェストの差分を正当化してください。

ウェブサイトへの公開

ウェブサイトはテスト済みの投影であり、第二のコピーではありません。website/docs.ts は、正式な docs/ のソースをルートツリーに対応付ける、明示的な公開許可リストです。scripts/project-doc-site.ts はそれらを書き換えて一時的な website/.generated/ ツリーを作成し、VitePress はそのツリーをビルドします。編集可能なコンテンツソースはリポジトリ内の Markdown のみです。翻訳は兄弟ファイルのペア（foo.md、foo.zh.md、foo.i18n.yaml）として配置し、ロケール別のディレクトリは作成しません。公開済みページを編集する場合は、正式なソースのみを編集してください。新しいページにはマニフェスト項目を1つ追加します。ページの移動や削除では、ソース、マニフェスト項目、参照元リンクを同じ変更内で更新してください。website/.generated/、website/.cache/、website/.dist/ は編集してはいけません。すべての DocsPage フィールドを意図的に設定し、プロジェクターのリンク規則を守ってください。フィールド、サイドバーのコレクション、プレビューコマンドについては references/website-sync.md を参照してください。コンテンツをビルドに同期しても公開されるわけではありません。デプロイは、別途明示的に依頼された場合にのみ行います。

詳細なリファレンス

タスクに必要なリファレンスのみを読み込んでください。各リファレンスはこのファイルから直接リンクされているため、スキル内で深い参照チェーンが発生しません。

• メタデータ、リンク、バイリンガルペア：README のフロントマター、kind システムとその導出方法、説明文の意味、リポジトリのパス、行の対応、サイドカーレコード。
• ページの構成と階層：必須のセクション順、セクションの概要、ユーザー向けから開発者向けへの展開、ドキュメントツリー内の配置、小規模なルールファイル、Further Exploration、Dev Note の管理者。
• ページのスタイル：簡潔な Summary、----- セクション区切り、折りたたみ可能なコンテンツセクション、強調表現のルール。
• レビュー基準：初心者向けの確認、根拠の確認、パッケージ README のレビュー、参照例、検証コマンド。
• ウェブサイトへの公開：マニフェストのフィールド、プロジェクターのリンクルール、プレビューと検証、デプロイの分離。

templates/ 内のテンプレートには、各 kind に対応する実用的なひな形があります。執筆前に、ドキュメントの kind に指定されたものを開いてください。

文単位で契約の網羅性と編集上の判断を確認するには、dsh-prose-standard を使用してください。参照例は、session-persistence-jsonl の README ペア（英語、中国語）です。検索可能な YAML、Summary と Table of Contents、折りたたみ式の開発者向けセクションを含むユーザー向けから開発者向けへの展開、Further Exploration、標準の Model Experience セクションと Known Limitations セクション、最後の Dev Note を備えています。

検証

Markdown の構文だけでなく、対象の形式を検証してください。強い保証を設ける場合は、対象を絞った有効なフィクスチャと、トップレベルのゲートが失敗することを示す無効なフィクスチャを用意してください。

• README メタデータ：YAML を解析し、kind をテンプレートとドキュメント標準に対応付け、name、audience、管理対象外の tags、README 内の i18n メタデータを拒否します。また、説明文がない場合や、広告のような説明文も拒否します。
• バイリンガルページ：構成、行数の一致、用語、リンクの一致、サイドカーレコードを検証します。
• チュートリアル：記載された開始手順を実行するか、手動検証を担当する明確なオーナーを指定します。
• 生成されたリファレンス：決定論的な鮮度チェックを実行し、取得サイズの指標を報告します。
• パッケージ README：Summary ゲートを実行します。このゲートでは英語の各 Summary を wc -w 形式で 100 語以内に制限し、失敗した場合はこのスキルと kind テンプレートを確認するよう案内します。Model Experience と制限事項のチェックを実行し、動作に関する説明を変更した場合はパッケージを対象とするテストを実行します。また、README に記載された内容に関する説明をマージする前に、その README が指示するすべてのコマンドを再実行します。
• スキル：リポジトリのスキル呼び出しメタデータチェックを実行します。

包括的なドキュメントチェック（ペアリング、折り返し、リンク、README ゲート、予算、スキルメタデータ、Agent Note ゲート）を手早く実行するには、完全な pnpm run doc-sync の前に pnpm run test:docs を実行してください。

Dev Note

なし。