code-quality-foundations
コード品質の要件、目標設定、抽象化レベル、トレードオフの考え方について学べます。コード品質の評価、品質目標の設定、適切な抽象化レベルの選択、設計上のトレードオフの検討、品質要件に対するコード監査が必要な場合に活用できます。可読性、モジュール性、テスト容易性、再利用性、最小驚き原則をカバーしています。
description の原文を見る
Code quality pillars, goals, abstraction layers, and tradeoff thinking. Use when evaluating code quality, setting quality goals, choosing abstraction levels, making design tradeoffs, or auditing code against quality pillars. Covers readability, modularity, testability, reusability, and the principle of least astonishment.
SKILL.md 本文
コード品質の基礎
高品質コードの4つの目標
| 目標 | 問うべき質問 | 失敗パターン |
|---|---|---|
| 動作する | 問題を正しく解決しているか？ | バグ、未処理のエッジケース、要件の未充足 |
| 動き続ける | 周囲の変化に耐えられるか？ | 脆弱な依存関係、テストがない、隠れた仮定 |
| 適応可能である | 要件変更があっても書き直さずにすむか？ | 堅い結合、過度な設計、ハードコードされた仮定 |
| 車輪の再発明をしない | 実証済みのソリューションを再利用しているか？ | 既に解決された問題向けのカスタムコード、重複した作業 |
コード品質の6つの柱
| 柱 | 意味 | 主要なテクニック |
|---|---|---|
| 読みやすい | 他のエンジニアがすぐに理解できる | 記述的な名前付け、クリーンなレイヤー、一貫したスタイル |
| 驚きがない | 動作が予期と一致する(POLA) | 明示的なコントラクト、マジック値なし、隠れた副作用なし |
| 誤用しにくい | 正しくない方法で使う方が難しい | 型安全性、イミュータビリティ、検証された構築 |
| モジュール化されている | コンポーネントを独立して入れ替えられる | インターフェース、DI、関心の分離、凝集度 |
| 再利用可能で一般化できる | 1つのケースだけでなく、広く問題を解決する | 焦点を絞ったパラメータ、ジェネリクス、仮定を避ける |
| テスト可能である | 分離して検証できる | モジュール化がテスト可能性を実現；設計時から考慮する |
POLA = Principle of Least Astonishment(最小驚き原則)。関数が合理的な呼び出し側が予期しないことをする場合、たとえ「動作」しても、それは設計上のバグです。
現代的な追加事項(2024-2026年 業界コンセンサス)
| 関心事 | 現在明示的な理由 | 元々の分類 |
|---|---|---|
| セキュア | シフトレフトセキュリティ；設計時の脅威モデル | 「動作する」に暗黙的に含まれていた |
| 効率的 | リソース最適化は事後的ではなく、設計上の選択 | 「動作する」に包含されていた |
| 信頼できる | 明示的なエラーリカバリーと段階的な機能低下 | 「動き続ける」に包含されていた |
判定表
「これを抽象化すべきか？」
| シグナル | アクション |
|---|---|
| 同じロジックが2箇所以上に現れている | 共有する関数/クラスに抽出する |
| 関数を1文で説明できない | より小さな関数に分割する |
| クラスのメソッドグループが異なるフィールドを使用している | 別のクラスへの分割を検討する |
| 1つの機能を変更するために多くのファイルに触れる必要がある | モジュール化とレイヤー境界を改善する |
| ユースケースが1つだけ存在する | 待つ — 時期尚早に抽象化しない |
「品質努力をどこに投資すべきか？」
| 状況 | 焦点 | 根拠 |
|---|---|---|
| グリーンフィールドプロジェクト | モジュール化、クリーンなインターフェース | 基礎の決定は複合的に影響；早期に構造を整える |
| レガシーコードベース | テスト、読みやすさ | 安全に変更する前に理解する |
| 高トラフィックサービス | 信頼性、効率性、テスト | 本番障害は高くつく |
| プロトタイプ/スパイク | 動作するコード、速度 | アイデアを検証；書き直しを計画する |
| 共有ライブラリ/API | 誤用しにくさ、驚きがなさ | コンシューマーがどう使うかを予測できない |
| セキュリティに関連するコード | セキュリティ、テスト可能性 | 違反は壊滅的で信頼を失わせる |
チェックリスト
コード作成前に
- 問題が明確に理解されている(要件、制約、エッジケース)
- 既存ソリューションをチェックした(ライブラリ、共有コード、先行事例)
- テスト戦略を検討した(これをどのように検証するか？)
- 主要なトレードオフを識別した(何を選択し、何を諦めるか？)
コード品質の自己レビュー
- 関数が1文に翻訳できる
- 驚きがない：動作が名前と型に一致している
- 誤用しにくい：可能な限り無効な状態を表現できない
- モジュール化されている：変更が局所化され、散らばっていない
- テスト可能である：複雑なセットアップなしでユニットテストできる
- クリーンな抽象化：API が実装詳細をリークしていない
ライセンス: MIT(寛容ライセンスのため全文を引用しています) · 原本リポジトリ
詳細情報
- 作者
- smileynet
- リポジトリ
- smileynet/code-spice
- ライセンス
- MIT
- 最終更新
- 2026/3/1
Source: https://github.com/smileynet/code-spice / ライセンス: MIT
関連スキル
doubt-driven-development
重要な判断はすべて、本番環境への展開前に新しい視点から対抗的レビューを実施します。速度より正確性が重要な場合、不慣れなコードを扱う場合、本番環境・セキュリティに関わるロジック・取り消し不可の操作など影響度が高い場合、または後でバグを修正するよりも今検証する方が効率的な場合に活用してください。
apprun-skills
TypeScriptを使用したAppRunアプリケーションのMVU設計に関する総合的なガイダンスが得られます。コンポーネントパターン、イベントハンドリング、状態管理（非同期ジェネレータを含む）、パラメータと保護機能を備えたルーティング・ナビゲーション、vistestを使用したテストに対応しています。AppRunコンポーネントの設計・レビュー、ルートの配線、状態フローの管理、AppRunテストの作成時に活用してください。
desloppify
コードベースのヘルスチェックと技術負債の追跡ツールです。コード品質、技術負債、デッドコード、大規模ファイル、ゴッドクラス、重複関数、コードスメル、命名規則の問題、インポートサイクル、結合度の問題についてユーザーが質問した場合に使用してください。また、ヘルススコアの確認、次の改善項目の提案、クリーンアップ計画の作成をリクエストされた際にも対応します。29言語に対応しています。
debugging-and-error-recovery
テストが失敗したり、ビルドが壊れたり、動作が期待と異なったり、予期しないエラーが発生したりした場合に、体系的な根本原因デバッグをガイドします。推測ではなく、根本原因を見つけて修正するための体系的なアプローチが必要な場合に使用してください。
test-driven-development
テスト駆動開発により実装を進めます。ロジックの実装、バグの修正、動作の変更など、あらゆる場面で活用できます。コードが正常に動作することを証明する必要がある場合、バグ報告を受けた場合、既存機能を修正する予定がある場合に使用してください。
incremental-implementation
変更を段階的に実施します。複数のファイルに影響する機能や変更を実装する場合に使用してください。大量のコードを一度に書こうとしている場合や、タスクが一度では完結できないほど大きい場合に活用します。