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
- 1Kontext festlegen: Eine zentrale Kontextdatei im Repository hält Architekturentscheide, Tech-Stack und Coding-Guidelines fest, je nach Werkzeug zum Beispiel eine
replit.mdoder.cursorrules. - 2Aufgabe spezifizieren: Bevor eine Zeile Code entsteht, beschreiben wir das «Was» und das «Warum», samt Abnahmekriterien.
- 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
| Kriterium | Bedeutung |
|---|---|
| Explizit | Keine Annahmen. Legen Sie genau fest, welche Bibliotheken und Versionen gelten. |
| Modular | Zerlegen Sie grosse Aufgaben in kleine Schritte, die der Agent einzeln umsetzen kann. |
| Prüfbar | Definieren 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.readfü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)
| ADR | Entscheid | Begründung |
|---|---|---|
| ADR-001 | Fluent UI v9 statt Tailwind CSS | SharePoint-nativer Look, Theming-Kompatibilität, eingebaute Barrierefreiheit |
| ADR-002 | SPFx HttpClient statt fetch | Lä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-003 | localStorage-Cache mit TTL | Zeigt bei Ausfall die letzten Daten, reduziert Aufrufe beim Wetterdienst, braucht keinen Server-State. Die TTL-Werte sind Designentscheide. |
| ADR-004 | Service-Interface-Pattern | Dependency Injection für Unit Tests, Mock-Service für die Entwicklung |
| ADR-005 | Error Boundary pro Widget | Ein einzelner Fehler legt nicht das ganze Webpart lahm |
| ADR-006 | API-Schlüssel nur im Serverdienst | Der 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 viasetInterval, Cache-IntegrationuseGeolocation(): Browser-Geolocation mit Permission-HandlinguseThemeDetection(): SharePoint-Theme für adaptive FarbenuseResponsiveLayout(): erkennt die Webpart-Breite für Mini-, Standard- und Full-Modus
6. Tests
| Test-Typ | Werkzeug | Abdeckung |
|---|---|---|
| Unit Tests | Jest + React Testing Library | Service-Layer, Cache, Hooks (>80 %) |
| Integration | SPFx Workbench | Property Pane, Rendering, Theme |
| E2E | Playwright | Live-Test in SharePoint Online |
| Mock-Service | MockWeatherService | Offline-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 --shipDeployment mit PnP PowerShell:
Connect-PnPOnline -Url "https://tenant.sharepoint.com/sites/appcatalog"
Add-PnPApp -Path "./sharepoint/solution/weather-webpart.sppkg" -OverwriteGrenzen
- 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.

