/ Verzeichnis / Playground / pilot-shell
← Alle Server ↗ GitHub
● Community maxritter ⚡ Sofort

pilot-shell

von maxritter · maxritter/pilot-shell

Spezifikationsgetriebenes Claude Code mit eingebauten Qualitätsgates — jede Änderung durchläuft Plan → Spec → Implementierung → Verifikation bevor sie landet.

pilot-shell hüllt Claude Code in eine spezifikationsgetriebene Schleife: Features beginnen als Pläne, werden zu Specs, werden gegen Abnahmekriterien implementiert und shippen erst wenn Gates grün sind (lint, type, test, doc). Es persistiert außerdem Projektwissen — Invarianten, Entscheidungen, Gotchas — damit Qualität sitzungsübergreifend bestehen bleibt.

▶ Demo ansehen 📦 Installieren 💡 Anwendungsfälle

Warum nutzen

Hauptfunktionen

Live-Demo

In der Praxis

bereit

Installation

Repository des Autors · Offizielle Dokumentation zu Claude Skills

Anwendungsfälle

Praxisnahe Nutzung: pilot-shell

Feature mit Spec-First-Disziplin shippen

👤 Entwickler, die halbgare KI-geschriebene Features leid sind ⏱ ~90 min intermediate

Wann einsetzen: Vage Feature-Anforderung vom PM; du willst es richtig geliefert, nicht schnell.

Ablauf
  1. Planen
    Use pilot-shell. Plan the feature 'export usage CSV per workspace per month'. List unknowns + risks.✓ Kopiert
    → Plan mit expliziten Unbekannten; du füllst Lücken vor dem nächsten Schritt
  2. Spezifizieren
    From the plan, write a spec with acceptance criteria + non-goals + edge cases.✓ Kopiert
    → Spec gespeichert unter /specs/<feature>.md
  3. Implementieren
    Implement against the spec. Tests first, then code. Stop at any unmet criterion.✓ Kopiert
    → Tests + Implementierung; fehlschlagende Tests sichtbar bis Implementierung besteht
  4. Gates prüfen
    Run all gates: lint, type, tests, docs. Block PR if any red.✓ Kopiert
    → Gate-Report; nur grün = Merge-Kandidat

Ergebnis: Features die spec-vollständig shippen, mit Tests und Docs.

Fallstricke
  • Spec-Phase wird zum Planungsmarathon — Spec-Phase auf 30 Min. eingrenzen; kleinste Spec shippen die Abnahme sperrt
Kombinieren mit: filesystem

PRs verhindern, die beim ersten CI-Lauf fehlschlagen

👤 Entwickler, deren PRs häufig an lint/type-Fehlern scheitern ⏱ ~30 min intermediate

Wann einsetzen: Du hast diese Woche 3 PRs geöffnet; alle schlugen bei Basics in CI fehl.

Ablauf
  1. Gates verdrahten
    Use pilot-shell. Configure quality gates to mirror our CI: eslint, tsc, vitest, prettier.✓ Kopiert
    → .pilot.config.json mit aufgelisteten Gates
  2. Bei Rot blockieren
    Set policy: don't open PR until all gates green locally.✓ Kopiert
    → Richtlinie angewendet
  3. Messen
    After 2 weeks, compare CI first-run pass rate before/after.✓ Kopiert
    → Pass-Rate gestiegen

Ergebnis: PRs, die CI beim ersten Versuch bestehen; weniger Aufwand für Reviewer.

Fallstricke
  • Lokale Gates weichen subtil von CI ab (Node-Version) — Lokale Node-Version mit .nvmrc pinnen; exakte CI-Befehle spiegeln
Kombinieren mit: github

Projektwissen beim Teamwachstum bewahren

👤 Projektverantwortliche beim Onboarding neuer Mitarbeiter ⏱ ~30 min beginner

Wann einsetzen: Du übergibst / teilst das Projekt; willst Entscheidungen und Invarianten erfasst haben.

Ablauf
  1. Wissensdatei initialisieren
    Use pilot-shell. Initialize project knowledge with: architecture, key invariants, decisions log.✓ Kopiert
    → /.pilot/knowledge.md erstellt mit Abschnitten
  2. Laufend erfassen
    Whenever a decision is made (chose Postgres over MySQL), record with date + reason.✓ Kopiert
    → Entscheidungen akkumulieren; neue Mitarbeiter können Geschichte lesen
  3. Beim Onboarding verwenden
    When a new collaborator starts, point Claude Code to this file as primary context.✓ Kopiert
    → Schnellere Einarbeitung; weniger 'warum ist es so'

Ergebnis: Wissen überlebt Teamwechsel.

Fallstricke
  • Wissensdatei wird zum Trivialitätenjournal — Knapp halten: Invarianten, Entscheidungen, Gotchas. Kein Tagesprotokoll

Kombinationen

Mit anderen MCPs für 10-fache Wirkung

pilot-shell-skill + github

PR-Template automatisch aus Spec befüllen; CI validiert Gates

When opening a PR, populate the body from the spec markdown; CI checks gates match.✓ Kopiert
pilot-shell-skill + filesystem

Specs und Wissen ins Repo committen

Persist /specs/ and /.pilot/knowledge.md in repo for review history.✓ Kopiert

Werkzeuge

Was dieses MCP bereitstellt

WerkzeugEingabenWann aufrufenKosten
plan feature_description Schritt 1 jedes neuen Features 0
spec plan_id Nach dem Auflösen von Plan-Unbekannten 0
implement spec_id Nach Spec-Genehmigung 0
run_gates scope? Pre-PR; CI-Spiegel 0
knowledge_update decision_or_invariant Projektebene-Entscheidung erfassen 0

Kosten & Limits

Was der Betrieb kostet

API-Kontingent
Keine — lokal
Tokens pro Aufruf
Spec-Docs ~500–2000 Tokens; Wissensdatei begrenzt auf ~3000 um handhabbar zu bleiben
Kosten in €
Kostenlos
Tipp
knowledge.md auf ~3000 Tokens begrenzen; ältere Einträge periodisch konsolidieren

Sicherheit

Rechte, Secrets, Reichweite

Minimale Scopes: filesystem-write
Credential-Speicherung: Keine
Datenabfluss: Keine

Fehlerbehebung

Häufige Fehler und Lösungen

Gates bestehen lokal aber schlagen in CI fehl

Node-Version, OS-spezifische Abhängigkeiten pinnen; CI-Befehl exakt spiegeln

Prüfen: Diff local vs CI command output
Implementierungsschritt überspringt Test-First

Richtlinie strict_tdd=true in .pilot.config setzen; Tool weigert sich dann, Implementierung vor Tests zu schreiben

Spec-Phase zieht sich

--time-box 30m verwenden; Entscheidungen bei Unbekannten erzwingen statt perfekte Specs

Wissensdatei zu lang

knowledge_consolidate ausführen; archiviert alte Einträge nach /.pilot/archive/

Alternativen

pilot-shell vs. andere

AlternativeWann stattdessenKompromiss
spec-workflow-mcpAls MCP-Server mit tool-übergreifender Reichweite gewünscht (kein Claude Code Skill)Mehr Setup; flexibleres Deployment
Plain CLAUDE.md + manual TDDSolo-Projekt, keine Automatisierung nötigDisziplinabhängig; weniger Sicherheitsnetz

Mehr

Ressourcen

📖 Offizielle README auf GitHub lesen

🐙 Offene Issues ansehen

🔍 Alle 400+ MCP-Server und Skills durchsuchen