unix-software-design

目的

模块边界、インターフェース設計、複雑さのトレードオフを検討する際に、Unix 哲学に基づく設計原則を参考として提示し、よりシンプルで透明性が高く、組み合わせやすい判断を支援します。

適用シーン

• 新しいモジュールやサービスの境界を設計するとき
• リファクタリング時に分割方法やインターフェースを計画するとき
• 複雑さのトレードオフや抽象化のレベルについて議論するとき

適用しないケース

• 実装だけのタスクで、主な問題が設計ではなくコードを書くことにある場合
• 既存のツールやフレームワークを選ぶだけで、システムの境界や構造が関係しない場合
• タスクの主眼が「新規着手／保守の推進／プロジェクトを読み解いて要点をまとめる」といった進め方や成果物の構成にある場合は、spark を使ってください。このスキルは境界と原則に焦点を当てており、作業方法の契約に代わるものではありません。

使用方法

1. 原則を誤った問題に当てはめないよう、現在の設計目標、制約、非目標をまず言い換えて確認します。
2. 実際の設計の軸を特定します。モジュール境界、データ表現、インターフェースプロトコル、状態の所有者、エラー処理、拡張ポイント、デプロイ／運用の境界などです。
3. 判断に最も関連する原則を 2～4 個だけ選びます。すべての原則を一つずつ列挙しないでください。
4. 最小限の実用的な設計を提示します。明確なデータフローと交換可能な小さな部品を優先し、まだ導入しない複雑さについても説明します。
5. 複数の案がある場合は、簡潔な表でトレードオフを比較し、推奨案と後戻りにかかるコストを明示します。

出力の好み

• 抽象的な格言より、実行可能な設計上の提案を優先します。
• 「今やること／当面やらないこと／どのような兆候が現れたら後で拡張するか」を明確にします。
• 複雑な案については、それが実際に解決する問題を説明します。問題がまだ発生していないなら、導入を先延ばしにする方向で考えます。
• 可観測性を維持します。ログ、テキスト形式の状態、dry-run、検査コマンド、小規模な診断用エントリーポイントなどを提案します。

モジュール化の原則

• Rule of Modularity：シンプルな部品を作り、明確なインターフェースで接続します。
• Rule of Composition：ほかのプログラムと連携できるようにプログラムを設計します。
• Rule of Separation：ポリシーとメカニズムを分離し、インターフェースとエンジンを分離します。

シンプルさの原則

• Rule of Clarity：巧妙さより明快さを優先します。
• Rule of Simplicity：シンプルさを重視して設計し、必要な場合にのみ複雑さを加えます。
• Rule of Parsimony：ほかに方法がないことが明確に証明された場合にのみ、大規模なプログラムを書きます。
• Rule of Extensibility：将来を見越して設計します。将来は想像より早く訪れるからです。

堅牢性の原則

• Rule of Transparency：検査やデバッグが容易になるよう、可視性を重視して設計します。
• Rule of Robustness：堅牢性は透明性とシンプルさから生まれます。
• Rule of Representation：知識をデータに組み込み、プログラムのロジックをよりシンプルで堅牢にします。
• Rule of Least Surprise：インターフェース設計では、常に最も意外性の少ない動作を選びます。
• Rule of Silence：プログラムに伝えることがないときは、何も出力しないようにします。
• Rule of Repair：失敗せざるを得ない場合は、できるだけ早く、明確に失敗させます。

効率の原則

• Rule of Economy：プログラマーの時間は貴重です。マシンの時間より、プログラマーの時間を節約することを優先します。
• Rule of Generation：コードを手書きするのは避け、コード生成ツール（protobuf、SQLAlchemy、cargo-generate など）で繰り返し作業を置き換えます。
• Rule of Optimization：最適化より先にプロトタイプを作ります。まず動作させ、profiling ツールでボトルネックを特定してから最適化します。

多様性の原則

• Rule of Diversity：「唯一の正しい方法」というあらゆる主張を疑います。

補足原則

• 可能な限り、データフローをテキスト形式に設計します（標準ツールで表示やフィルタリングがしやすくなります）。
• データベースのレイアウト、設定、アプリケーションプロトコルには、性能または互換性の要件がバイナリ形式を明確に求める場合を除き、人間が読みやすく diff しやすい形式（JSON/YAML/TOML など）を優先します。
• 複雑なフロントエンド（ユーザーインターフェース）は、複雑なバックエンドから明確に分離します。
• ポリシーとメカニズムを分離します。中核となるメカニズムは小さく安定させ、ポリシーは設定、ルール、または交換可能なモジュールに置きます。
• データ構造、schema、状態機械、宣言的な設定に知識を組み込み、処理コードに散在する暗黙のルールを減らします。
• 入力には寛容に、出力には厳格にします。出力は安定しており、解析・テスト可能であるべきです。
• フィルタリング時は、不要な情報もできる限り破棄しないようにします。元の入力を保持するか、追跡可能な経路を用意します。
• 小さいことは美しいことです。タスクの達成に必要なことだけを、できる限り少ないプログラムで実現します。
• 技術スタック、コンテナ化、CI/CD などのエンジニアリング上の提案は、モジュール境界、組み合わせやすさ、再現性に影響する場合にのみ行います。これらをデフォルトの答えにしないでください。