ub-quality

UB Quality

重要な契約

この SKILL.md が読み込まれたら、埋め込みのベースラインを直ちに適用してください。

より詳細な品質ルールに依存する作業では、出力を作成する前に、このスキルのトリガーテーブルに従って関連するリファレンスを読み込んでください。タスクが小さく見える場合や、ローカルのスタイルが異なる場合でも、トリガーされたリファレンスを省略してはいけません。

編集対象となる適格な縦区切りブロックでは、区切り記号を必ず1列に揃えてください。値の列に揃える形式（key: value）ではなく、区切り列に揃える形式（key : value）を使用してください。

これは、構造が適格であれば、コード、設定、コメント、docstring、マークアップ属性、ドキュメントブロック全般に適用されます。

<style> や <script> などの埋め込み言語ブロックは、汎用的な HTML テキストとしてではなく、ネイティブの CSS および JavaScript の書式設定対象として扱ってください。

構文の破損、またはツールやランタイムの制約が確認されている場合に限り、編集対象となる適格なブロックを整列せずに残すことが正当化されます。

準拠例：

grid      : ''
solar     : ''
textMuted : ''

非準拠例：

grid:      ''
solar:     ''
textMuted: ''

使用する場面

次の作業では、主要な実装、レビュー、またはワークフロースキルと併用してください。

• 新しいコードの生成
• コードの編集とリファクタリング
• コードレビューへの対応
• リポジトリのスキャン、アーキテクチャの説明、保守性に関するフィードバック
• 編集対象箇所におけるドキュメント、設定、コメント、書式の正規化
• 明確な構成や比較形式が必要なユーザー向けの回答

コードやドキュメントを作成、変更、レビュー、リファクタリング、または正規化する際に、共通の品質ルールや可読性ルールが役立つ場合は、このスキルを適用してください。

任意扱い禁止

• 書式設定と整列を、任意のクリーンアップ作業として扱わないでください。
• このスキルが読み込まれた場合、その書式設定と整列のルールは、編集対象となるすべての適格なブロックに適用されます。
• 周辺のコードが整列されていないから、短いスタイルのほうが馴染みがあるから、またはコードではなくドキュメント内のブロックだからという理由で、整列を省略しないでください。
• より広範な正規化が明示的に依頼されていない限り、編集対象となる論理的な範囲外の無関係なブロックは正規化しないでください。

リファレンス読み込みの契約

ub-quality 自体は、常に読み込まれるベースラインです。より詳細なリファレンスは任意ではなく、すべてのタスクであらゆる品質領域が対象となるかのように扱うのではなく、適切な契約を適切なタイミングで適用するため、トリガーに応じて読み込みます。

必ず読み込んで適用するもの：

• アーキテクチャ、実装、リファクタリング、抽象化、依存関係、または保守性に関する判断を行う場合は、references/design-patterns.md。
• コード、設定、例、コメント、docstring、マークアップ属性、ドキュメントの表、または区切りブロックを含むその他の編集対象コンテンツを作成または変更する前に、references/formatting-alignment.md。
• ドキュメント、コメント、ファイル構造、公開される呼び出しインターフェース、または大規模なソースファイルを作成、編集、レビュー、再構成、またはリファクタリングする前に、references/documentation-structure-refactoring.md。
• 生成ドキュメント、コメントタグ、TODO のようなマーカー、または特別な保持タグを含む可能性のあるコンテンツを作成または変更する前に、references/important-tags-and-doc-generation.md。
• ユーザー向けの計画、レビュー、説明、比較など、構成が読みやすさに大きく影響する回答を作成する前に、references/response-readability.md。
• ガイダンスがリポジトリのポリシー、強く推奨される標準、最新性に関する助言、または移植性に関する懸念のいずれに当たるかを判断する場合は、references/freshness-portability.md。

複数のトリガーに該当する場合は、依存する出力を作成する前に、関連するすべてのリファレンスを読み込んでください。

非準拠

変更対象のブロックが整列の対象となる場合、以下は非準拠です。

• 整列対象となる縦方向の区切りブロックで、区切りが一つの列を形成していない。
• 整列対象となるブロック内の値列が整列されている。
• 変更対象の内容が整列の対象であるにもかかわらず、埋め込み CSS／JS ブロックをネイティブ言語ブロックとしてフォーマットせずに残す。
• 都合、省略、または周囲のローカルスタイルを理由に整列を省略する。
• 変更対象の論理的な範囲外にある無関係なブロックを正規化する。

意思決定分析の基本方針

計画、設計、アーキテクチャ、実装方針、およびその他の選択を伴う指針では、次の方針に従います。

• 原則として、妥当な選択肢を 2+ 個提示します。
• 網羅的に列挙するのではなく、厳選した 2-4 個の選択肢を優先します。
• 各選択肢の簡潔な長所と短所を示し、推奨する方針を特定します。
• 実質的に意味のある方針が一つしかない場合は、そのことを明示し、他の選択肢に実質的な違いがない理由を説明します。見せかけの選択肢を作ってはいけません。
• 実際に価値がある場合、関連するスキルがドメイン固有のトレードオフの観点を追加することは妨げません。

読みやすさの基本方針

チャット、計画、レビュー、仕様、説明など、ユーザー向けの回答では次の方針に従います。

• 回答、推奨事項、または要点を最初に示します。
• 内容のある回答には、内容が伝わる見出しを付けます。
• 段落を短くし、視覚的に区切ります。
• 項目の列挙には箇条書き、順序のある手順には番号付きリストを使います。
• リスト項目の文法と意図を統一します。
• 表は、複数の属性を簡潔に比較する場合にのみ使います。
• 構成によって一覧性が向上する場合は、密度の高い文章ブロックを避けます。
• 短い回答は簡潔にし、形式的な装飾を避けます。

表のルール：

• 左右の比較が実質的に見やすくなる場合に限り、簡潔な表を優先します。
• 表は通常、列数を 2-4 列に抑え、見出しを短く、セルの内容を簡潔にします。
• 文のように長い文章を表のセルに押し込まないでください。
• 表が広すぎる、密度が高すぎる、またはレンダラーで崩れやすい場合は、表を維持しようとせず、より安全な形式に切り替えてください。

基本ワークフロー

1. タスクの範囲と変更対象ファイルを確認します。
2. 埋め込まれた基本方針をすぐに適用します。
3. 出力に影響する内容を作成する前に、タスクによって適用対象となるすべての参照資料を読み込み、適用します。
4. 計画、設計、アーキテクチャ、実装方針、およびその他の選択を伴う指針には、意思決定分析の基本方針を適用します。
5. ユーザー向けの回答には、読みやすさの基本方針を適用し、表とより安全な形式のどちらを使うか選択します。
6. 動作と制約を維持できる、最もシンプルな方法を選びます。
7. フォーマット、ドキュメント、構造に関するルールは、変更対象の論理ブロックにのみ適用します。
8. 動作を検証し、適用対象となる参照資料で認められた意図的な例外があれば説明します。

スキルの連携

• 利用可能な場合は、このスキルを最も関連性の高い言語／フレームワークのスキルと組み合わせて適用します。
• このスキルは補完的な基本方針として扱い、主要な実装スキルやワークフロースキルの代わりにしないでください。
• 構文、ランタイム、フレームワークの正しさを最優先の制約として扱います。
• フォーマッターの好みや慣れ親しんだチーム内スタイルを、整列要件に違反する正当な理由として扱わないでください。
• 動作の仕組みはコードと命名で表現し、ドキュメントとコメントは契約、根拠、そして自明でない制約の説明に使うことを優先します。

ポリシーとデフォルト

• このリポジトリでは、ub-quality が読み込まれている場合、整列要件と適用対象の参照資料に従うワークフローはリポジトリのポリシーです。
• 関連するスキルを通じて連携される言語／フレームワークの推奨事項の多くは、強く推奨されるデフォルトであり、普遍的な移植性要件ではありません。
• 変わりやすいセットアップ手順は、リポジトリが明示的にポリシーとして定めている場合を除き、自動的な阻害要因とせず、まず最新性を確認する対象として扱います。

出力要件

コードを生成または変更する場合：

1. 意味のある実装上の選択について、簡潔なメリット・デメリットと推奨案を示してください。
2. 解決策はシンプルにし、過度な設計は避けてください。
3. 変更が明示的に求められていない限り、既存の動作を維持してください。
4. 意図的に残した技術的負債や、後回しにしたクリーンアップがあれば明記してください。
5. 特に共有ガイダンスや広く再利用されるコードでは、広範な説明よりも、要点を絞った高シグナルなドキュメントを優先してください。
6. ユーザー向けの説明は、詳しく読む前に要点を把握しやすい形にしてください。
7. 情報の形に合わせて構成を選び、密度の高い文章や過度に大きな表を安易に使用しないでください。

完了前の確認

最終化する前に、以下を確認してください。

• 変更した対象となるすべての区切り線ブロックを確認してください。
• 変更した <style> および <script> の内容は、ネイティブの CSS および JavaScript の対象として扱ってください。
• references/formatting-alignment.md で求められている場合は、密度の高い複数行対応構造（リテラル、引数リスト、設定／データブロックなど）を、項目ごとに1行の形式に展開してから、対象項目を整列してください。
• references/formatting-alignment.md の最長左側トークンのルールに従い、区切り線を1列に揃えてください。
• 関連のないブロックを整形し直していないことを確認してください。
• 対象となるブロックが未整列のまま残っている場合、references/formatting-alignment.md に記載された例外が適用されない限り、編集は未完了です。
• 特殊なコメントタグと AGENT_TODO の取り扱い方針が守られていることを確認してください。
• ユーザー向けの回答では、答えや推奨案を早い段階で示してください。
• 見出し、箇条書き、手順、表、代替ブロックは、情報を把握しやすくする場合にのみ使用してください。
• 箇条書きの各項目が、並列で簡潔な表現になっていることを確認してください。
• 表によって情報がわかりやすくなることを確認し、横幅や情報密度の問題がないようにしてください。
• 比較表が広すぎる、または文章量が多すぎる場合は、無理に表形式にせず、項目を積み重ねた代替形式に切り替えてください。
• 簡潔な回答は簡潔なままにしてください。