Roadmaps erstellen

Eine Roadmap ist ein Plan, den die nächste Person aufnehmen und umsetzen kann, ohne auf das Gespräch angewiesen zu sein, das ihn hervorgebracht hat. Sie sagt, was das Projekt erreichen will, in welcher Reihenfolge, wie jeder weiß, dass ein Teil fertig ist, und welche Fragen noch offen sind. Sie lebt im Repository neben dem Code, den sie beschreibt, und wird daher wie alles andere überprüft und versioniert.

Eine Roadmap hält Entscheidungen fest. Sie trifft sie nicht. Wenn etwas noch nicht entschieden ist, sagt die Roadmap das.

Repo-Regeln haben Vorrang

Bevor Sie etwas schreiben, suchen Sie nach den eigenen Konventionen des Repositorys: AGENTS.md, CLAUDE.md, CONTRIBUTING.md, einem Docs- oder Wiki-Schema und einer vorhandenen Roadmap. Sie entscheiden, wo Roadmaps abgelegt werden, welche Metadaten sie tragen, wie Issues verknüpft werden und welche Prüfungen durchzuführen sind. Wo sie mit dieser Fähigkeit in Konflikt stehen, haben sie Vorrang. Folgen Sie dem Format einer vorhandenen Roadmap, anstatt eine zweite einzuführen.

Arbeitsablauf

1. Die Anforderung klären

Finden Sie heraus, was der Benutzer möchte, denn jede dieser Anforderungen erfordert einen anderen Arbeitsaufwand:

Neue Roadmap: für ein Projekt, eine Funktion, eine Migration, einen Testaufwand usw.
Aktualisieren: Elemente hinzufügen oder ändern, Phasen neu ordnen, eine Entscheidung festhalten.
Abgleichen: Eine vorhandene Roadmap mit dem tatsächlich Ausgelieferten in Einklang bringen.
Überprüfen: Eine Roadmap lesen und Lücken melden, ohne sie umzuschreiben.

2. Beweise sammeln, bevor Sie fragen

Lesen Sie, was das Projekt bereits weiß: den relevanten Code und die Tests, offene und kürzlich geschlossene Issues, zusammengeführte und offene PRs, vorhandene Dokumente und den Commit-Verlauf für den Bereich. Notieren Sie, was heute existiert, was bereits in Arbeit ist und was zuvor versucht wurde.

Alles, was Sie auf diese Weise erfahren können, fragen Sie den Benutzer nicht.

3. Nach den Entscheidungsfragen fragen

Eine Roadmap ist nur so gut wie die Entscheidungen dahinter, und die meisten davon liegen beim Benutzer. Fragen Sie in kurzen Runden statt in einer langen Liste und erklären Sie, warum eine Frage wichtig ist, wenn der Kompromiss nicht offensichtlich ist. Gute Themen:

Ziel: Welches Ergebnis macht diesen Aufwand lohnenswert, und wie wird jemand erkennen, dass es erreicht ist?
Umfang: Was ist explizit ausgeschlossen? Was darf sich nicht ändern (APIs, Datenformate, Verhalten)?
Einschränkungen: Termine, Releases, Personen, Budget, Plattformen.
Prioritäten: Wenn nur die Hälfte davon ausgeliefert wird, welche Hälfte?
Risiko: Was ist am wenigsten verstanden, und sollte es zuerst angegangen werden?
Fertig: Welche Tests, Metriken oder Überprüfungen gelten als Nachweis?

Bieten Sie eine Empfehlung an, wenn die Beweise eine stützen. Lassen Sie den Benutzer immer mit „noch nicht entschieden“ antworten. Diese Antwort kommt in Offene Entscheidungen, nicht in eine Vermutung.

Bei einer kleinen Aktualisierung springen Sie direkt zum Schreiben. Bei einer neuen Roadmap rechnen Sie mit zwei oder drei Runden.

4. Eine Form wählen

Eine Datei (ROADMAP.md oder ein Name, der zum Repository passt) für die meisten Roadmaps.
Ein Verzeichnis (roadmaps/<slug>/README.md plus unterstützende Seiten) nur, wenn der Plan umfangreiches Begleitmaterial benötigt, wie Forschungsnotizen, einen Designentwurf oder Testmatrizen, das die Arbeitspakete begraben würde. Die Hauptseite behält dennoch die Kontrolle über jede Arbeitspaket-ID.

5. Schreiben

Verwenden Sie die Vorlage unten. Regeln, die sie im Laufe der Zeit nützlich halten:

Stabile IDs. Geben Sie jedem Arbeitspaket eine ID wie R-001. Nummerieren Sie nie um und verwenden Sie keine ID erneut. Gestrichene Arbeiten bleiben in der Datei, markiert als dropped, mit Grund.
Phasen haben Abbruchkriterien. Jede Phase sagt, was wahr ist, wenn sie abgeschlossen ist. Ordnen Sie Phasen zuerst nach Abhängigkeiten, dann nach Risiko, dann nach Wert.
Akzeptanzkriterien sind überprüfbar. Schreiben Sie Kriterien, die jemand verifizieren kann: ein Test, der besteht, ein Befehl, der erfolgreich ist, eine messbare Zahl. Vermeiden Sie Wörter wie „robust“, „verbessert“ und „sauber“.
Abhängigkeiten sind explizit. Listen Sie sie nach ID auf. Weisen Sie auf alles hin, das außerhalb der Kontrolle des Teams liegt, wie ein anderes Repository, ein Anbieter oder eine Entscheidung.
Verknüpfen Sie Beweise mit der vollständigen URL oder einem repository-relativen Pfad, damit Links beim Kopieren an andere Orte erhalten bleiben.
Beschreiben Sie den Plan, nicht das Meeting. Präsens, aktueller Stand. Geschichte gehört ins Änderungsprotokoll.

6. Prüfen

Bevor Sie es übergeben:

Jedes Element hat eine ID, einen Status und mindestens ein Akzeptanzkriterium.
Jede Abhängigkeit verweist auf eine vorhandene ID.
Keine Phase hängt von einer späteren Phase ab.
Jede unentschiedene Frage steht unter Offene Entscheidungen, nicht versteckt in einem Element.
Links sind auflösbar und Dateipfade existieren.
Die Formatierungs- und Dokumentationsprüfungen des Repositorys bestehen.
Das Änderungsprotokoll enthält einen Eintrag für diese Änderung.

7. Berichten

Teilen Sie dem Benutzer mit, was Sie erstellt oder geändert haben, welche Entscheidungen Sie festgehalten haben und welche Fragen noch offen sind.

Eine Roadmap mit der Realität abgleichen

Roadmaps driften, während Arbeiten abgeschlossen werden. Um eine abzugleichen:

Listen Sie die Elemente auf, die nicht done oder dropped sind.
Suchen Sie für jedes nach zusammengeführten PRs, geschlossenen Issues und Code, der seine Akzeptanzkriterien erfüllt.
Markieren Sie ein Element nur dann als done, wenn jedes Kriterium erfüllt ist. Verknüpfen Sie den Beweis.
Wenn die Arbeit anders als geplant ausgeliefert wurde, aktualisieren Sie das Element, um zu sagen, was tatsächlich passiert ist, und notieren Sie den Unterschied im Änderungsprotokoll.
Fügen Sie neue Arbeiten, die Sie entdecken, als neue Elemente mit neuen IDs hinzu.
Fassen Sie die Änderungen für den Benutzer zusammen. Fragen Sie, bevor Sie etwas streichen.

Eine Roadmap überprüfen

Wenn Sie nur zur Überprüfung aufgefordert werden, schreiben Sie nicht um. Berichten Sie, am wichtigsten zuerst:

Ziele oder Phasen, bei denen nicht festgestellt werden kann, wann sie abgeschlossen sind;
Elemente mit unklaren Akzeptanzkriterien;
fehlende oder zirkuläre Abhängigkeiten;
Entscheidungen, die als getroffen dargestellt werden, aber von den Beweisen nicht gestützt werden;
Elemente, die der Code oder der Issue-Tracker bereits als erledigt oder nicht mehr relevant zeigen;
fehlende Risiken: die schwierigsten oder am wenigsten verstandenen Teile, die spät eingeplant sind.

Vorlage

# <Projekt- oder Funktions-Roadmap>

**Ziel:** <das Ergebnis in ein oder zwei Sätzen>
**Status:** <entwurf | aktiv | abgeschlossen | ersetzt>
**Zuletzt aktualisiert:** <JJJJ-MM-TT>

## Kontext

Warum diese Arbeit jetzt wichtig ist, was heute existiert, und Links zu den Beweisen.

## Umfang

- **Drin:** …
- **Draußen:** …
- **Darf sich nicht ändern:** …

## Status-Legende

| Status         | Bedeutung                                         |
| -------------- | ------------------------------------------------- |
| `planned`      | Vereinbart, nicht begonnen                        |
| `in-progress`  | Jemand arbeitet daran                             |
| `blocked`      | Wartet auf eine Abhängigkeit oder Entscheidung (sagen, welche) |
| `done`         | Jedes Akzeptanzkriterium erfüllt, mit Beweis      |
| `dropped`      | Wird nicht gemacht (sagen, warum)                 |

## Phase 1: <Name>

**Abbruchkriterien:** <was wahr ist, wenn diese Phase abgeschlossen ist>

### R-001: <Kurzer Titel>

- **Status:** planned
- **Warum:** <das Problem, das dies löst>
- **Akzeptanzkriterien:**
  - [ ] <überprüfbare Aussage>
- **Abhängigkeiten:** <IDs, oder „none“>
- **Beweis:** <Issue-, PR- oder Dateilinks>

## Phase 2: <Name>

…

## Offene Entscheidungen

| ID    | Frage | Optionen | Blockiert | Besitzer |
| ----- | ----- | -------- | --------- | -------- |
| D-001 | …     | …        | R-004     | …        |

## Risiken

| Risiko | Wahrscheinlichkeit | Auswirkung | Maßnahme |
| ------ | ------------------ | ---------- | -------- |

## Änderungsprotokoll

- <JJJJ-MM-TT>: <was geändert wurde und warum>

Lassen Sie Abschnitte weg, die nicht zutreffen. Eine kleine Roadmap könnte nur aus einem Ziel, einer Phase und einem Änderungsprotokoll bestehen.

Nicht tun

Eine Entscheidung erfinden, weil die Roadmap ohne sie unvollständig aussieht.
Den Plan mit allgemeinen Elementen („Dokumentation hinzufügen“, „Tests verbessern“) aufblähen, die kein spezifisches Ergebnis haben.
Elemente umnummerieren oder gestrichene löschen.
Arbeit allein anhand eines PR-Titels als done markieren, ohne die Kriterien zu prüfen.
Den gesamten Inhalt einer Roadmap in Issues kopieren oder umgekehrt. Verlinken Sie stattdessen.

lggarrison/agent-skills

Was ist agent-skills?

In Ihrer bevorzugten KI fragen

Dokumentation