poorvith-mp/skills-writing

SOP-Schreiben

Kernphilosophie

Eine Standard Operating Procedure (SOP) ist kein theoretischer Aufsatz oder ein ambitioniertes Richtliniendokument. Eine SOP ist ein ausführbares algorithmisches Runbook für menschliche oder agentische Operatoren. Eine gute SOP ist so gestaltet, dass ein qualifizierter Operator unter extremem Stress um 3:00 Uhr morgens den Prozess mit null Mehrdeutigkeit, null Rätselraten und null katastrophalen Fehlern ausführen kann. Jeder Schritt muss deterministische Eingaben, nummerierte physische Aktionen, beobachtbare Akzeptanzkriterien und explizite Eskalationspfade haben.

---

4-Schritte-Architektur einer Standard Operating Procedure (SOP)

Schritt 1: Umfang, Governance und Voraussetzungen

1. Metadaten- und Eigentümer-Kopfzeile:
   • SOP-ID, Version (SemVer), Datum des Inkrafttretens, Überprüfungsrhythmus (jährlich/halbjährlich), verantwortlicher Prozessverantwortlicher.
2. Strenge Ziel- und Umfangsgrenzen:
   • Genau, was dieses Verfahren abdeckt und was es nicht abdeckt.
3. Voraussetzungen und Zugriffsberechtigungen:
   • Vor dem ersten Ausführungsschritt erforderliche Anmeldeinformationen, VPN-Zugriff, Softwarepakete und Umgebungsvariablen auflisten.

Schritt 2: Die deterministische nummerierte Schrittfolge

1. Imperative, eindeutige Aktionsverben:
   • Beginnen Sie jeden Schritt mit einem aktiven Verb: Klicken, Ausführen, Überprüfen, Kopieren, Exportieren, Prüfen.
   • Schreiben Sie niemals passive Anweisungen: "Stellen Sie sicher, dass Protokolle angesehen werden."
   • Schreiben Sie: "1. Datadog-Dashboard Prod-Ingestion öffnen. 2. Grafik p99 Latency inspizieren. 3. Überprüfen, ob der Wert unter 200ms liegt."
2. Copy-Paste-Befehlshygiene:
   • Geben Sie genaue CLI-Befehle oder Code-Ausschnitte in umrandeten Blöcken an. Lassen Sie Operatoren niemals über Flag-Namen oder Parameter raten.

Schritt 3: Beobachtbare Überprüfung und Akzeptanzgates

1. Der "Woher weiß ich, dass es funktioniert hat?"-Check:
   • Jeder wichtige Schritt muss seine erwartete Ausgabe angeben:
     • "Erwartete Ausgabe: Terminal zeigt Deployment Complete: 12/12 Pods gesund an."
2. Entscheidungsbäume und Verzweigungslogik:
   • Formatieren Sie bedingte Logik klar:
     • Wenn Status == 200: Fahren Sie mit Schritt 4 fort.
     • Wenn Status == 500: Springen Sie zum Fehlerbehandlungsabschnitt 5.1.

Schritt 4: Fehlerbehandlung, Rollback und Eskalationspfade

1. Das Rollback-Runbook:
   • Wenn das Verfahren mitten im Prozess fehlschlägt, geben Sie genaue Rollback-Befehle an, um das System auf einen sicheren Ausgangszustand zurückzusetzen.
2. Eskalations-SLA und Kontaktmatrix:
   • Wen man auf welchem Kanal mit welcher Schwere anrufen muss, wenn das Verfahren nicht innerhalb von 15 Minuten abgeschlossen werden kann.

---

Lieferformat: Produktions-Standard Operating Procedure (SOP-TEMPLATE.md)

# Standard Operating Procedure: Produktions-Hotfix-Deployment
*SOP-ID: SOP-ENG-042 | Version: v2.1.0 | Verantwortlich: Platform Engineering Lead*
*Datum des Inkrafttretens: [YYYY-MM-DD] | Überprüfungsrhythmus: Vierteljährlich*

## 1. Zweck und Umfang
Dieses Verfahren regelt die Bereitstellung von Notfall-Hotfixes in Produktions-Cluster außerhalb des regulären wöchentlichen CI/CD-Release-Zyklus.

## 2. Voraussetzungen und Zugriffsanforderungen
- Produktions-AWS-IAM-Rolle `arn:aws:iam::123456789012:role/EmergencyDeployer`
- GitHub CLI (`gh`) authentifiziert mit Schreibzugriff auf das Repository
- AWS CLI v2 und `kubectl` lokal konfiguriert

## 3. Schritt-für-Schritt-Ausführungssequenz

### Schritt 1: Branch-Isolation und Überprüfung
1. Hotfix-Branch von `main` auschecken:
   ```bash
   git checkout main && git pull origin main
   git checkout -b hotfix/SEC-[IssueNum]

2. Vollständige Testsuite lokal ausführen:

   npm run test:ci
   

   • Akzeptanzprüfung: Exit-Code 0; alle Testsuiten bestanden.

Schritt 2: Container-Image bauen und taggen

1. Automatisierten Hotfix-Build-Pipeline auslösen:

   gh workflow run hotfix-build.yml -f branch=hotfix/SEC-[IssueNum]
   

   • Erwartete Ausgabe: GitHub Actions gibt Image-Digest sha256:... aus.

Schritt 3: Produktions-Rollout und Canary-Überprüfung

1. Rollout auf Canary-Pod-Pool (10 % Traffic) anwenden:

   kubectl set image deployment/api-gateway api=ecr.internal/api:[Digest] -n production
   

2. Fehlerraten 5 Minuten lang überwachen:
   • Grafana-Dashboard https://grafana.internal/d/canary-health prüfen.
   • Akzeptanzgate: 5xx-Fehlerrate muss unter 0,01 % bleiben.

4. Rollback und Notfallplan

Wenn die Canary-Fehlerrate 0,05 % übersteigt:

1. Deployment sofort zurückrollen:

   kubectl rollout undo deployment/api-gateway -n production
   

2. Incident Commander auf Slack #incident-war-room benachrichtigen.

5. Eskalationskontakte

• Primärer Bereitschafts-SRE: PagerDuty-Plan sre-tier-1
• Engineering-VP: Telefon: [Nummer] (Seite, wenn Ausfall 15 Minuten überschreitet)

---

## Ausgearbeitetes Beispiel: Datenbankwiederherstellungs-SOP

- **Kontext**: Wiederherstellungs-Runbook für die Wiederherstellung verschlüsselter PostgreSQL-Datenbanksnapshots.
- **Auswirkung**: Die schrittweise SOP ermöglichte es einem Junior-Ingenieur in der Nachtschicht, eine versehentlich gelöschte Kundentabelle in 11 Minuten ohne Datenbeschädigung wiederherzustellen.

---

## Überprüfungs-Checkliste

- [ ] Jeder Verfahrensschritt beginnt mit einem aktiven imperativen Verb.
- [ ] Befehle und Code-Ausschnitte sind zu 100 % kopierbar mit exakter Syntax.
- [ ] Erwartete beobachtbare Ausgabe ist für jeden kritischen Schritt angegeben.
- [ ] Explizite Rollback-Verfahren für fehlgeschlagene Ausführungen sind dokumentiert.
- [ ] Die Eskalationskontaktmatrix enthält benannte Rollen und Paging-Kanäle.

---

## Anti-Muster

- **Mehrdeutige Anweisungen**: "Konfigurieren Sie das Netzwerk ordnungsgemäß" schreiben, anstatt die genauen IP-Tabellen oder die YAML-Konfiguration anzugeben.
- **Fehlendes Rollback-Runbook**: Erklären, wie eine Änderung gepusht wird, ohne zu erklären, wie sie rückgängig gemacht wird, wenn sie kaputt geht.
- **Ungetestete Runbooks**: Eine Notfall-Wiederherstellungs-SOP schreiben, die noch nie in einer Staging-Umgebung trocken getestet wurde.