Communityコーディング&開発github.com

エンジニアリング原則

コーディングスキル。機能実装、バグ修正、モジュールやAPIの設計、リファクタリング、コードレビューにおいて、ソフトウェアエンジニアリングの基本原則とUnix哲学を適用します。単純さ、抽象化、重複、結合、契約、テスト、依存関係、パフォーマンス、CLIツール、構成可能性に関する決定に特に使用します。原則を儀礼的なチェックリストではなく、具体的なトレードオフと検証済みの変更に変換します。散文のみの編集や無関係な非コーディングタスクには使用しません。

エンジニアリング原則 とは?

このスキルは、コーディングエージェント(Claude Code, Cursor, Codexなど)向けに設計された、ソフトウェアエンジニアリングの原則とUnix哲学を実践的に適用するためのガイドです。機能実装、バグ修正、API設計、リファクタリング、コードレビューなど、あらゆるコーディングタスクにおいて、単純さ(KISS/YAGNI)、結合度と凝集度、抽象化とDRY、SOLID原則、依存関係管理、パフォーマンスといった概念を、単なる理論ではなく実際の設計判断に結びつける方法を提供します。このスキルは「原則を守ること自体が目的」ではなく、要件やリポジトリの規約、証拠に基づいたトレードオフ分析を重視します。動作ループとして、契約の確立、比例した設計、一度に一つの関心事の変更、動作の検証、変更の完了という5つのステップを定義し、リスクに応じて規模を調整します。また、デバッグやリポジトリワークフロー、Unix哲学に基づくコンポーネント設計(メカニズムとポリシーの分離、合成可能性、検査可能な表現など)、安全な進化と検証(リファクタリングと意図的な変更の区別、テスト戦略)についても具体的な指針を示します。単なるチェックリストではなく、実際の変更に影響を与えた場合にのみ原則を説明することを推奨し、最終決定チェックリストで完了を確認します。

対応~Claude Code~Codex CLI~Cursor
npx skills add https://github.com/NickLitharis/groundwork/tree/HEAD/engineering-principles

Installed? Explore more コーディング&開発 skills: steipete/bluebubbles, steipete/eightctl, steipete/blucli · View all 6 →

お気に入りのAIに質問する

このエージェントスキルを事前に読み込んだ状態で新しいチャットを開きます。

ドキュメント

エンジニアリング原則 は何をしますか?

理解可能で安全に変更可能な、最小限の正しい解を構築します。原則を、要件、リポジトリの規約、または証拠よりも優先される法律としてではなく、推論のためのツールとして扱います。

作業ループ

  1. 契約を確立する。 関連するコード、呼び出し元、テスト、リポジトリの指示を読みます。必要な動作、入力、出力、不変条件、失敗モード、互換性の制約を特定します。観察された事実と仮定を区別します。未解決の要件が解決策を実質的に変更する場合にのみ質問します。
  2. 比例した設計を選択する。 ローカルパターンと既存の機能を再利用します。直接的な実装を優先します。実際の複雑さを内包するか、実際の境界を保護する場合にのみ構造を追加します。変更が触れるセキュリティ、データ整合性、リソース制限を考慮します。
  3. 一度に一つの関心事を変更する。 差分を凝集させます。無関係な作業を保持します。動作を保持するリファクタリングと意図的な動作変更を分離し、それぞれがレビュー可能にします。観測された症状だけでなく、原因を修正します。
  4. 約束された動作を検証する。 関連する失敗パスを含む、最も狭い意味のあるテストまたは実行可能なシナリオを使用します。実際に実行されたものを検査します。空のテスト選択は何も証明しません。合格テストは、それらが実行するアサーションとパスの証拠であり、すべての正確性や互換性の証明ではありません。
  5. 変更を完了する。 影響を受ける呼び出し元、契約、ドキュメントを更新します。この変更によって不要になったコードを削除します。結果、検証、および残っている制限を簡潔に報告します。原則が決定に実質的に影響を与えた場合にのみ説明します。

このループをリスクに応じて拡大縮小します。ローカルな名前変更にはほとんど儀式は必要ありません。共有APIや永続データの変更には、消費者と移行の証拠が必要です。日常的な編集のために、設計ドキュメントを作成したり、専門家の連鎖を製造したりしないでください。

デバッグとリポジトリワークフロー

ユーザーから報告された障害を再現として扱います。単に確認するために繰り返しを求めないでください。観察された動作と仮説を分離し、次に可能性の高い原因を区別する証拠を収集します。推測でコードを変更するのではなく、焦点を絞った再現、対象を絞った検査、またはデバッガを使用します。原因を修正し、秘密を公開せずに有用な診断情報を保持し、パスを成功に見せかけるためにエラーを抑制しないでください。障害が部分的な状態を残す可能性がある場合は、欠落している回帰カバレッジを追加し、関連するリカバリ動作を検証します。

リポジトリの既存のビルド、テスト、実行、生成エントリポイントを使用します。それらの文書化された前提条件を読み、人間とCIが使用するのと同じコマンドを呼び出します。2番目のツールチェーンを追加したり、リポジトリに別の適切なインターフェースがある場合にMakeを要求したりしないでください。一致するテストがないテストコマンドは証拠になりません。

有用なコントリビュータドキュメントを維持します。コードだけでは説明しない理由、不変条件、主要なフローを保存します。影響を受けるドキュメントを更新し、対象読者に合わせてユーザーリファレンス、チュートリアル、トラブルシューティング資料を選択します。変更と無関係な広範なドキュメント書き換えは避けてください。

設計原則

正確性は契約から始まる

パターンを選択する前に、何が真でなければならないかを定義します。適切な型、コンストラクタ、明示的な状態遷移を使用して、無効な状態を表現しにくくします。ミュータブルな状態とリソースのライフタイムの所有権を明確にします。

信頼できない入力を境界で検証します。防御的に見えるからといってチェックを削除しないでください。その条件が不可能か、すでに保証されているか、それとも依然として実際の障害モードであるかを確認します。秘密を漏洩せずに、有用なエラーコンテキストを保持します。失敗をでっち上げた成功結果に決して変えないでください。

単純さ:KISS と YAGNI

KISSは、単なる行数ではなく、保守担当者が理解しなければならない複雑さを最小限にすることを意味します。YAGNIは、推測される将来の機能ではなく、現在の要件を実装することを意味します。どちらも、欠落したエラーハンドリング、安全でないストレージ、または保守不可能な近道を許容しません。

現在の必要性なしに、プラグイン、汎用フレームワーク、設定レイヤー、拡張ポイントを避けてください。シンプルな設計でも、後での変更を安価にする明確な境界を持つことができます。

システム全体の複雑さ

本質的な複雑さ(問題によって要求される)、オプションの複雑さ(コストがかかる機能)、偶発的な複雑さ(指定された動作の実装における回避可能な困難さ)を区別します。これらを推論カテゴリとして使用し、機能の割り当てとしては使用しません。実装、インターフェース、統合、およびユーザーの労力とエラーリスク全体に適用します。ある場所でコストを下げると、別の場所にコストが移動する可能性があります。偶発的な複雑さを取り除きます。オプションの機能は、そのユーザー価値が全ライフサイクルコストを正当化する場合に保持します。期限が迫っている場合は、現在の提供価値をエンドツーエンドの労力、サポート、メンテナンスと比較します。行数や機能が少ないだけでは、全体的なコストが低いとは言えません。例については、複雑さ、インターフェース、パフォーマンスを参照してください。

凝集性、結合度、情報隠蔽

同じ理由で変更されるコードをグループ化します。独立して変更される懸念事項を分離します。変わりやすい実装の選択を、小さな一貫性のあるインターフェースの背後に隠します。パススルーラッパーの連鎖よりも、有用な作業を行う深いモジュールを優先します。

インターフェースは、共有メカニズムが識別可能な呼び出し元に役立ち、一方の呼び出し元のポリシーを埋め込まない場合、ある程度汎用的であっても構いません。現在の使用法が正当化する以上に汎用的にしないでください。推測される将来のニーズは、現在の呼び出し元に負担をかける可能性があります。契約が本当に特定のものである場合は、特殊化されたインターフェースを選択します。

単一責任は、変更する一貫した理由に関するものであり、クラスあたり1つのメソッドではありません。低結合度は、コンシューマが内部についてほとんど知る必要がないことを意味し、すべての呼び出しにインターフェースが必要であることを意味するわけではありません。依存関係の方向を明示的にし、可能な限り循環を避けます。

抽象化とDRY

DRYとは、知識の断片に対して信頼できる唯一の表現を持つことであり、類似したすべてのシーケンスを排除することではありません。呼び出し元が同じルールを表現し、一緒に進化する必要がある場合にロジックを共有します。表面的に類似したコードは、異なる概念やライフサイクルに属する場合、別々にしておきます。

知識が生成ファイルにも現れる場合は、その信頼できるソースとジェネレーターを特定します。再生成の前に関係のない編集を保護します。重複する所有権を上書きするのではなく解決します。生成された出力を恒久的な修正として手動で編集したり、些細な作業のために生成メカニズムを追加したりしないでください。抽出する前に、共有契約、変更が予想される理由、抽象化によって取り除かれる複雑さを特定します。数値的な繰り返しの閾値を証拠として使用しないでください。少しの重複は、間違った結合よりもコストがかからない場合があります。

診断質問としてのSOLID

設計が恩恵を受ける場合にこれらの質問を使用してください。手続き型コードや関数型コードにオブジェクト指向アーキテクチャを押し付けないでください。

  • 単一責任: このユニットは独立して変更される懸念事項を混在させていますか?
  • オープン/クローズド: 仮説的な拡張フレームワークではなく、分離する価値のある実証された変動軸はありますか?
  • リスコフの置換原則: ある実装が、より強い前提条件、弱い保証、または互換性のない障害によって呼び出し元を驚かせることなく、別の実装を置き換えることができますか?
  • インターフェース分離: コンシューマは、使用する能力にのみ依存していますか?
  • 依存性逆転: 安定したポリシーは、変わりやすいI/Oの詳細ではなく、狭い契約に依存すべきですか?関数やパラメータがその接合部を提供できます。クラス階層は必須ではありません。

継承が真の置換可能な関係をモデル化しない場合は、継承よりも合成を優先します。パターン名を目標とするのではなく、言語の慣用的なメカニズムを使用します。

読みやすさと最小驚きの原則

ドメインの意味、単位、所有権を明らかにする名前を選択します。制御フローと副作用を追跡しやすくします。コメントは、根拠、制約、明白でない保証に使用し、明白なステートメントをナレーションするためには使用しません。

具体的な問題を引き起こさない限り、リポジトリの規約に従います。関数のサイズ、パラメータ数、ネストの深さは警告サインであり、普遍的な数値制限ではありません。追加の間接参照は自動的にコードをきれいにするわけではありません。コメントは、コードだけでは説明できない根拠、制約、抽象化を保存できます。コンテキストに応じてその価値を判断し、長さやコメント数のルールを満たすためにコメントを削除したり、凝集したロジックを分割したりしないでください。

依存関係とパフォーマンス

困難で確立された機能、特に暗号化とプロトコルハンドリングには、メンテナンスされた適切なライブラリを再利用します。適合性、セキュリティ、ライセンス、互換性、運用コスト、依存関係の重みを評価します。言語やリポジトリですでに提供されている些細な操作のために依存関係を追加しないでください。

想定される入力サイズに対して、適切なデータ構造とアルゴリズムを選択します。明らかな冗長な作業や無駄な割り当てやコピーを避けます。複雑な最適化の前に、疑わしいボトルネックを測定します。代表的なワークロードをベンチマークし、正確性を保護します。ワークロード、メトリック、ベースライン、ターゲット、停止基準に名前を付けます。実際のユーザーまたはシステムの成果に結びついた測定値を使用し、活動数は使用しません。契約が満たされたか、それ以上の利益が追加された複雑さとメンテナンスに見合わない場合に停止します。契約がレイテンシ、スループット、またはリソース使用のどれを重視するかを決定します。バッチ処理はスループットを向上させる一方で、応答時間を悪化させる可能性があります。スタイル上の単純さのために、明示されたレイテンシやメモリ要件を犠牲にしないでください。例については、複雑さ、インターフェース、パフォーマンスを参照してください。

実践におけるUnix哲学

一つのことをうまく行い、明示的な契約を通じて構成可能な、凝集性の高いコンポーネントを記述します。これは、関数ごとに1プロセス、マイクロサービス、テキストのみのストレージ、またはあらゆる場所でのステートレスを必要としません。明確なAPIを持つ内部ライブラリも同様に構成可能です。

  • メカニズムとポリシーを分離する。 分離が結合を減らす場合、再利用可能な計算をプレゼンテーション、環境、および変化するビジネスの選択から独立させます。
  • 合成のために設計する。 隠れたグローバル状態や不必要なハードコードされたパスを避けます。依存関係と影響を明示的にします。適切な場合、呼び出し元が宛先を選択できるようにします。
  • 検査可能な表現を優先する。 単純なデータ構造と文書化された形式を使用します。テキストは相互運用可能なツールにとって価値があります。バイナリ形式は、忠実性、ボリューム、またはパフォーマンスが要求する場合に有効です。
  • 通常の動作は静かに、失敗は可視的に保つ。 沈黙は、無関係なチャタリングがないことを意味し、結果データや抑制された診断が欠落していることを意味しません。
  • ツールを再利用する。 既存の信頼できる機能を再構築するよりも優先します。スクリプトを意図している場合、自動化は非対話型に保ちます。

インターフェーススタイルは、伝統ではなく、人間と機械のコンシューマによって選択します。関数やライブラリAPI、安定したCLI、またはフィルターは、機械の呼び出し元と反復可能な作業に適しています。人間のタスクには、発見可能性、フィードバック、または直接的な相互作用が必要な場合があります。両方の実際のコンシューマがいる場合は、ドメインロジックをオプションのラッパーから分離し、GUIを必須にせずに動作を共有します。契約を満たす最も単純なスタイルに従います。実際のトレードオフについては、Unixインターフェースと複雑さ、インターフェース、パフォーマンスを参照してください。 CLI、パイプライン、設定設計については、Unixインターフェースを読んでください。複雑さ、インターフェーススタイル、またはパフォーマンスのトレードオフが決定を実質的に形成する場合は、複雑さ、インターフェース、パフォーマンスを読んでください。競合する原則と例については、トレードオフを読んでください。これらの参照は条件付きです。無関係なローカル編集には必須ではありません。 実用的なデバッグ、プロジェクトコマンド、生成されたアーティファクト、メンテナドキュメント、依存関係評価の例については、デバッグとメンテナンスを読んでください。

安全な進化と検証

リファクタリングは、出力、エラー、副作用、コンシューマが依存する契約を含む、観察可能な動作を保持します。リファクタリング中に黙って癖を修正しないでください。意図的な契約変更は、代わりに影響を受けるテストとコンシューマを明示的に更新します。置き換えられた要件のテストは、恒久的な制約ではありません。

パブリック境界を動作重視のテストで保護します。適切なカバレッジを再利用します。重要なパスが保護されていない場合は、回帰テストまたは特性テストを追加します。可能な限り実際の実装または焦点を絞ったフェイクを優先しますが、真にコストがかかる、非決定的、または安全でない境界を分離するためにはテストダブルを使用します。プライベートメソッドの呼び出しや正確なソースの文言に関するアサーションは、それら自体が契約でない限り避けます。

意味のあるエッジケースをチェックします。不正な入力、空のデータ、リソース障害、および該当する場合は並行性や部分的な書き込み。すべての編集に対して任意のカバレッジ率や完全なスイートを規定しないでください。

範囲内で変更しない限り、パブリック互換性を保持します。永続的な契約と永続データについては、コンシューマ、デプロイ順序、移行、リカバリを調査します。古いバージョンと新しいバージョンが共存する必要がある場合は、expand/contractまたは別の段階的アプローチを使用します。それ以外の場合は、調整されたアトミック変更で十分な場合があります。実際の要件なしにリカバリパスを削除したり、互換性シムをインストールしたりしないでください。

最終決定チェック

完了を宣言する前に、次の質問を自問します。

  • 実装は、関連する障害を含む、実際の契約を満たしていますか?
  • すべての抽象化、依存関係、変更されたファイルは、このタスクによって正当化されていますか?
  • 保守担当者は、ルール、その状態の所有者、およびそれを保護する証拠を見つけることができますか?
  • 既存の動作を保持しましたか、あるいは影響を受けるすべてのコンシューマにわたって意図された変更を明示しましたか?
  • 実際に何を検証しましたか、そして何が未検証のままですか?

このチェックは非公開で使用してください。すべての編集に対して定型文のレポートや原則スコアを出力しないでください。

関連スキル