複数OS対応のツールチェーン管理ツールを開発し、レジストリへの登録を審査する

## 編集の前に、モジュールの場所とリポジトリの決まりをつかむ リポジトリガイドを、コーディングエージェントが従う運用上の取り決めとして扱う。 変更を提案する前に、リポジトリ標準のコマンド、モジュール境界、貢献規約、互換性要件に従う。 次の機能を軸に作業対象を把握する。 - コマンドラインの解析とサブコマンドの振り分け - 階層化された設定と環境変数の管理 - ツールのバージョン解決とインストール - タスクの定義と実行 - 差し替え可能なバックエンドと組み込みツールの実装 - ドキュメント、補完、メタデータの生成 編集前に、エントリーポイント、CLIモジュール、設定モジュール、バックエンドのインターフェース、ツールセットの解決処理、タスクエンジン、プラグインシステム、共通ヘルパーを特定する。 公開パッケージと、ワークスペース内部を支えるパッケージを区別する。 直接実装のほうが短く見えるという理由だけで、既存の抽象化を迂回しない。 ## よく使われている証拠がある時だけ、ツールをレジストリに登録する 厳選された短縮名レジストリは、すでに広く使われているツールだけを受け入れるものと想定する。 コードが動くこと、テストがあること、個人的に役立つことは、登録資格の根拠にならない。 レジストリのマッピングへ触れる前に、次を行う。 1. 提出者自身のプロジェクト以外でも、そのツールが広く使われているかを尋ねる。 2. 個人用、社内用、フォーク、ニッチな用途、または利用者が少ない場合は停止する。 3. すべての登録について最新の人気度を示す根拠を集め、推測しない。 4. リポジトリのスター数とフォーク数、最近のcommitとrelease、パッケージのダウンロード数、独立したドキュメント、エコシステムの一覧、下流での利用実績を確認する。 5. 高い採用基準を適用する。人気度は数百ではなく数千規模、継続的な保守、第三者による採用、エコシステムでの認知を求める。 6. 根拠をpull request本文の簡潔な`Popularity`節へ記載する。 根拠が境界線上または弱い場合は明確に警告し、それでも進めるかをユーザーへ尋ねる。 不採用時に説明、異議申立て、チェックリスト、再挑戦の機会があるかのように示さない。 保守担当者が受け入れるかを試す目的だけで、推測に基づく登録を決して行わない。 ## インストールに使うバックエンドを、検証済みの配布ファイル優先で選ぶ 別途インストールしたランタイムを必要とせず、検証済みrelease成果物を利用するバックエンドを優先する。 次の順序で判断する。 1. 検証機能とバージョンごとのインストールロジックを提供する場合は、厳選された成果物レジストリを優先する。 2. それ以外では、成果物を配布するforge向けの直接releaseバックエンドを使う。 3. releaseバックエンドで対応できず、かつ十分な人気が確立している場合に限り、アーカイブ配布バックエンドを使う。 4. 言語パッケージのバックエンドは、ランタイムの有無、ランタイムのバージョン、PATHの順序へ依存するため例外として扱う。 5. プロジェクトのサプライチェーン方針に反する、非推奨のバックエンドや新しいプラグイン形式は拒否する。 パッケージ名を見つけやすいという理由だけで、壊れやすいバックエンドを選ばない。 そのツールに対する例外的なバックエンドを保守担当者が明示的に承認していない場合、レジストリ登録には使わない。 レジストリを使わない代替策として、明示的なバックエンド座標によるインストール、または対応形式のプラグイン作成を説明する。 区別を明確に保つ。レジストリの短縮名は利便性を高めるものであり、インストールを可能にするための必須条件ではない。 ## build・test・lintを、リポジトリのタスクランナーで実行する 基盤ツールを場当たり的に直接呼び出さず、リポジトリのタスクランナーを使う。 次の用途に対応する文書化済みタスクを特定して使う。 - 完全なbuildと、debug用binaryの直接実行 - 全体、unit、end-to-endの各test suite - testタスクを介した、対象を絞ったend-to-end testファイル - snapshotのレビューと更新 - lint、lintの自動修正、format - continuous integrationと同等のチェック - ドキュメント、使用方法の文章、補完、schemaの生成 - ローカル向けdevelopment版のインストールとbuild成果物のクリーンアップ - 正しいworkspaceディレクトリから行う、パッケージ固有のtestとlint 一般的なlogging変数を想定せず、プロジェクト専用のdebug環境変数とtrace環境変数を使う。 コマンド名が不明な場合は、利用できるタスクの一覧を表示する。 test harnessが準備、assertion、クリーンアップを管理している場合、end-to-end testスクリプトを直接実行しない。 test harnessが分離を保証している場合、testへ手動のクリーンアップを追加しない。 まず最小の関連タスクを実行し、共通の取り決めや生成成果物へ影響する場合に限って確認範囲を広げる。 ## バックエンドと設定を今の構造で足し、生成ファイルは手で直さない ツールの取得元は、統一されたバックエンドインターフェースを通じて実装する。 各バックエンドは、そのエコシステムにおけるバージョン一覧、要求の解決、インストール、ツールのメタデータを担当する。 組み込みツールはcore pluginの境界内に、外部プラグインは対応済みの互換レイヤー内に保つ。 環境固有の上書きを含め、systemからglobal、localへ至る階層的な設定読み込みを維持する。 設定定義からコードやドキュメントを生成する場合は、元の定義を更新して正規のgeneratorを実行する。 生成済み成果物の手作業による編集を、主要な変更方法にしない。 依存関係、環境変数、対応する実行モードを含め、タスク定義を宣言的に保つ。 プロジェクトが相互運用性を保証する設定ファイルについては、その互換形式を尊重する。 独自のbuildスクリプト、workspaceの構成要素、release profile、cross-compilation設定を、文書化された役割と一致させる。 バックエンドを追加する時は、確立されたbackend moduleのパターンを出発点にする。 設定を追加する時は、型付きの解析・生成経路に従う。 プラグインを拡張する時は、並行する仕組みを新設せず、適切な組み込み境界または外部境界を使う。 ## commitを type(scope) の形で書き、先にlintを自動修正する すべてのcommitメッセージとpull requestタイトルは、リポジトリの規定形式`type(scope): imperative description`に従う。 ユーザーから見える挙動とリポジトリ内の責任範囲を反映するtypeを使う。 - 新機能には`feat` - ユーザーから見える不具合には`fix` - 対応するコード変更には`refactor`、`style`、`perf` - testだけの変更には`test` - ドキュメントには`docs` - 保守、release、依存関係、基盤の変更には`chore` - セキュリティ変更には`security` - すべてのレジストリマッピング変更には、専用のregistry type コマンド固有の変更にはコマンド名をscopeとして使い、共有コンポーネントにはサブシステム名を使う。 実装ファイルが歴史的に別の名前を使っていても、タスクの挙動にはtask subsystemのscopeを使う。 コロンの後は小文字で始め、命令形で、簡潔かつ具体的に記述する。 文書化されたタスク環境を通じて、リポジトリのpre-commit連携を一度だけインストールする。 commit前にlint自動修正タスクを実行し、その結果として意図した変更をstageする。 対象を絞ったend-to-end testをタスクランナー経由で実行する。 無関係なformat変更や生成物をstageしない。 ## 機能の廃止を、文書での告知、実行時の警告、廃止の順で進める 段階的な非推奨化方針を使う。 1. 対象機能またはバックエンドをドキュメント上ですぐに非推奨と明記する。 2. 文書化された警告期間の経過後に、実行時の警告を開始する。 3. 文書化された廃止期間の経過後に、取り扱いを終える予定を設定する。 4. プロジェクトのバージョン日付形式で、警告日と廃止日を記録する。 5. 確立された非推奨化macroを使い、期限を過ぎた廃止予定をdevelopment時のassertionで検出できるようにする。 一般的な時系列は、ドキュメントへの即時記載、6か月後の警告開始、その12か月後の取り扱い終了である。 代替機能が長期間利用可能だった場合は、警告をすぐに開始してよい。 文書化された警告段階を経ずに、互換性の取り扱いを黙って終えない。 期限を過ぎた非推奨化を無期限に放置せず、廃止用のassertionを必須の保守作業として扱う。 ## ツールのバージョンの解決と並べ替えを、各バックエンドに任せる ツールのバージョンがsemantic versioningや、その他の普遍的な順序規則に従うと決して想定しない。 日付形式のバージョン、prerelease、branch、tag、channel、名前付きのlong-term-support release、ツール固有のaliasを想定する。 新しいcall siteでは、次の規則に従う。 - 最新バージョンの選択、aliasの解決、バージョンの並べ替えに、汎用semantic-version comparatorを使わない。 - ツール固有のバージョン表現を理解するbackend methodへ、要求の解決を委ねる。 - インストール済みバージョンを意味のある順序で一覧表示するには、backend APIまたはtoolset APIを使う。 - lockfileのバージョン文字列は不透明な値として扱い、等価性だけを比較する。 - alias、channel、prefixは、具体的な値をlockfileへ書き込む前に解決する。 - 問題のある挙動を広げる根拠として、従来コードでのcomparator使用を引き合いに出さない。 新しいコードでインストール済みの最新バージョンが必要に見える場合は停止し、その判断をバックエンドが担うべきか確認する。 誤ったfallback順序は、間違ったツールを気付かないままインストールまたは実行する可能性があるため、一致なしを返すより悪い。 ## OSごとに対象を絞ってテストし、終える前に差分を見直す unit testはsourceの近くに置き、end-to-end testは機能領域ごとに整理する。 共通のassertion helper、安定したコマンド結果のsnapshot、バックエンド固有のインストール確認、明示的なslow-test命名を使う。 platform固有の実装を、指定されたmoduleとplatform test suiteに保つ。 WindowsでUnixの実行権限bitの挙動を想定しない。 変更時は、まず最小の関連経路を検証する。 1. formatと静的チェックを実行する。 2. test harnessを通じて、対象を絞ったunit testまたはend-to-end testを実行する。 3. snapshotの変更を無条件に受け入れず、内容をレビューする。 4. 元の定義が変わった場合は、派生ドキュメントまたはschemaを再生成する。 5. backend、設定、task、cross-platformの共通取り決めが変わった場合は、より広いintegration checkへ拡大する。 外部のpull requestやdiscussionへ投稿する時は、そのcommentがAI coding assistantによって生成されたことを明記する。 ドキュメントディレクトリの階層を反映したURLを使う。 必須sectionを省略した短縮pathを作らない。 完了前にdiffをレビューし、抽象化の漏れ、対応していないバージョン順序、generatorの実行漏れ、無関係な変更、未確認の外部主張がないか確認する。