Blog
Eine vorhersehbare Umgebung für Agenten
Unterstützte Arbeit lässt sich für mich leichter beurteilen, wenn die Umgebung ausdrücklich beschrieben ist.
Zufällige Unterschiede verringern
Beginnt dieselbe Aufgabe mit anderen Werkzeugen, Abhängigkeiten oder Annahmen, sind abweichende Ergebnisse schwer zu deuten. Ich bevorzuge einen wiederholbaren Ausgangspunkt: bekannte Werkzeugversionen, deklarierte Abhängigkeiten und einen ausdrücklich beschriebenen Arbeitskontext. Das macht Entscheidungen und Eingaben nicht deterministisch. Es beseitigt aber vermeidbare Ungewissheit darüber, ob ein Unterschied aus der Arbeit oder ihrer Umgebung stammt.
Das Festlegen von Versionen ist die konkrete Form dieser Vorliebe. Versionen stehen in einer Sperrdatei oder einer Entwicklungsumgebung, sodass die Umgebung ein lesbarer Wert ist. Es geht nicht darum, die Welt einzufrieren, sondern ein Update zu einer sichtbaren Änderung zu machen, die wie jede andere geprüft werden kann. Ein nicht festgelegtes Werkzeug aktualisiert sich still und macht jeden Vergleich zum Rätsel.
Der Arbeitskontext verdient dieselbe Behandlung. Welches Verzeichnis im Umfang liegt, welche Variablen gesetzt sind, ob die Aufgabe das Netzwerk erreichen darf: Das sind Bedingungen der Arbeit, und sie sollten vor dem Beginn benannt sein. Bleiben sie implizit, trägt ein Ergebnis verborgene Annahmen, die später niemand prüfen kann.
{
description = "Pinned tools for repeatable local work";
inputs.nixpkgs.url = "github:NixOS/nixpkgs/nixos-24.11";
outputs = { self, nixpkgs }:
let
system = "x86_64-linux";
pkgs = nixpkgs.legacyPackages.${system};
in {
devShells.${system}.default = pkgs.mkShell {
packages = [
pkgs.nodejs_22
pkgs.bun
pkgs.jq
pkgs.ripgrep
];
};
};
}Dauerhafte Regeln dauerhaft ablegen
Ich trenne beständige Anleitung vom Kontext einer einzelnen Aufgabe. Langfristige Hinweise sollten stabile Grenzen und Prüfroutinen beschreiben; die Anfrage liefert Ziel, Umfang und besondere Einschränkungen. Verstecke ich eine dauerhafte Regel in einem einmaligen Gespräch, kann sie beim nächsten Versuch fehlen. Mache ich jede vorübergehende Vorliebe zur festen Regel, wird die Anleitung unübersichtlich. Entscheidend ist, ob jemand bei einem Neustart die weiterhin geltenden Regeln findet.
Ich frage, was ein Neustart wissen müsste. Grenzen, die immer gelten, die Befehle, die eine Änderung prüfen, und die Gewohnheiten, die Arbeit nachvollziehbar halten, gehören in dauerhafte Anleitung. Das aktuelle Ziel, die betroffenen Dateien und Ausnahmen gehören zur Anfrage. Vermischt man beides, erbt die nächste Aufgabe die Einschränkungen von gestern.
Anleitung braucht auch Pflege. Regeln sammeln sich, und eine alte Vorliebe, die nicht mehr zum Projekt passt, wird zu Rauschen, das die weiterhin wichtigen Regeln verdeckt. Ich lese die dauerhaften Notizen neu, wenn sich die Arbeit verändert, und entferne, was nicht mehr stimmt, denn eine veraltete Regel ist schlechter als keine.
{
"version": 1,
"checks": [
{
"name": "typecheck",
"argv": ["bun", "run", "typecheck"],
"profiles": ["fast"]
},
{
"name": "build",
"argv": ["bun", "run", "build"],
"profiles": ["full"]
}
]
}Die Übergabe prüfen
Ich würde die dokumentierte Einrichtung aus einem frischen Ausgangszustand versuchen und nachsehen, ob dieselben Werkzeuge, Abhängigkeiten und dauerhaften Hinweise ohne mein früheres Gespräch verfügbar sind. Eine wiederholbare Umgebung bescheinigt keiner Entscheidung Qualität; sie macht die Bedingungen hinter der Entscheidung leichter nachvollziehbar. Hängt ein Schritt von unausgesprochenem lokalem Wissen ab, würde ich die Abhängigkeit festhalten oder entfernen, bevor ich auf wiederholte Ausführung vertraue.
Meine Prüfung ist bewusst langweilig: aus einem frischen Checkout starten, die dokumentierte Einrichtung ausführen und danach die deklarierten schnellen Prüfungen laufen lassen. Braucht ein Schritt etwas, das ich vor Wochen eingerichtet und nie aufgeschrieben habe, scheitert die Wiederholung und ich habe die Lücke gefunden. Gelingt sie, weiß ich nur, dass die Umgebung wiederholbar ist, nicht dass die Arbeit gut ist.
Dieselbe Prüfung gilt für die dauerhaften Regeln. Ich stelle mir jemanden vor, der heute zur Arbeit stößt, und frage, ob diese Person die Grenzen und Prüfgewohnheiten ohne meine alten Gespräche finden könnte. Was sie nicht finden könnte, wird entweder dokumentiert oder entfernt.
#!/usr/bin/env bash
set -euo pipefail
# Run from a fresh checkout: nothing from an earlier session may help.
tmp="$(mktemp -d)"
trap 'rm -rf "$tmp"' EXIT
git clone --depth 1 "$1" "$tmp/work"
cd "$tmp/work"
nix develop --command ./scripts/check.sh --fast