poorvith-mp/skills-writing

sop-writing

コア哲学

標準作業手順書（SOP）は、理論的なエッセイや野心的なポリシー文書ではありません。SOPは、人間またはエージェントオペレータ向けの実行可能なアルゴリズム的手順書です。優れたSOPは、資格のあるオペレータが午前3時に極度のストレス下でも、ゼロの曖昧さ、ゼロの推測、ゼロの致命的エラーでプロセスを実行できるように設計されています。すべてのステップには、決定的な入力、番号付きの物理アクション、観察可能な受入基準、明確なエスカレーションパスが必要です。

---

4ステップ標準作業手順書（SOP）アーキテクチャ

ステップ1：スコープ、ガバナンス、前提条件

1. メタデータと所有権ヘッダー：
   • SOP ID、バージョン（SemVer）、発効日、レビュー頻度（年次/半期）、責任プロセスオーナー。
2. 厳格な目的とスコープの境界：
   • この手順がカバーする内容と、カバーしない内容。
3. 前提条件とアクセス権限：
   • 最初の実行ステップの前に、必要な認証情報、VPNアクセス、ソフトウェアパッケージ、環境変数をリストアップします。

ステップ2：決定的な番号付きステップシーケンス

1. 命令的で曖昧さのないアクション動詞：
   • すべてのステップを能動的な動詞で始めます：クリック、実行、確認、コピー、エクスポート、チェック。
   • 受動的なガイドライン（「ログが確認されていることを確認する」）は絶対に書きません。
   • 次のように記述します："1. Datadogダッシュボード Prod-Ingestion を開く。2. グラフ p99 Latency を確認する。3. 値が200ms未満であることを確認する。"
2. コピーペーストコマンドの衛生管理：
   • 正確なCLIコマンドまたはコードスニペットをフェンスブロックで提供します。オペレータにフラグ名やパラメータを推測させることは絶対に避けます。

ステップ3：観察可能な検証と受入ゲート

1. 「動作したかどうかをどうやって確認するか？」チェック：
   • 主要な各ステップは、その期待される出力を指定する必要があります：
     • "期待される出力：ターミナルに Deployment Complete: 12/12 pods healthy と表示される。"
2. 決定木と分岐ロジック：
   • 条件ロジックを明確にフォーマットします：
     • ステータスが200の場合：ステップ4に進みます。
     • ステータスが500の場合：トラブルシューティングセクション5.1にジャンプします。

ステップ4：障害処理、ロールバック、エスカレーションパス

1. ロールバック手順書：
   • 手順が途中で失敗した場合に、システムを安全なベースライン状態に復元するための正確なロールバックコマンドを提供します。
2. エスカレーションSLAと連絡先マトリックス：
   • 手順が15分以内に完了できない場合、誰に、どのチャネルで、どの重大度でページングするか。

---

成果物フォーマット：本番標準作業手順書（SOP-TEMPLATE.md）

# Standard Operating Procedure: Production Hotfix Deployment
*SOP ID: SOP-ENG-042 | Version: v2.1.0 | Owner: Platform Engineering Lead*
*Effective Date: [YYYY-MM-DD] | Review Cadence: Quarterly*

## 1. Purpose & Scope
This procedure governs the deployment of emergency hotfixes to production clusters outside the standard weekly CI/CD release cycle.

## 2. Prerequisites & Access Requirements
- Production AWS IAM Role `arn:aws:iam::123456789012:role/EmergencyDeployer`
- GitHub CLI (`gh`) authenticated with repository write access
- AWS CLI v2 and `kubectl` configured locally

## 3. Step-by-Step Execution Sequence

### Step 1: Branch Isolation & Verification
1. Checkout hotfix branch from `main`:
   ```bash
   git checkout main && git pull origin main
   git checkout -b hotfix/SEC-[IssueNum]

2. Run full test suite locally:

   npm run test:ci
   

   • Acceptance Check: Exit code 0; all test suites pass.

Step 2: Build & Tag Container Image

1. Trigger automated hotfix build pipeline:

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

   • Expected Output: GitHub Actions emits image digest sha256:....

Step 3: Production Rollout & Canary Verification

1. Apply rollout to Canary pod pool (10% traffic):

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

2. Monitor error rates for 5 minutes:
   • Check Grafana dashboard https://grafana.internal/d/canary-health.
   • Acceptance Gate: 5xx error rate must remain < 0.01%.

4. Rollback & Contingency Plan

If Canary error rate exceeds 0.05%:

1. Roll back deployment immediately:

   kubectl rollout undo deployment/api-gateway -n production
   

2. Notify Incident Commander on Slack #incident-war-room.

5. Escalation Contacts

• Primary On-Call SRE: PagerDuty schedule sre-tier-1
• Engineering VP: Phone: [Number] (Page if outage exceeds 15 minutes)

---

## 実例：データベース復元SOP

- **コンテキスト**：暗号化されたPostgreSQLデータベーススナップショット復元のための復旧手順書。
- **影響**：ステップバイステップのSOPにより、夜間ローテーションのジュニアエンジニアが誤って削除された顧客テーブルを11分で復元し、データ破損ゼロを達成しました。

---

## 検証チェックリスト

- [ ] すべての手順ステップが能動的命令動詞で始まっている。
- [ ] コマンドとコードスニペットは、正確な構文で100%コピーペースト可能である。
- [ ] 重要な各ステップについて、観察可能な期待出力が指定されている。
- [ ] 失敗した実行に対する明示的なロールバック手順が文書化されている。
- [ ] エスカレーション連絡先マトリックスに、名前付きの役割とページングチャネルが含まれている。

---

## アンチパターン

- **曖昧な指示**：正確なIPテーブルやYAML設定を提供する代わりに、「ネットワークを適切に設定する」と書くこと。
- **ロールバック手順書の欠落**：変更をプッシュする方法を説明しながら、それが壊れた場合に元に戻す方法を説明しないこと。
- **未テストの手順書**：ステージング環境でドライランが行われたことのない緊急災害復旧SOPを書くこと。