Zurück zum Blog

    Engineering

    Spec-Driven Development in VS Code: unsere SPFx-Vorlage

    Wie wir Specs für Coding-Agenten in VS Code schreiben: drei Arbeitsschritte und eine vollständige Vorlage für ein SharePoint-Webpart mit SPFx.

    27. Februar 20266 Min. Lesezeit
    Christof Schnyder

    Christof Schnyder

    Software Architect, Co-Founder

    christof.schnyder@cnext.ch
    CNEXT AI Agent
    In diesem Artikel

    Ein Coding-Agent baut ein SharePoint-Webpart dann korrekt, wenn die Spezifikation nichts offenlässt: kompatible Versionen, begründete Architekturentscheide, priorisierte Anforderungen, Schnittstellen, Fehlermeldungen, Tests und Deployment. Bei CNEXT arbeiten wir in VS Code mit Coding-Agenten; deshalb steht bei uns die Spec vor dem Code. Hier finden Sie unseren Arbeitsablauf und die vollständige Spec für ein Wetter-Webpart, die Sie als Vorlage übernehmen können.

    Unser Arbeitsablauf in drei Schritten

    1. 1Kontext festlegen: Eine zentrale Kontextdatei im Repository hält Architekturentscheide, Tech-Stack und Coding-Guidelines fest, je nach Werkzeug zum Beispiel eine replit.md oder .cursorrules.
    2. 2Aufgabe spezifizieren: Bevor eine Zeile Code entsteht, beschreiben wir das «Was» und das «Warum», samt Abnahmekriterien.
    3. 3Iterativ prototypen: Der Agent baut, wir prüfen die Spec und nicht nur den Code.

    Coding-Agenten in VS Code wie GitHub Copilot lesen die Projektstruktur, arbeiten direkt im Dateisystem und können Befehle im Terminal ausführen. Umso wichtiger sind klare Leitplanken. Dazu kommt ein Nebeneffekt: Die Architekturentscheide liegen als Text vor, und neue Teammitglieder lesen sie genauso wie der Agent. Unser Grundsatz dabei: Design for less complexity, design for less overhead.

    Was eine Spec für Agenten braucht

    KriteriumBedeutung
    ExplizitKeine Annahmen. Legen Sie genau fest, welche Bibliotheken und Versionen gelten.
    ModularZerlegen Sie grosse Aufgaben in kleine Schritte, die der Agent einzeln umsetzen kann.
    PrüfbarDefinieren Sie Abnahmekriterien, gegen die Code und Tests geprüft werden.

    Für SPFx heisst «explizit» vor allem: SPFx, Node, TypeScript und React stammen aus derselben Zeile der SPFx-Kompatibilitätstabelle von Microsoft. Die Tabelle ordnet SPFx 1.19 React 17.0.1 zu; mit dieser Kombination arbeitet die Vorlage unten.

    Die Vorlage: Wetter-Webpart für SharePoint

    Mit dieser Spec baut ein Agent in VS Code ein vollständiges SPFx-Webpart, inklusive Architekturentscheiden, Service-Layer, Fehlerbehandlung, Caching und Deployment. Übernehmen Sie Aufbau und Detailgrad; Versionen und Wetteranbieter passen Sie an Ihr Projekt an.

    1. Kontext und Tech-Stack

    • Framework: SPFx 1.19 (SharePoint Framework)
    • Bibliotheken: React 17.0.1, Fluent UI v9, CSS Modules
    • API: OpenWeatherMap (Current Weather und 5-Day Forecast), abgefragt über einen eigenen Serverdienst
    • Ziel: SharePoint Online und Microsoft Teams (Personal Tab und Full-Width)
    • Auth: App-Registrierung mit Scope user.read für standortbasierte Personalisierung
    • API-Schlüssel: nur im Serverdienst gespeichert; der Browser erhält nur die benötigten Werte
    • Caching: localStorage mit TTL (15 Minuten für aktuelle Daten, 60 Minuten für den Forecast)
    • Monitoring: Application Insights Telemetry via @microsoft/applicationinsights-web

    2. Architekturentscheide (ADR)

    ADREntscheidBegründung
    ADR-001Fluent UI v9 statt Tailwind CSSSharePoint-nativer Look, Theming-Kompatibilität, eingebaute Barrierefreiheit
    ADR-002SPFx HttpClient statt fetchLäuft im SPFx-Kontext des Webparts. CORS-Regeln und Retries übernimmt er nicht automatisch; beides legt die Spec fest, und die Tests prüfen es.
    ADR-003localStorage-Cache mit TTLZeigt bei Ausfall die letzten Daten, reduziert Aufrufe beim Wetterdienst, braucht keinen Server-State. Die TTL-Werte sind Designentscheide.
    ADR-004Service-Interface-PatternDependency Injection für Unit Tests, Mock-Service für die Entwicklung
    ADR-005Error Boundary pro WidgetEin einzelner Fehler legt nicht das ganze Webpart lahm
    ADR-006API-Schlüssel nur im ServerdienstDer Schlüssel gehört weder in die Property Pane noch ins ausgelieferte JavaScript

    3. Funktionale Anforderungen

    Must Have (P0):

    • Aktuelles Wetter für einen konfigurierbaren Standort (Stadt oder Koordinaten) mit Ort, Temperatur und Messzeit
    • 5-Tage-Forecast in 3-Stunden-Intervallen als horizontale Scroll-Karten
    • Property Pane: location (Text mit Autocomplete), unit (Toggle Celsius/Fahrenheit), showForecast (Toggle), refreshInterval (Dropdown: 15/30/60 Minuten)
    • Fehlerbehandlung mit verständlichen Meldungen und Retry-Button
    • Responsives Layout: Full-Width sowie 1/2- und 1/3-Spalten
    • Barrierefreiheit: WCAG 2.1 AA, Tastaturnavigation, Screenreader-Support

    Should Have (P1):

    • Standorterkennung über die Browser Geolocation API, mit IP-basiertem Fallback
    • Wetterwarnungen über die OpenWeatherMap One Call API
    • Hintergrundfarbe passt sich der Wetterlage an (sonnig = warm, Regen = kühl)
    • Dark Mode über die SharePoint-Theme-Erkennung

    Nice to Have (P2):

    • Mini-Widget-Modus für schmale Spalten (nur Icon und Temperatur)
    • Mehrsprachigkeit über das SharePoint Language Pack (this.context.pageContext.cultureInfo)

    4. Technische Spezifikation

    Service-Layer:

    interface IWeatherService {
      getCurrentWeather(location: string, unit: Unit): Promise<WeatherData>;
      getForecast(location: string, unit: Unit): Promise<ForecastData>;
      searchLocations(query: string): Promise<LocationResult[]>;
      getAlerts(lat: number, lon: number): Promise<WeatherAlert[]>;
    }
    
    interface WeatherData {
      temp: number;
      feelsLike: number;
      humidity: number;
      windSpeed: number;
      windDirection: number;
      condition: WeatherCondition;
      icon: string;
      sunrise: Date;
      sunset: Date;
      location: { city: string; country: string; lat: number; lon: number };
      lastUpdated: Date;
    }
    
    type WeatherCondition =
      | "clear" | "clouds" | "rain" | "drizzle"
      | "thunderstorm" | "snow" | "mist" | "fog";

    Caching:

    class WeatherCache {
      private readonly CURRENT_TTL = 15 * 60 * 1000;   // 15 Minuten
      private readonly FORECAST_TTL = 60 * 60 * 1000;   // 60 Minuten
    
      get(key: string): CachedData | null {
        const raw = localStorage.getItem('spfx-weather-' + key);
        if (!raw) return null;
        const parsed = JSON.parse(raw);
        if (Date.now() - parsed.timestamp > parsed.ttl) {
          localStorage.removeItem('spfx-weather-' + key);
          return null;
        }
        return parsed.data;
      }
    }

    Fehlerbehandlung:

    • HTTP 401 (Schlüssel im Serverdienst ungültig): «Der Wetterdienst ist nicht verfügbar. Bitte informieren Sie Ihre IT.»
    • HTTP 404: «Standort nicht gefunden. Versuchen Sie es mit einer anderen Stadt.»
    • HTTP 429: «API-Limit erreicht. Nächste Aktualisierung in [countdown].»
    • Netzwerkfehler: letzte gecachte Daten mit dem Hinweis «Offline — Daten von [timestamp]»
    • Timeout (über 5 Sekunden): Abbruch; mit Cache-Eintrag die letzten Daten samt Zeitpunkt, sonst ein Retry-Button

    5. Umsetzung

    Komponenten:

    WeatherWebPart (SPFx Entry)
    ├── WeatherProvider (Context + Service Injection)
    │   ├── ErrorBoundary
    │   │   ├── CurrentWeather (Hauptanzeige)
    │   │   │   ├── WeatherIcon (Animierte SVG-Icons)
    │   │   │   ├── TemperatureDisplay
    │   │   │   └── WeatherDetails (Wind, Humidity, etc.)
    │   │   ├── ForecastStrip (Horizontale Scroll-Karten)
    │   │   │   └── ForecastCard (3h-Intervall)
    │   │   └── AlertBanner (Wetterwarnungen)
    │   └── LoadingState / ErrorState / EmptyState
    └── PropertyPane (Konfiguration)

    Hooks:

    • useWeather(location, unit): Haupthook mit Loading-, Error- und Data-State, Auto-Refresh via setInterval, Cache-Integration
    • useGeolocation(): Browser-Geolocation mit Permission-Handling
    • useThemeDetection(): SharePoint-Theme für adaptive Farben
    • useResponsiveLayout(): erkennt die Webpart-Breite für Mini-, Standard- und Full-Modus

    6. Tests

    Test-TypWerkzeugAbdeckung
    Unit TestsJest + React Testing LibraryService-Layer, Cache, Hooks (>80 %)
    IntegrationSPFx WorkbenchProperty Pane, Rendering, Theme
    E2EPlaywrightLive-Test in SharePoint Online
    Mock-ServiceMockWeatherServiceOffline-Entwicklung, alle Wetterzustände

    Abnahmefälle: gültige und ungültige Ortsnamen, leere Antworten, Timeout, Tastaturbedienung, Theme-Wechsel und Mobilansicht.

    7. Deployment

    Build und Paket:

    gulp bundle --ship
    gulp package-solution --ship

    Deployment mit PnP PowerShell:

    Connect-PnPOnline -Url "https://tenant.sharepoint.com/sites/appcatalog"
    Add-PnPApp -Path "./sharepoint/solution/weather-webpart.sppkg" -Overwrite

    Grenzen

    • Die Spec ist eine Arbeitsgrundlage, kein Sicherheitsnachweis. Prüfen Sie den erzeugten Code im Diff, lassen Sie die Tests laufen und deployen Sie zuerst in einen Test-Tenant.
    • Versionen gelten nur als Paket. Wer eine neuere Zeile der Kompatibilitätstabelle wählt, passt auch Abhängigkeiten und Build-Befehle an; die Befehle oben gehören zu SPFx 1.19.
    • Den Serverdienst, der den API-Schlüssel hält, beschreibt diese Vorlage nicht. Er braucht eine eigene Spec.

    Quelle

    Agentic EngineeringAgentic AISchweiz
    Teilen:

    KI-Tools können die Erstellung dieses Artikels unterstützt haben. CNEXT verantwortet den veröffentlichten Inhalt. Produktfunktionen und Preise können sich ändern; prüfen Sie dafür die verlinkten Originalquellen.

    Christof Schnyder

    Christof Schnyder

    Software Architect, Co-Founder

    SPFx-Prototyp besprechen

    Wir zeigen Ihrem Team, wie Sie VS Code und Coding-Agenten mit klaren Specs in Ihre Arbeitsweise einbinden.