sunao1222/agent-skills

Nix-Entwicklungsumgebungen

Erstellen und verwalten Sie Projektentwicklungsumgebungen mit Nix Flakes, nixpkgs unstable, devenv und direnv. Halten Sie die öffentliche Schnittstelle des Flakes klein und platzieren Sie shellspezifische Details in separaten Nix-Dateien.

Interaktionsvertrag

Behandeln Sie die Nix-Konfiguration als ausführbare Projektrichtlinie. Ändern oder aktivieren Sie sie nicht implizit.

1. Untersuchen Sie das Repository und erklären Sie zuerst die vorgeschlagenen Änderungen.
2. Fragen Sie nach einer expliziten Genehmigung, bevor Sie Dateien erstellen, bearbeiten, umbenennen oder löschen. Fassen Sie zusammenhängende Bearbeitungen in einer klaren Anfrage zusammen.
3. Nachdem die Bearbeitungen genehmigt und abgeschlossen sind, schlagen Sie Validierungsbefehle vor und fragen Sie vor der Ausführung eines dieser Befehle nach einer separaten Genehmigung.
4. Führen Sie direnv allow nicht aus, ohne es namentlich zu nennen und eine Genehmigung einzuholen. Es autorisiert die automatische Auswertung der Projektkonfiguration.

Wenn der Benutzer eine der Genehmigungen ablehnt, geben Sie nur den Plan oder die Befehle an und halten Sie an dieser Grenze an.

Standardwerte und Geltungsbereich

• Für neue Arbeiten ist ein Flake erforderlich. Verwenden Sie nixpkgs/nixos-unstable, es sei denn, das Projekt hat bereits eine andere Version festgelegt und der Benutzer bittet um eine Änderung.
• Unterstützen Sie alle Sprachen. Fügen Sie Sprachpakete, Formatierungswerkzeuge, Linter, Dienste und Umgebungsvariablen nur dann hinzu, wenn das Projekt sie benötigt.
• Bevorzugen Sie nix develop und devShells.<system>.default als portable Schnittstelle.
• Verwenden Sie devenv für seine deklarativen Module, Dienste, Skripte, Tests und Git-Hooks, wenn diese Funktionen benötigt werden. Erstellen Sie keine doppelten Definitionen sowohl in einem rohen mkShell als auch in devenv, ohne zu erklären, welche maßgeblich ist.
• Integrieren Sie direnv über eine eingecheckte .envrc nur auf Anfrage oder wenn das Projekt es bereits verwendet. Bewahren Sie die lokalen Umgebungseinstellungen eines Benutzers.
• Ersetzen oder löschen Sie niemals eine vorhandene shell.nix, flake.nix, .envrc, devenv.nix, Lockdatei oder CI-Einrichtung, nur weil ein neueres Layout bevorzugt wird.

Prüfen vor dem Vorschlagen von Änderungen

Suchen Sie mindestens nach:

• flake.nix, flake.lock, shell.nix, default.nix und dem nix/-Verzeichnis
• devenv.nix, devenv.yaml und .envrc
• Sprachmanifesten und Lockdateien, Formatierungs-/Linter-Konfiguration, Aufgabenverwaltungstools und CI-Workflows
• Projektdokumentation, die Einrichtungsbefehle oder unterstützte Plattformen erwähnt

Lesen Sie die vorhandenen Nix-Ausdrücke, bevor Sie ein Layout vorschlagen. Stellen Sie fest, ob das Projekt bereits einen Flake hat, welche Systeme es unterstützt, wie Abhängigkeiten festgelegt sind, ob devenv installiert oder konfiguriert ist und ob direnv absichtlich ausgeschlossen ist.

Wenn ein Befehl für die Erkundung nützlich ist, bevorzugen Sie schreibgeschützte Befehle wie nix flake metadata oder nix flake show. Fragen Sie um Erlaubnis, bevor Sie sie ausführen, wenn die Befehlsausführung nicht bereits vom Benutzer genehmigt wurde.

Dateilayout

Schlagen Sie für ein neues oder leicht konfiguriertes Repository dieses Layout vor, es sei denn, die etablierte Konvention des Repositorys ist besser:

.
├── flake.nix
├── flake.lock
├── devenv.nix              # devenv-spezifische Module und Dienste, falls verwendet
├── .envrc                  # direnv Einstiegspunkt, falls verwendet
└── nix/
    └── devshell.nix        # Pakete, Variablen und Shell-Hooks

flake.nix sollte Inputs, die grundlegende Unterstützung von Systemen und exportierte Outputs enthalten. Platzieren Sie mkShell-Argumente, Paketlisten, Umgebungsvariablen und Shell-Hooks in nix/devshell.nix. Verwenden Sie weitere fokussierte Dateien unter nix/, wenn die Shell erheblich wächst, z. B. nix/packages.nix oder nix/hooks.nix.

Verwenden Sie für neue Einrichtungen kein shell.nix. Wenn bereits eines vorhanden ist, behalten Sie es, es sei denn, der Benutzer genehmigt explizit einen Migrationsplan. Erklären Sie während einer Migration die Kompatibilitätsauswirkungen für Benutzer, die weiterhin nix-shell ausführen.

Design-Workflow

1. Aktuelle Situation darlegen

Fassen Sie relevante vorhandene Dateien, erkannte Projektwerkzeuge und etwaige Unklarheiten zusammen. Wenn die Anforderungen unvollständig sind, stellen Sie gezielte Fragen, wie z. B.:

• Welche Plattformen müssen unterstützt werden (z. B. nur Linux oder Linux und macOS)?
• Welche Projektbefehle sollten innerhalb der Shell funktionieren?
• Werden Datenbank- oder andere lokale Dienste benötigt?
• Soll devenv die Umgebung verwalten, oder soll es Funktionen um eine devShell herum hinzufügen?

2. Implementierung vorschlagen

Beschreiben Sie genau, welche Dateien hinzugefügt oder geändert werden und warum. Geben Sie an, ob sich flake.lock ändert, ob .envrc erstellt oder bearbeitet wird und welche Quelle für jede Abhängigkeit verantwortlich ist.

Verwenden Sie für einen neuen Allzweck-Flake eine explizite Strategie für unterstützte Systeme und machen Sie devShells.<system>.default verfügbar. Importieren Sie den separaten Shell-Ausdruck, anstatt den gesamten mkShell-Rumpf in flake.nix zu platzieren. Halten Sie die anfängliche Paketmenge minimal: Fügen Sie keine willkürlichen Sprach-Toolchains hinzu, nur damit die Vorlage vollständig erscheint.

Wenn der Benutzer devenv anfordert, wählen Sie eine Integration, die mit der installierten/versionsfestgelegten devenv-Einrichtung kompatibel ist. Halten Sie devenv-Deklarationen in devenv.nix (oder fokussierten Dateien, die es importiert). Machen Sie deutlich, ob Benutzer mit nix develop, devenv shell oder beidem eintreten, und stellen Sie sicher, dass dokumentierte Einstiegspunkte nicht stillschweigend auseinanderdriften.

Verwenden Sie für direnv die vorhandene Konvention des Projekts. Eine flake-basierte .envrc verlässt sich im Allgemeinen auf die nix-direnv-Unterstützung; eine devenv-basierte .envrc verlässt sich auf die entsprechende devenv-Integration. Schreiben Sie keinen Einstiegspunkt, dessen erforderliche direnv-Erweiterung nicht identifiziert wurde.

Behandeln Sie diese als separate Fakten: ob nix-direnv installiert ist, ob es in das direnv dieses Benutzers integriert ist und ob die .envrc dieses Projekts erfolgreich ausgewertet wird. Verwenden Sie direnv stdlib (oder das Fehlen von use flake in seiner Ausgabe) nicht als Installationsprüfung: Sie spiegelt die Standardbibliothek wider, die für diesen Aufruf verfügbar ist, und ist nicht maßgeblich für die deklarative NixOS- oder Home-Manager-Konfiguration. Insbesondere ist ein leeres direnv stdlib | grep -F 'use flake'-Ergebnis kein Beweis dafür, dass nix-direnv fehlt.

Wenn die Erkundung genehmigt wurde, überprüfen Sie die relevanten Beweise, ohne zu übertreiben, was sie beweisen:

• Suchen Sie unter NixOS oder mit verfügbarer Home-Manager-Konfiguration nach programs.direnv.enable = true und programs.direnv.nix-direnv.enable = true (oder der entsprechenden Modulkonfiguration). Melden Sie dies als deklarative Konfiguration, nicht als Beweis dafür, dass die aktive Shell sie geladen hat.
• Überprüfen Sie, ob nix-direnv und direnv in der aktuellen Umgebung verfügbar sind, und untersuchen Sie die anwendbare direnvrc oder generierte direnv-Konfiguration, wenn darauf zugegriffen werden kann. Melden Sie ein nicht verfügbares ausführbares Programm oder eine fehlende Integrationsdatei als Beobachtung der aktuellen Umgebung, nicht als Behauptung über die deklarative Konfiguration des Benutzers.
• Lesen Sie die .envrc des Projekts, um die erforderliche Erweiterung zu identifizieren. Verwenden Sie direnv status, um den aktuellen Autorisierungs-/Ladezustand zu überprüfen. Ziehen Sie nicht den Schluss, dass ein use flake-Einstiegspunkt funktioniert, bis er in diesem Projekt ausgewertet wurde.

Nur nach expliziter Genehmigung autorisieren und testen Sie eine .envrc des Projekts. Weisen Sie darauf hin, dass direnv allow den Vertrauenszustand ändert; führen Sie danach direnv reload oder direnv exec . <harmloser-befehl> aus, um die Konfiguration zu testen. Wenn eine Auswertung nicht durchgeführt werden kann, sagen Sie, dass die Integration unbestätigt ist, anstatt zu erklären, dass nix-direnv nicht installiert ist.

3. Genehmigung für Bearbeitung einholen

Verwenden Sie eine präzise Bestätigungsanfrage ähnlich wie:

Ich werde nix/devshell.nix hinzufügen, flake.nix aktualisieren, um die Standard-Dev-Shell zu exportieren, devenv.nix und .envrc hinzufügen/aktualisieren und flake.lock generieren/aktualisieren, wenn die Abhängigkeitsauflösung dies erfordert. Darf ich diese Änderungen vornehmen?

Warten Sie auf eine zustimmende Antwort. Wenn die vorgeschlagene Arbeit vom genehmigten Plan abweicht, fragen Sie erneut, bevor Sie die zusätzlichen Änderungen vornehmen.

4. Sorgfältig bearbeiten

Bewahren Sie die Formatierung und lokalen Namenskonventionen. Halten Sie Kommentare auf nicht offensichtliche Einschränkungen fokussiert, anstatt die Nix-Syntax zu wiederholen. Fixieren Sie Flake-Inputs durch flake.lock; ersetzen Sie keine Lockdatei durch schwebende URLs.

Wenn Sie ein Shell-Paket hinzufügen, bevorzugen Sie das Paket, das von den festgelegten pkgs des Projekts bereitgestellt wird. Vermeiden Sie unfreie Pakete, Zulassungen für unsichere Pakete, Binär-Caches oder Substituter-Konfiguration, es sei denn, der Benutzer fordert und genehmigt dies ausdrücklich.

5. Validierung vorschlagen und separate Genehmigung einholen

Listen Sie nach den Bearbeitungen nur relevante Befehle auf, erklären Sie deren Zweck und fordern Sie eine Genehmigung an. Wählen Sie aus:

nix flake check
nix flake show
nix develop --command <projekt-check-oder-tool-version-befehl>
devenv test
devenv shell -- <projekt-check-oder-tool-version-befehl>
direnv allow

Verwenden Sie nach Möglichkeit einen harmlosen Befehl für die Shell-Eingangsüberprüfung, wie z. B. --version eines erforderlichen Tools oder den Prüfmodus eines Projekt-Formatierungswerkzeugs. Erklären Sie den erwarteten Netzwerkzugriff, Builds, Downloads oder Lockdatei-Aktualisierungen, bevor Sie Befehle ausführen, die diese verursachen können. Führen Sie niemals nix flake update, breite Garbage Collection, Store-Löschung oder profiländernde Befehle aus, es sei denn, der Benutzer fordert dies ausdrücklich an.

6. Ergebnis melden

Geben Sie die geänderten Dateien, den/die Einstiegsbefehl(e), die Validierungsergebnisse und alle verbleibenden manuellen Schritte an. Identifizieren Sie z. B., ob der Benutzer nach Überprüfung der .envrc nix develop, devenv shell und/oder direnv allow ausführen sollte.

Prinzipien der Fehlerbehebung

• Reproduzieren und untersuchen Sie den tatsächlichen Fehler, bevor Sie Pins ändern oder Overrides hinzufügen.
• Unterscheiden Sie zwischen Evaluierungsfehlern, fehlenden Attributen, Plattformunterstützungsproblemen, Build-Fehlern und Laufzeitabhängigkeitsproblemen.
• Überprüfen Sie den festgelegten Input und das Paketattribut, bevor Sie annehmen, dass ein instabiles Paket existiert oder den erwarteten Namen hat.
• Bevorzugen Sie eine kleine, dokumentierte Korrektur gegenüber globalen Nix-Konfigurationsänderungen.
• Wenn eine Änderung die Reproduzierbarkeit oder alle Mitwirkenden beeinflussen kann, präsentieren Sie Alternativen und fordern Sie eine Genehmigung an, bevor Sie sie bearbeiten.

Abschlusskriterien

Betrachten Sie die Aufgabe nur dann als abgeschlossen, wenn die Konfiguration modular ist, der deklarierte Einstiegspunkt in der endgültigen Antwort dokumentiert ist, angeforderte Prüfungen entweder bestanden haben oder deren Ergebnis klar gemeldet wurde und jeder Bearbeitungs- und Validierungsbefehl durch die erforderliche Genehmigung vorbereitet wurde.