sunao1222/agent-skills

Nix 開発環境

Nix Flakes、nixpkgs unstable、devenv、direnvを使ってプロジェクトの開発環境を作成し、維持します。Flakeの公開インターフェースは小さく保ち、シェル固有の詳細は別のNixファイルに配置してください。

インタラクション契約

Nix設定を実行可能なプロジェクトポリシーとして扱ってください。暗黙的に変更したり、アクティベーションしたりしないでください。

1. リポジトリを検査し、まず提案する変更を説明します。
2. ファイルを作成、編集、名前変更、削除する前に、明示的な承認を1回求めます。関連する編集は1つの明確なリクエストにまとめます。
3. 編集が承認されて完了した後、検証コマンドを提案し、それらを実行する前に別途承認を求めます。
4. 名前を明示して承認を得るまでは、direnv allow を実行しないでください。これはプロジェクト設定の自動評価を許可します。

ユーザーがいずれかの承認を拒否した場合は、計画またはコマンドのみを提供し、その境界で停止します。

デフォルトと範囲

• 新しい作業にはFlakeを必須とします。プロジェクトが既に別のリビジョンを固定しており、ユーザーが変更を依頼しない限り、nixpkgs/nixos-unstable を使用します。
• すべての言語をサポートします。言語パッケージ、フォーマッター、リンター、サービス、環境変数は、プロジェクトで必要な場合にのみ追加します。
• nix develop と devShells.<system>.default をポータブルなインターフェースとして優先します。
• devenv は、その宣言型モジュール、サービス、スクリプト、テスト、Gitフックが必要な場合に使用します。どちらが権威あるかを説明せずに、生の mkShell とdevenvの両方に重複した定義を作成しないでください。
• direnv は、リクエストがあった場合、またはプロジェクトですでに使用されている場合にのみ、チェックインされた .envrc を通じて統合します。ユーザーのローカルのみの環境設定は保持します。
• 新しいレイアウトが好ましいという理由だけで、既存の shell.nix、flake.nix、.envrc、devenv.nix、ロックファイル、CI設定を置き換えたり削除したりしないでください。

変更を提案する前に検査する

少なくとも以下を確認してください：

• flake.nix、flake.lock、shell.nix、default.nix、および nix/ ディレクトリ
• devenv.nix、devenv.yaml、および .envrc
• 言語マニフェストとロックファイル、フォーマッター/リンター設定、タスクランナー、CIワークフロー
• セットアップコマンドやサポートプラットフォームに言及しているプロジェクトドキュメント

レイアウトを提案する前に、既存のNix式を読んでください。プロジェクトに既にFlakeがあるかどうか、どのシステムをサポートしているか、依存関係がどのように固定されているか、devenv がインストールまたは設定されているか、direnv が意図的に除外されているかを判断します。

発見に役立つコマンドがある場合は、nix flake metadata や nix flake show などの読み取り専用コマンドを優先します。ユーザーがまだコマンド実行を承認していない場合は、実行する前に許可を求めてください。

ファイルレイアウト

新規または軽く設定されたリポジトリの場合、リポジトリの確立された慣習がより優れていない限り、以下のレイアウトを提案します：

.
├── flake.nix
├── flake.lock
├── devenv.nix              # devenv固有のモジュールとサービス（使用時）
├── .envrc                  # direnvエントリポイント（使用時）
└── nix/
    └── devshell.nix        # パッケージ、変数、シェルフック

flake.nix には、inputs、サポートされるシステムの配線、エクスポートされるoutputsを含めます。mkShell の引数、パッケージリスト、環境変数、シェルフックは nix/devshell.nix に配置します。シェルが大幅に大きくなった場合は、nix/ の下にさらに焦点を絞ったファイル（例：nix/packages.nix や nix/hooks.nix）を使用します。

新しいセットアップには shell.nix を使用しないでください。既に存在する場合は、ユーザーが明示的に移行計画を承認しない限り保持します。移行中は、まだ nix-shell を実行しているユーザーへの互換性への影響を説明します。

設計ワークフロー

1. 現在の状況を述べる

関連する既存ファイル、検出されたプロジェクトツール、および不確実性を要約します。要件が不完全な場合は、次のような的を絞った質問をします：

• サポートする必要があるプラットフォームはどれですか（例：Linuxのみ、またはLinuxとmacOS）？
• シェル内で動作する必要があるプロジェクトコマンドはどれですか？
• データベースやその他のローカルサービスは必要ですか？
• devenv が環境を所有すべきか、それとも devShell を中心に機能を追加すべきですか？

2. 実装を提案する

どのファイルが追加または変更されるか、そしてその理由を正確に説明します。flake.lock が変更されるかどうか、.envrc が作成または編集されるかどうか、各依存関係をどのソースが所有するかを含めます。

新しい汎用Flakeの場合、明示的なサポートシステム戦略を使用し、devShells.<system>.default を公開します。mkShell 全体を flake.nix に配置するのではなく、別のシェル式をインポートします。初期パッケージセットは最小限に抑えます。テンプレートを完全に見せるためだけに、任意の言語ツールチェーンを追加しないでください。

ユーザーが devenv をリクエストした場合は、インストール/バージョン固定されたdevenv設定と互換性のある統合を選択します。devenv宣言は devenv.nix（またはそれがインポートする焦点を絞ったファイル）に保持します。ユーザーが nix develop、devenv shell、またはその両方で環境に入るのかを明確にし、文書化されたエントリポイントが暗黙的に乖離しないようにします。

direnv については、プロジェクトの既存の慣習を使用します。Flakeベースの .envrc は一般的に nix-direnv サポートに依存します。devenvベースの .envrc は適切なdevenv統合に依存します。必要なdirenv拡張機能が特定されていないエントリポイントを作成しないでください。

これらを別個の事実として扱います：nix-direnv がインストールされているかどうか、このユーザーの direnv と統合されているかどうか、このプロジェクトの .envrc が正常に評価されるかどうか。direnv stdlib（またはその出力に use flake がないこと）をインストールチェックとして使用しないでください。これはその呼び出しで利用可能な標準ライブラリを反映しており、宣言型NixOSやHome Manager設定に対して権威あるものではありません。特に、direnv stdlib | grep -F 'use flake' の結果が空であっても、nix-direnvが存在しないことの証拠にはなりません。

発見が承認されたら、それが何を証明するかを過大評価せずに関連する証拠を検査します：

• NixOS上、またはHome Manager設定が利用可能な場合、programs.direnv.enable = true と programs.direnv.nix-direnv.enable = true（または同等のモジュール設定）を探します。これを宣言型設定として報告し、アクティブなシェルがそれをロードしたことの証明としては報告しません。
• nix-direnv と direnv が現在の環境で利用可能かどうかを確認し、アクセス可能な場合は該当する direnvrc または生成されたdirenv設定を検査します。実行不可能な実行可能ファイルや欠落している統合ファイルは、ユーザーの宣言型設定に関する主張ではなく、現在の環境の観測として報告します。
• プロジェクトの .envrc を読み取り、必要な拡張機能を特定します。direnv status を使用して、その現在の認可/ロード状態を検査します。use flake エントリポイントがそのプロジェクトで評価されるまで、それが機能すると推測しないでください。

明示的な承認があった場合にのみ、プロジェクトの .envrc を認可しテストします。direnv allow が信頼状態を変更することを指摘し、その後 direnv reload または direnv exec . <無害なコマンド> を実行して設定をテストします。評価を実行できない場合は、nix-direnvがインストールされていないと宣言するのではなく、統合が未確認であると述べます。

3. 編集の承認を得る

次のような簡潔な確認リクエストを使用します：

nix/devshell.nix を追加し、flake.nix を更新してデフォルトのdevシェルをエクスポートし、devenv.nix と .envrc を追加/更新し、依存関係の解決に必要な場合は flake.lock を生成/更新します。これらの編集を行ってもよろしいですか？

肯定の回答を待ちます。提案された作業が承認された計画と異なる場合は、追加の編集を行う前に再度質問します。

4. 慎重に編集する

フォーマットとローカルの命名規則を保持します。コメントは、Nix構文を言い換えるのではなく、明白でない制約に焦点を当てます。Flake入力は flake.lock を通じて固定します。ロックファイルの代わりに浮動URLを使用しないでください。

シェルパッケージを追加するときは、プロジェクトの固定された pkgs によって提供されるパッケージを優先します。ユーザーが明示的にリクエストして承認しない限り、非フリーパッケージ、非セキュアパッケージの許可、バイナリキャッシュ、またはsubstituter設定を避けてください。

5. 検証を提案し、別途承認を得る

編集後、関連するコマンドのみをリストし、その目的を説明し、承認をリクエストします。以下から選択します：

nix flake check
nix flake show
nix develop --command <プロジェクトチェックまたはツールバージョンコマンド>
devenv test
devenv shell -- <プロジェクトチェックまたはツールバージョンコマンド>
direnv allow

可能な場合は、シェルエントリ検証に無害なコマンド（例：必要なツールの --version やプロジェクトフォーマッターのチェックモード）を使用します。予想されるネットワークアクセス、ビルド、ダウンロード、ロックファイルの更新について、それらを引き起こす可能性のあるコマンドの前に説明します。ユーザーが明示的に依頼しない限り、nix flake update、広範なガベージコレクション、ストアの削除、プロファイルを変更するコマンドを決して実行しないでください。

6. 結果を報告する

変更されたファイル、エントリコマンド、検証結果、および残っている手動ステップを述べます。例えば、ユーザーが .envrc を確認した後、nix develop、devenv shell、direnv allow のどれを実行すべきかを特定します。

トラブルシューティングの原則

• ピンやオーバーライドを変更する前に、実際のエラーを再現して確認します。
• 評価エラー、属性の欠落、プラットフォームサポートの問題、ビルドエラー、実行時依存関係の問題を区別します。
• 固定された入力とパッケージ属性を確認してから、不安定なパッケージが存在するか、期待された名前であると仮定します。
• グローバルなNix設定の変更よりも、小さく文書化された修正を優先します。
• 変更が再現性やすべてのコントリビューターに影響を与える可能性がある場合は、代替案を提示し、編集前に承認をリクエストします。

完了基準

設定がモジュール化され、宣言されたエントリポイントが最終応答で文書化され、要求されたチェックが合格したか、その結果が明確に報告され、すべての編集と検証コマンドが必要な承認の前に実行された場合にのみ、タスクは完了したと見なします。