planning-with-files

KI-Coding-Agenten haben eine strukturelle Schwäche: Ihr Gedächtnis liegt in einem Context-Window, das gekürzt, zusammengefasst oder komplett gelöscht wird, sobald man einen Befehl wie /clear ausführt. Bei einer langen Aufgabe mit vielen Tool-Calls vergisst ein Agent nach und nach, warum er begonnen hat, was er bereits versucht hat und welche Schritte noch offen sind. Ein Absturz oder ein Context-Reset kann das gesamte mentale Modell einer halb erledigten Aufgabe auslöschen. planning-with-files, ein MIT-lizenziertes Skill des Einzelentwicklers OthmanAdi, geht dieses Problem an, indem es den Planungszustand aus dem flüchtigen Context auf die Festplatte verlagert. Es installiert eine SKILL.md-basierte Harness, die drei persistente Markdown-Dateien pflegt, sodass der Agent sein volles Verständnis der Aufgabe nach jeder Unterbrechung allein durch erneutes Lesen wiederherstellen kann.

Der Mechanismus ist bewusst schlicht gehalten, und genau das ist der Kern. Drei Dateien tragen den Zustand: task_plan.md enthält Phasen, Abhängigkeiten und Fertigstellungsstatus, findings.md speichert Recherche und technische Notizen, und progress.md protokolliert Sessions, Testergebnisse und Fehler. Die Harness spielt diese über SKILL.md-Lifecycle-Hooks zurück in den Context, gebunden an Ereignisse wie UserPromptSubmit, PreToolUse und Stop. Sie läuft in drei Modi. Der Legacy-Modus liest den Plan vor jedem Tool-Call neu, der autonome Modus injiziert nur beim Session-Start und bei Phasenübergängen, um den Overhead für leistungsstarke Modelle zu senken, und der Gated-Modus ergänzt ein Stop-Hook-Abschluss-Gate, das den Agenten am Beenden hindert, solange eine Phase noch offen ist. Es gibt keine Datenbank, keinen Server und nichts zu hosten. Die Dateien sind reiner Text, den man selbst lesen und bearbeiten kann.

Die natürliche Zielgruppe sind alle, die lange, mehrstufige Coding- oder Recherchearbeit in Agenten wie Claude Code, Cursor oder Codex betreiben, wo Context-Limits und Session-Recovery täglich reale Reibung erzeugen. Konkrete Fälle sind mehrphasige Feature-Entwicklungen, langwierige Debugging-Sessions, bei denen frühere Erkenntnisse nicht verloren gehen dürfen, und Rechercheaufgaben über mehrere Sitzungen hinweg. Weil der Zustand nur aus Dateien auf der Festplatte besteht, können mehrere Agenten im Prinzip einen geteilten Plan lesen, was es für lose koordinierte Multi-Agent-Arbeit attraktiv macht. Das Projekt gibt Unterstützung für mehr als 60 Agenten an, mit tieferer Hook-Integration für Tools wie Claude Code, Cursor, GitHub Copilot, Gemini CLI und Codex sowie einem leichteren Agent-Skills-Pfad für andere. Die Installation läuft über einen einzigen npx-Befehl, was die Hürde für einen echten Test senkt.

Die ehrlichen Einschränkungen sollte man ernst nehmen. Dies ist ein Einzelentwickler-Projekt, das in kurzer Zeit eine hohe Anzahl an Stars angesammelt hat, weshalb die übliche Skepsis zur Star-Authentizität gilt, bevor man Popularität als Qualitätssignal wertet. Die Benchmark-Angaben, darunter eine selbst berichtete Bestehensquote von 96,7 Prozent und hohe Rubric-Werte, sind vom Autor in docs/evals.md dokumentiert, aber selbst durchgeführt und nicht unabhängig geprüft, also als Aussagen des Projekts zu lesen. Dateibasierter Zustand ist zudem bei gleichzeitiger Multi-Agent-Nutzung fragil: Es gibt kein Locking, sodass zwei Agenten, die denselben Plan schreiben, sich gegenseitig überschreiben können. Auch praktische Ecken bleiben, etwa eingeschränkte Exec-Bit-Behandlung unter Windows, weil NTFS keine POSIX-Rechte speichert, und eine Session-Recovery, die auf IDE-spezifische Session-Metadaten angewiesen ist.

Die Grunddaten nennen keine direkte kommerzielle Alternative, und das passt zur Realität: Die eigentliche Konkurrenz ist das eingebaute Task- und To-do-Tracking, das Agentenanbieter zunehmend nativ mitliefern. planning-with-files ist eine portable, herstellerneutrale Schicht, die über viele Agenten hinweg gleich funktioniert, und das ist sein Hauptargument gegenüber jedem einzelnen proprietären System. Setzen Sie es ein, wenn Ihre Aufgaben wirklich lang und mehrstufig sind, wenn Sie regelmäßig an Context-Limits stoßen oder nach einem Absturz fortsetzen müssen, und wenn Sie Wert darauf legen, Ihren Plan als bearbeitbaren Text zu besitzen, statt ihn in einem Tool einzusperren. Zu früh ist es für kurze Einzelsitzungsfragen, für Teams, die bereits auf ein agentenintegriertes Task-System standardisiert sind, oder für stark parallele Multi-Agent-Setups, in denen das fehlende File-Locking zum Problem würde. Für den passenden Workflow ist es eine risikoarme, kostengünstige Ergänzung.