共有ワークツリーで、ほかの作業を壊さずに、どのOSでも動くCLIを作る

## 今のワークツリーの中だけで、探して直す 開発でワークツリーを使う場合、現在の作業ディレクトリがアクティブなブランチの完全なリポジトリになる。検索、読み取り、ビルド、テスト、編集は、そのルート内だけで行う。 - 相対パス、または現在のルート配下へ解決されたパスを使う。 - 親ディレクトリをリポジトリだと想定しない。 - 実装や設定を探すために、同階層の別ワークツリーを検索しない。 - 開発者のホームディレクトリをハードコードしたパスは受け入れない。 - フィクスチャとソースのパスは、アクティブなルートから解決する。 ワークツリーの外へ出ると、別ブランチの古いコードが分析や変更へ混入する可能性がある。 ## ほかのセッションの変更を、リセットなどで消さない 見慣れないファイルや編集は、別の稼働中セッションが所有している可能性があると考える。現在のタスク範囲外という理由だけで、作業を消去、リセット、破棄、上書きしてはならない。 - 自分が作成していないファイルを保持する。 - 未追跡ファイルを取り除く前に確認する。 - 明示的な承認なしに、リセット、チェックアウトによる破棄、クリーン、スタッシュ破棄を実行しない。 - 触れていないファイルが原因でフックに失敗した場合、そのファイルを変更せず競合を報告する。 - 変更を依頼範囲に限定し、最終差分を確認する。 共有ワークツリーの状態はユーザーデータとして扱い、破壊的操作の前に所有者を特定する。 ## コマンドは、条件分岐を散らさずレジストリで足す コマンド、プロバイダー、統合を拡張可能にするため、レジストリを使う。新しい実装は安定したインターフェースを満たし、アプリケーション全体へ条件分岐を追加するのではなく、単一の正規登録経路を通す。 - 主要な振る舞いにインターフェースを定義する。 - コンストラクタまたはフィールドを通じて依存関係を注入する。 - リポジトリが対応する生成器でモックを生成する。 - デフォルト値を持つ拡張可能な設定には、関数型オプションを使う。 - 焦点を絞った各ファイルに、コマンド実装を一件ずつ置く。 - 汎用ユーティリティパッケージを肥大化させず、目的別パッケージを追加する。 並行するロジックを導入する前に、既存のコマンド層、実行層、パッケージ層を検索する。 ## コンテキストの使い道を絞り、フラグは1つのパーサーを通す リクエストコンテキストは、キャンセル、期限、少数のリクエスト単位の値にだけ使う。受け取る場合は先頭の引数にする。設定、依存関係、通常の引数を隠すためにコンテキストを使わない。 設定を決定的なパイプラインとしてモデル化する。 1. 設定ソースを読み込む。 2. インポートと継承を処理する。 3. コマンドフラグ、環境、ファイル、デフォルトの順で優先順位を適用する。 4. 対応するテンプレートをレンダリングする。 5. 有効な設定を生成する。 フラグと環境のバインドは、統一パーサーを通す。オプションを追加する時は所有する全スキーマを更新し、中央のバインド層を決して迂回しない。 ## パイプで渡すデータと人向けの表示を、別の出力先に分ける パイプ可能な結果はデータストリームだけへ書く。プロンプト、進捗、警告、整形済みの人向けメッセージはインターフェースストリームへ書く。構造化ログは、ユーザー向け出力ではなくシステムイベントだけに使う。 - 直接表示する代わりに、共有I/O抽象化を使う。 - 色、アイコン、Markdown、端末幅、機能検出はUI層に任せる。 - 端末が装飾に対応しない場合や、継続的インテグレーションで実行する場合は自動的に簡素化する。 - 人向けの整形を無効にしても、構造化データの妥当性を保つ。 - 機密情報のマスキングを一貫して適用し、テレメトリへユーザーデータを取り込まない。 テスト用または記録用のフラグで端末特性を強制してもよいが、本番のデフォルトは環境を認識したままにする。 ## 関数を小さく保ち、エラーを決まった分類で包む ファイルと関数の責務を絞る。複雑度の高いオーケストレーションから名前付きの手順を抽出し、最上位関数を平坦なパイプラインとして読めるようにする。 - リポジトリ標準の整形、インポートのグループ化、別名、コメントの句読点規則を使う。 - 有用なコメントを保持し、振る舞いが変わった時はコメントも更新する。 - 意味のある公開操作へ標準の性能計測を適用する。 - ポリシーが認める場合、単純なアクセサー、コンストラクタ、純粋な検索、単純な委譲は対象外にする。 - 安定した分類でエラーをラップし、原因を保持する。 - 独立した複数の失敗を、どのエラーチェーンも失わずに結合する。 - ラップされたエラーは、文字列比較ではなく意味に基づいて照合する。 ユーザーにヒント、コンテキスト、終了状態を示す必要がある場合は、情報量の多いエラービルダーを使う。 ## モックを使い、本当に失敗できるテストで振る舞いを確かめる 分離された振る舞いには、生成済みモックを使う高速な単体テストを優先する。その後、外部向けコマンドの振る舞いが実際の境界をまたぐ箇所へ、統合テストまたは受け入れテストを追加する。 - 入力とエラーの網羅にはテーブル駆動テストを使う。 - 内部実装ではなく振る舞いをテストする。 - スタブ、同語反復的なテスト、恒久的にスキップされるテストを取り除く。 - 結合済みコレクションでは、結果側とソース側を別々の検査で変更し、双方向の分離性を証明する。 - スライスの結果では、長さだけでなく代表的な内容も表明する。 - 条件が存在しない時に復旧処理が発動しないことを証明する否定側テストを追加する。 - ラップされた失敗には、意味に基づくエラー照合を使う。 表明が保護対象の振る舞いに対して失敗できる場合にだけ、カバレッジは証拠になる。 ## どのOSでも動き、準備が欠けたらはっきり失敗するテストを書く テストは、シェル、パス区切り、プラットフォーム固有のユーティリティを前提にせず、対応するデスクトップとサーバーの各環境で動かなければならない。 - 標準パスライブラリを使い、個別の構成要素からパスを組み立てる。 - 移植可能な接尾辞比較または表示のためにだけ、区切り文字を正規化する。 - プラットフォーム固有コマンドの代わりに、テスト実行ファイルまたは注入したランナーを使う。 - 重複する入口を定義せず、サブプロセス用ゲートを既存のテスト入口へ統合する。 - フィクスチャのルートは、走査または件数確認の前に絶対パスへ解決する。 - 前提条件とフィクスチャ件数のガードは、設定が欠けている時に明確に失敗させる。 - 名前変更によってテストをコンパイルエラーにすべきスキーマフィールドには、コンパイル時センチネルを追加する。 依存するサブプロセスの振る舞いをテストする前に、暗黙の環境伝播を明示的な前提サブテストで検証する。 ## スナップショットは手で直さず、テストの仕組みで作り直す ゴールデンスナップショットには、不可視の書式、端末幅、装飾、環境依存の出力が含まれる。手作業で編集してはならない。 - 対応するテストフラグまたは生成器を通じてスナップショットを再生成する。 - 受け入れる前に生成された差分を確認する。 - リダイレクトで機能検出が変わる可能性があるため、スナップショットや端末のテストをパイプしない。 - コマンドのヘルプまたは出力が変わった時は、関連する記録をまとめて再生成する。 - コマンド失敗、参照欠落、機械固有パスの漏出がないか記録を検証する。 - 明示的な作業範囲なしに、保護対象のフィクスチャやテストデータを変更しない。 生成物は、所有元のソースと正規ワークフローを通じて変更する。 ## 新しいコマンドに文書を付け、先送りする作業は課題として残す 新しいコマンド、フラグ、パラメータ、設定面には、リポジトリが求めるメタデータ、使用法、例、引数、フラグ、視覚的証拠を含むユーザー文書が必要になる。 - ファイル名からURLを推測せず、宣言されたページ識別子を確認する。 - 変更後に文書サイトをビルドし、リンク、画像、コンポーネントを確認する。 - 文章だけの編集ではなく、コマンドの振る舞い、ヘルプ、出力が変わった時に視覚的記録を再生成する。 - 要件文書を指定された場所と命名規則に従って置く。 - 作業を先送りする場合は、マージ前に追跡対象の課題を作成し、その識別子をリンクする。 - リリースノート、ロードマップデータ、ラベルを変更区分に合わせる。 追跡されていない後続作業を約束する文書は未完成である。 ## フックを飛ばさず、壊すGitコマンドを使わずにレビューを進める リポジトリのレビューワークフローを使い、永続サービスが明示的に承認されていない限り、反復する保守自動化はセッション内に限定する。 - 承認済みのブランチ手順だけでリベースまたは更新する。 - 継続的インテグレーションを確認し、未解決のレビュースレッドへ対応する。 - 元のレビュースレッド内で返信し、関連付けを確認する。 - レビューを更新する前に、パッチ範囲のlintとテストカバレッジを実行する。 - フックを迂回したり、検証を無効にするフラグを使ったりしない。 - 下書きメモ、調査資料、未解決のプレースホルダーをコミットしない。 失われる内容について明示的な確認を得ずに、破壊的なGitコマンドを実行したり、別セッションの作業を取り除いたりしてはならない。 ## バグは先に再現テストを書き、通らないチェックは原因から直す バグには、まず再現テストを書いて失敗を観察し、最小の修正を実装して回帰がないか確認する。 完了前に次を確認する。 - プロジェクトが固定済みツールチェーンでコンパイルできる。 - 変更ファイルが正規フォーマッターとlintを通過する。 - 短時間テストが通過し、影響経路で必要な場合は完全テストまたは受け入れテストも実行されている。 - 見せかけの表明に頼らず、カバレッジが強制しきい値を満たす。 - 生成済みモック、スキーマ、スナップショット、文書、視覚的記録が最新である。 - 複雑度とファイルサイズの上限を満たしている。 - クロスプラットフォームのパスとサブプロセステストに移植性がある。 - 機密情報、ユーザーデータ、無関係な作業が差分へ混入していない。 失敗したゲートを弱めず、すべての原因を修正する。