전문 문서 작성 스킬

sop 작성

핵심 철학

표준 운영 절차(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. "작동했는지 어떻게 알 수 있습니까?" 확인:
   • 모든 주요 단계는 예상 출력을 지정해야 합니다:
     • "예상 출력: 터미널에 배포 완료: 12/12 포드 정상이 표시됩니다."
2. 의사 결정 트리 및 분기 로직:
   • 조건부 로직을 명확하게 형식화하십시오:
     • 상태가 200인 경우: 4단계로 진행합니다.
     • 상태가 500인 경우: 문제 해결 섹션 5.1로 이동합니다.

4단계: 실패 처리, 롤백 및 에스컬레이션 경로

1. 롤백 런북:
   • 절차가 중간에 실패하는 경우, 시스템을 안전한 기준 상태로 복원하는 정확한 롤백 명령을 제공하십시오.
2. 에스컬레이션 SLA 및 연락처 매트릭스:
   • 절차를 15분 이내에 완료할 수 없는 경우, 어떤 심각도로 어떤 채널을 통해 누구에게 페이지를 보낼지.

---

전달 형식: 프로덕션 표준 운영 절차(SOP-TEMPLATE.md)

# 표준 운영 절차: 프로덕션 핫픽스 배포
*SOP ID: SOP-ENG-042 | 버전: v2.1.0 | 소유자: 플랫폼 엔지니어링 리드*
*발효일: [YYYY-MM-DD] | 검토 주기: 분기별*

## 1. 목적 및 범위
이 절차는 표준 주간 CI/CD 릴리스 주기 외부에서 프로덕션 클러스터에 긴급 핫픽스를 배포하는 방법을 규정합니다.

## 2. 전제 조건 및 액세스 요구 사항
- 프로덕션 AWS IAM 역할 `arn:aws:iam::123456789012:role/EmergencyDeployer`
- 저장소 쓰기 액세스 권한으로 인증된 GitHub CLI(`gh`)
- 로컬에 구성된 AWS CLI v2 및 `kubectl`

## 3. 단계별 실행 시퀀스

### 1단계: 브랜치 격리 및 확인
1. `main`에서 핫픽스 브랜치를 체크아웃합니다:
   ```bash
   git checkout main && git pull origin main
   git checkout -b hotfix/SEC-[IssueNum]

2. 로컬에서 전체 테스트 스위트를 실행합니다:

   npm run test:ci
   

   • 수용 확인: 종료 코드 0; 모든 테스트 스위트 통과.

2단계: 컨테이너 이미지 빌드 및 태그

1. 자동화된 핫픽스 빌드 파이프라인을 트리거합니다:

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

   • 예상 출력: GitHub Actions가 이미지 다이제스트 sha256:...를 내보냅니다.

3단계: 프로덕션 롤아웃 및 카나리 확인

1. 카나리 포드 풀(10% 트래픽)에 롤아웃을 적용합니다:

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

2. 5분 동안 오류율을 모니터링합니다:
   • Grafana 대시보드 https://grafana.internal/d/canary-health를 확인합니다.
   • 수용 게이트: 5xx 오류율이 0.01% 미만으로 유지되어야 합니다.

4. 롤백 및 비상 계획

카나리 오류율이 0.05%를 초과하는 경우:

1. 즉시 배포를 롤백합니다:

   kubectl rollout undo deployment/api-gateway -n production
   

2. Slack #incident-war-room에서 인시던트 사령관에게 알립니다.

5. 에스컬레이션 연락처

• 1차 온콜 SRE: PagerDuty 일정 sre-tier-1
• 엔지니어링 부사장: 전화: [번호] (장애가 15분을 초과하는 경우 페이지)

---

## 작업 예제: 데이터베이스 복원 SOP

- **컨텍스트**: 암호화된 PostgreSQL 데이터베이스 스냅샷 복원을 위한 복구 런북.
- **영향**: 단계별 SOP를 통해 야간 당직 주니어 엔지니어가 실수로 삭제된 고객 테이블을 11분 만에 데이터 손상 없이 복원할 수 있었습니다.

---

## 확인 체크리스트

- [ ] 모든 절차 단계가 능동 명령형 동사로 시작합니다.
- [ ] 명령 및 코드 조각이 정확한 구문으로 100% 복사-붙여넣기 가능합니다.
- [ ] 모든 중요한 단계에 대해 예상되는 관찰 가능한 출력이 지정됩니다.
- [ ] 실패한 실행에 대한 명시적인 롤백 절차가 문서화됩니다.
- [ ] 에스컬레이션 연락처 매트릭스에 명명된 역할 및 페이징 채널이 포함됩니다.

---

## 안티 패턴

- **모호한 지침**: 정확한 IP 테이블 또는 YAML 구성을 제공하는 대신 "네트워크를 적절히 구성하십시오"라고 작성하는 경우.
- **롤백 런북 누락**: 변경 사항을 푸시하는 방법은 설명하지만, 중단될 경우 되돌리는 방법은 설명하지 않는 경우.
- **테스트되지 않은 런북**: 스테이징 환경에서 드라이 런된 적이 없는 긴급 재해 복구 SOP를 작성하는 경우.