dsh-prose-standard

DeepSeek Harness の文章作成基準

契約を保つのに十分な内容を書き、その後、推論の記録、繰り返し、装飾を取り除きます。契約とは、呼び出し元、呼び出し先、実装者、生成側、または利用側が依拠する義務、不変条件、事前条件、事後条件、または互換性の保証です。このスキルでは、編集上の判断と必要な文章の網羅性を担います。配置、分量、二言語の対、ドキュメントのゲートについては dsh-doc を、推論記録の漏えいの発見と修正については dsh-trim-cot-leakage を使用してください。これはガイダンスであり、台本ではありません。

contract、boundary、shape、surface、seam、gate、vocabulary は、使用禁止の言葉ではなく、使用前に検討する用語として扱ってください。まず、正確なルール、API、フィールドの集合、型、検証、タイミング、コンポーネントの分割、または失敗状態のほうが事実を適切に表現できるかを確認してください。呼び出し元と呼び出し先の契約や、セキュリティ上・プロセス上の境界など、正確な技術的対象を示す場合は、その用語を使ってください。

コメントには、コードでは表現できない、自明でない契約や理由を記述します。コードがすでに示していることを言い換えてはいけません。

入力と対象外

明示的な scope を必須とします。指定がない場合は、必要な入力を報告して停止してください。リポジトリ全体を対象と推測したり、聞き取りを始めたりしてはいけません。

mode: automatic | interactive を受け付けます。既定値は automatic です。ユーザーが質問または調整を明示的に求めた場合に限り、対話モードに入ってください。

mode が制御するのは質問であり、書き込み権限ではありません。レビューや監査のタスクでは編集せず、指摘事項を報告します。書き込み、修正、または削除を明示的に求められた場合は、明確な変更を適用します。

依頼された対象範囲がリポジトリ全体であっても、探索、レビュー、編集では常に vendor/ を除外してください。vendor/ 内へのシンボリックリンクをたどってはいけません。除外指定は包含グロブの後に置き、後続の包含指定で再び対象にならないようにしてください。たとえば、ripgrep コマンドの末尾には --glob '!vendor/**' を指定し、Git コマンドには :(exclude)vendor/** のパススペックを明示します。依頼された対象範囲が vendor/ のみの場合、対象となるファイルが残らないことを報告してください。

文章のレビューと編集では、.agents/notes/archived/ も除外してください。アーカイブされた Agent Notes は凍結されたスナップショットです。過去の参照元からの引用を理解するために限り、明示的に指定された対象を確認できます。文章や外部リンクを現行化してはいけません。

生成されたカタログ、スナップショット、フィクスチャは派生物として扱います。編集前に、利用側をすべてたどってください。ソースの JSDoc が、生成されたモデル可視のカタログにも使われている場合があります。まず所有元のソースまたはシナリオを編集し、その後、すべての派生物を再生成してください。ジェネレーターが所有元の文章から要約を抽出する場合は、抽出される文がその表示先で完結するようにしてください。二言語の対に、恒久的な所有元はありません。どちらの言語も更新時の原文にできます。軽量な手順に従い、対応する側を最小限更新して、対を再記録してください。

命題をすべて保持する

編集する前に、その文章に含まれる命題をすべて特定してください。該当する以下の要素をそれぞれ保持します。

• 行為者と動作。
• 条件、タイミング、順序。
• must、may、never などの法的・規範的な度合い。
• 否定的な保証と例外。
• 所有権、副作用、失敗モード、結果。

すべての事実を含む節が残り、結果がより明確になる場合に限り、形容詞、繰り返し、説明的な叙述を取り除いてください。語数を減らすこと自体は改善ではありません。

使用箇所には、完全なローカル契約を記述してください。呼び出し元やメンテナーがその場で必要とする動作、失敗、所有権、結果を含めます。アーキテクチャ、理由、アルゴリズム、履歴、詳細な例については、所有元のドキュメントへのリンクを積極的に使用してください。説明にはそれぞれ一つの本拠地を設けます。ただし、必須の契約上の事実は使用箇所に重複して記載してかまいません。

省略すると誤用や不適切な単純化を招くおそれがある場合は、自明でない理由を残してください。それ以外の場合は、結果を記載し、理由の説明がある箇所へリンクしてください。

説明の配置ごとに必要な内容

これは一方向に短縮する作業ではありません。コード、型、構造だけでは以下の必須事項が伝わらない場合は、説明を追加または復元してください。これらの事実が該当箇所から明らかな場合は、コメントを追加しないでください。

• 公開 JSDoc： 呼び出し元から見える戻り値の違い、例外や拒否、側作用、所有権、タイミング、キャンセル、永続性を記述してください。
• 内部コメント： 不変条件、競合の順序、所有権、セキュリティ境界、予期しない失敗動作など、非局所的な構造や明らかに複雑な局所構造の理解を助けてください。制御フローの実況やコードの言い換えは削除してください。
• モジュールコメント： モジュールの役割、依存関係、責務、明白でないアーキテクチャ上の選択を記述してください。アーキテクチャ上の選択については、その根拠を説明する箇所へリンクしてください。
• テスト： フィクスチャ、アサーション、プラットフォームへの対応、実際のエントリーパス、間接的な観察が必要な理由など、明白でないテスト設計だけを説明してください。手順の解説や項目の羅列は削除してください。
• クックブック： 前提条件、必要な操作、実際のエントリーパス、観察可能な検証、簡潔な警告を含めてください。
• README： 利用者向けの契約（設定、動作、失敗、制限事項、拡張ポイント、モデルから見える影響）を含めてください。パッケージが管理する、安定したモデル可視テキストを引用し、生成カタログと他パッケージが管理する内容へリンクしてください。長期的に重要な未解決点やメンテナンス時の落とし穴は残し、通常の整理項目は省いてください。パッケージ README の要件に従ってください。
• エージェントノート： 独自の根拠、仕組み、代替案、結果、リリース済みの検証証拠、明記されたカバレッジの不足を残してください。実装済みのエージェントノートでは、リリース済みの現状を現在形で記述してください。計画チェックリストは削除し、判断を裏付ける証拠は残してください。
• ポストモーテム： インシデントの経過、証拠、因果関係、影響、再発防止策を残してください。説得の繰り返しや因果関係を明らかにしない実装の詳細は削除してください。
• スキルとエージェント向け指示： 行動上のガードレールと、「スクリプト／チェックリストではなく、ガイダンスである」といった明示的な適用範囲の制限を記述してください。ワークフローは簡潔にまとめ、正本へリンクしてください。
• 例と設定コメント： アクセス制限、明白でない配線や読み込み順序、セキュリティ方針、再生動作、例外、想定される誤用を説明してください。設定からすでに分かる項目を実況しないでください。
• プロンプトと表示文字列： 文言も動作の一部として扱ってください。クライアント UI の文言は型付きロケール辞書に記述し、Cordis を使用しないプリミティブには明示的にローカライズ済みのプロパティとして渡します。テキスト、アクセシビリティ名、ツールチップ、プレースホルダー、書式テンプレートをまとめて確認し、その後 verify-client-ui-i18n を実行してください。プラグインの meta.title と meta.description を含む英語の UI 文言はセンテンスケースにします。大文字にするのは最初の語、固有名詞、Chrome DevTools、Git、MCP などの製品名だけです（Git worktrees とし、Git Worktrees とはしません）。中国語の文言には独自の表記規則を適用します。モデル可視テキストについては、それを管理する実行可能なスナップショットを更新し、リポジトリで必須とされる GUI の証拠も更新してください。許可された作業範囲に該当シナリオがない場合は、文言を変更せず、対応を見送ったことを報告してください。説明文だけの編集に黙って取り込んではいけません。
• 診断： 明白でない場合は、失敗している対象またはパス、違反している規則、修正方法を明記してください。内部処理の実況は削除してください。

検索可能な仕組みの名前と、意味のある法・時制・否定の強調は維持してください。装飾目的の強調のみを標準化してください。

ワークフロー

1. 対象範囲、モード、現在のブランチまたは PR のベース、および適用される AGENTS.md ファイルを確認します。無関係なブランチは調べないでください。
2. 文面を評価する前に、ドキュメントの標準と、該当箇所を管理するコードまたはドキュメントを読みます。判断基準の確認や、慣れていないケースでは、要約された例を読みます。
3. 最大のファイルだけでなく、依頼された対象範囲を調べます。検索や単語数を使って候補を見つけ、その後、文面の意味に基づいて判断します。
4. 各候補を、維持、追加、削減、復元、再構成、または保留に分類します。タスクで編集が許可されている場合に限り、明確な変更を適用します。削除目標を満たすために、存在しない編集を作り出してはいけません。
5. 派生成果物より先に、管理元を更新します。新しいルールを学んだら、類似の箇所を再確認します。
6. 対象範囲に関連するチェック、ドキュメントのゲート、git diff --check、および表示文字列の動作テストを実行します。最終的な差分に vendor/ のパスが含まれていないことを確認し、誤って vendor に一致した場合は、除外履歴がクリーンだったと主張せず、その旨を報告します。
7. 調査した範囲、明確な変更、意図的に維持した箇所、保留したケース、および実際に実行したチェックを報告します。

判断が分かれるケース

完全な命題のルールを満たす案が少なくとも 2 つあり、このスキルでトレードオフが解決されない場合に限り、判断が分かれるケースとします。命題を保った唯一の答えがある書き換えは、判断が分かれるケースではありません。

自動モードでは、許可されている場合は明確な編集を適用し、真に判断が分かれるケースは質問せずに報告します。作業を進めるために命題を弱めてはいけません。

対話モードでは、適用する原則に基づいて類似の箇所をまとめます。実行可能な案を 2～3 個提示し、推奨案と、事実または構造上の違いを述べます。劣る案を紛らわしい選択肢として提示してはいけません。ユーザーが指定したチャネルを使います。インラインコメントで PR の調整を行う場合は、推奨する暫定案を差分に反映し、代替案はその該当行に紐付けます。

ユーザーが決定した後、その原則と案を 例 にまとめます。PR の履歴やレビュアーの説明は含めません。その後、対象範囲内の類似するすべての箇所に、学んだルールを適用します。