Davi's Devlog

Appearance

0. 이 챕터의 목적 ​

운영 매뉴얼·테스트 핸드북·정찰 보고서를 작성하는 사람이 가장 자주 마주치는 질문은 "어떤 구조로 써야 할까?"다.

본 챕터는 6섹션 표준 구조를 제시한다. 이 구조의 가치는 읽는 쪽의 진입 시간과 쓰는 쪽의 누락 방지 두 측면 모두에서 나온다.

  • 독자: 새 챕터를 펼쳤을 때 어디에 무엇이 있는지 즉시 안다 — §0은 목적, §1은 개념, §2는 명령, §3은 비정상 패턴, §4는 시나리오, §5는 역방향 매핑
  • 저자: 6섹션을 채워나가며 누락이 시각화된다 — §3가 비어있다면 비정상 패턴 정찰을 하지 않은 것

이 구조는 인프라 SaaS 테스트, 시스템 정찰 절차, 운영 사고 대응 매뉴얼 어디에든 적용 가능하다.

1. 6섹션 표준 구조 ​

text
## 0. 이 챕터의 정찰 목적
   ─ 무엇을 알아내려 하는가
   ─ 왜 알아내야 하는가
   ─ 어느 챕터·어느 테스트와 연결되는가

## 1. 개념 — 본문 이해에 필요한 최소 배경
   ─ 본문을 읽기 전 알아둬야 할 사전 지식

## 2. 정찰 명령과 출력 해석
   ─ 명령 한 줄 + 실제 출력 + 줄별 해석 + 끌어내야 할 정보

## 3. 출력의 비정상 패턴과 조기 경보
   ─ 정상 출력 vs 의심 출력의 대조표
   ─ 즉시 멈춰야 할 신호

## 4. 이 영역의 테스트 대분류와 시나리오
   ─ [02 4 분류](./02-test-classification) 각각에 해당하는 시나리오 카탈로그

## 5. 정찰 ↔ 테스트 단계 역방향 매핑
   ─ "특정 액션을 하기 전에 §2의 어느 출력을 확인해야 하는가"

1.1 섹션 번호의 의미 ​

§0이 0으로 시작하는 것은 의도적이다. §0은 "이 챕터를 읽기 전 결정"의 영역(읽을 가치 평가)이고, §1부터가 "본문"이다. 독자가 §0만 읽고 챕터를 닫을 수 있어야 한다.

1.2 부록은 자유 ​

위 6섹션 외에 부록(명령 치트시트, 참고 자료, 다음 챕터로의 인계 등)은 자유롭게 추가 가능하다. 본 표준은 본문의 6섹션만 강제한다.

2. 각 섹션의 작성 규칙 ​

2.1 §0 정찰 목적 ​

3개 질문에 답한다.

  1. 무엇을 알아내려 하는가 — 한 문단으로 챕터의 핵심 산출물 명시
  2. 왜 알아내야 하는가 — 이 정보가 부재할 때 어떤 사고가 가능한가
  3. 어느 챕터·테스트와 연결되는가 — 본 챕터를 펼친 독자가 이어서 펼칠 챕터·다른 자료

§0은 보통 200~400자. 길어지면 본문의 §1 또는 §4로 흘러가게 마련.

2.2 §1 개념 ​

§2의 명령 출력을 읽을 때 막히지 않을 수준의 사전 지식만 다룬다. 개념의 깊은 해부는 별도 자료에 위임한다 — §1이 길어지면 본 챕터의 정찰 절차가 묻혀버린다.

다음을 분리한다.

  • §1에 들어갈 것: 본 챕터의 명령·출력·시나리오를 이해하는 데 직접 필요한 개념
  • §1에 들어가지 않을 것: 일반 학습용 개념 (위 분리는 별도 학습 시리즈로 위임)

§1은 보통 챕터 분량의 10~20%. 그 이상이면 챕터 분리 검토.

2.3 §2 정찰 명령과 출력 해석 ​

본 챕터의 핵심. 표준 구조:

markdown
### 2.X 명령 이름 (또는 정찰 항목)

[명령 한 줄]

[실제 출력 블록 — 가상 예시 또는 마스킹된 실측]

[줄별 의미 풀이 — 명령 출력의 어느 줄이 무엇을 의미하는가]

> **이 출력에서 끌어내야 할 정보 N가지**:
> 1. ...
> 2. ...
> 3. ...

각 명령마다 위 4 블록을 일관되게 채운다. "끌어내야 할 정보" 블록이 없으면 단순 명령 카탈로그가 되어 매뉴얼의 가치가 사라진다.

2.4 §3 비정상 패턴과 조기 경보 ​

본 매뉴얼에서 가장 자주 펼쳐질 섹션이다. 사고는 정상 시점에 일어나지 않고 비정상 시점에 일어나며, 비정상의 첫 신호를 빠르게 인식하는가에 사고 확산 여부가 결정된다.

표준 구조:

markdown
### 정상 패턴
[명령] → [정상 출력 일부]
정상의 근거: ...

### 의심 패턴
[명령] → [의심 출력 일부]
원인 가설: A, B, C
즉시 확인할 후속 명령: ...

### 즉시 중단 신호
[다음 출력이 보이면 자기 작업을 즉시 중단하고 책임자에게 보고]
- ...

§3의 분량은 §2와 거의 비슷해야 한다. §2 대비 §3가 짧으면 비정상 정찰이 누락된 것이다.

2.5 §4 테스트 대분류와 시나리오 ​

본 영역의 테스트 시나리오 카탈로그를 02 4 분류에 따라 정리한다.

markdown
### 4.1 CRUD 기능 검증
[시나리오 1] 사전 정찰 §2.X → 작업 → 검증 §2.Y
[시나리오 2] ...

### 4.2 스테이징 워크플로우
...

### 4.3 위험 시나리오·에러 처리
...

### 4.4 클러스터 일관성
...

각 시나리오마다 01 L×R 격자 셀과 04 6 Layer 검증 깊이를 명시하면 행동 지침이 자동 결정된다.

2.6 §5 역방향 매핑 ​

§4와 §5는 같은 데이터의 두 인덱싱이다.

  • §4: "이 영역에서 가능한 모든 테스트의 카탈로그" — 신규 테스터가 펼친다
  • §5: "특정 액션을 수행하기 전에 어떤 정찰이 선행되어야 하는가" — 반복 테스터가 펼친다

§5의 표준 구조:

markdown
| 작업 | 사전 §2 정찰 | 격자 셀 | 검증 Layer |
| --- | --- | --- | --- |
| VM 마이그레이션 | §2.3 노드 가용성 | L2 × R2 | L1·L4·L6 |
| ... | ... | ... | ... |

§5는 §4를 방향만 바꿔 정리한 표이다. 새 데이터를 만들지 않는다.

3. §4와 §5 분리 이유 (반복) ​

같은 정보를 두 번 적는 것이 비효율적으로 보일 수 있으나, 사용 시점이 다르다.

시점펼치는 섹션사용 패턴
신규 진입 / 테스트 카탈로그 탐색§4"오늘 내가 할 수 있는 테스트가 무엇인가"
특정 액션 직전 / 사고 전§5"지금 이 액션을 안전하게 하려면 무엇을 미리 봐야 하는가"
사고 발생 후 / 원인 추적§3"현재 출력이 비정상인가, 어디까지 영향이 갔는가"

§4 단독으로 매뉴얼을 만들면 사고 직전 사용자가 카탈로그를 뒤져 자기 작업에 필요한 사전 정찰 항목을 직접 추출해야 한다. §5는 그 추출 작업을 매뉴얼이 미리 해두는 것이다.

4. §3의 위치와 무게 (반복) ​

§3는 본 표준 구조에서 가장 자주 사용된다. 그러나 작성 시 가장 자주 누락된다 — 정상 케이스만 정찰하고 비정상 케이스는 "필요할 때 채우자"로 미루기 쉽다.

규칙: §3가 빈 챕터는 미완성 챕터다. §2를 적었다면 §3에 최소 다음 3종은 있어야 한다.

  • 정상 패턴 1개 이상 (정상의 근거 명시)
  • 의심 패턴 1개 이상 (원인 가설 + 후속 명령)
  • 즉시 중단 신호 1개 이상

이 3종이 없으면 §3 자체가 형식적이며 사고 시 도움이 되지 않는다.

5. 메타 챕터 (시리즈 개요)의 예외 ​

시리즈의 첫 챕터(00)나 메타 자료에 해당하는 챕터는 본 6섹션 구조를 엄격히 따르지 않을 수 있다.

이런 챕터는 보통:

  • §4(분류 정의)는 시나리오 카탈로그가 아닌 분류 자체의 설명
  • §5(역방향 매핑)는 후속 챕터 인덱스로 대체
  • §3(비정상 패턴)은 §2(첫 판독) 안에 자연스럽게 녹아들어 분리하지 않음

메타 챕터 외 모든 챕터는 6섹션 구조를 엄격히 따른다. 메타 챕터에서 시작된 자유로움이 본문 챕터로 새는 것을 막는다.

6. 챕터 작성 5단계 사이클 ​

본 표준 구조의 챕터는 다음 5단계로 작성한다.

text
[1] 데이터 수집 명령 묶음 정의
    └ 명령으로 수집 가능한 것 + 환경 메타 정보 분리
[2] N개 노드(또는 관련 노드) 전체에서 데이터 수집
    └ 단일 노드 수집 시 그 한계를 본문에 명시
[3] 수집 데이터 첫 판독 → 본문 작성
    └ §2(명령·출력) → §3(비정상) → §4(시나리오) → §5(역방향) → §1(개념) → §0(목적)
       (§0이 가장 마지막에 작성된다 — 본문이 채워진 후 다시 봐야 정확한 목적이 도출됨)
[4] 챕터 본문 .md 파일 산출
[5] 시리즈 인덱스 갱신 후 다음 챕터로

§0을 마지막에 쓰는 것이 핵심이다. 목적은 본문을 다 쓴 다음에 명확해진다. 처음에 정한 목적을 그대로 §0에 박으면 본문과 어긋나는 챕터가 만들어진다.

7. 산출물 디렉터리 구조 ​

본 표준 구조 챕터들과 부속 산출물의 권장 디렉터리:

text
ops-handbook-series/
├── 00-overview.md                        ← 시리즈 개요 (메타 챕터)
├── 01-cluster-reconnaissance.md          ← 6섹션 구조
├── 02-node-reconnaissance.md             ← 6섹션 구조
├── 03-disk-reconnaissance.md             ← 6섹션 구조
├── ... (이하 6섹션 구조 챕터들)
├── 09-pretest-checklist.md               ← 6섹션 구조 (체크리스트형)
├── 10-recon-output-templates.md          ← 6섹션 구조 (양식 모음)
│
├── artifacts/                            ← 정찰 산출물
│   ├── cluster-topology-YYYY-MM-DD.md
│   ├── resource-inventory-YYYY-MM-DD.md
│   └── isolation-policy-vN.md
│
├── incidents/                            ← 사고 보고서
│   └── YYYY-MM-DD-사고요약.md
│
└── data-snapshots/                       ← 정찰 데이터 원본
    └── YYYY-MM-DD-HHMM-{node}.txt

산출물(artifacts)·사고 보고서(incidents)·데이터 스냅샷(data-snapshots)은 본문 챕터와 분리되어 시점별로 누적된다. 본문 챕터는 추상화된 매뉴얼이고, 산출물은 시점·노드별 구체 데이터다.

8. 챕터 표준 구조의 한계 ​

8.1 정찰·테스트가 아닌 영역 ​

본 6섹션 구조는 정찰·테스트·운영 매뉴얼에 최적화되었다. 다음 영역에는 부적합하다.

  • 개념 학습 가이드: §2(명령·출력)가 적합하지 않으며 §3(비정상)도 의미 없다
  • API 레퍼런스: 표 중심 구조가 본 6섹션과 어긋난다
  • 사용자 튜토리얼: 단계별 흐름이 §2보다 자연스럽다

이런 영역은 별도 표준 구조를 사용한다. 본 챕터는 정찰형 매뉴얼만 다룬다.

8.2 짧은 챕터 ​

매우 짧은 챕터(500줄 미만)에 6섹션 모두를 적용하면 섹션마다 한 단락씩만 들어가 어색해진다. 이 경우 §1과 §2를 합치거나 §4·§5를 합치는 것이 자연스럽다. 구조의 목적은 빈틈 방지이지 형식 강제가 아니다.

9. 정리 ​

본 표준 구조의 가치는 누락 시각화에 있다.

  • §3가 비어있으면 비정상 정찰이 누락
  • §4가 빈약하면 시나리오 카탈로그가 미작성
  • §5가 빈약하면 역방향 매핑이 누락 — 사고 직전 사용성이 떨어짐

이 누락이 시각적으로 드러나는 것이 표준 구조의 핵심이다. 자유 형식 매뉴얼은 누락을 숨기지만, 6섹션 구조는 빈 섹션이 즉시 보인다.

다음 챕터: 04 6 Layer 검증 사슬 — UI에서 게스트까지 풀체인 검증의 6단 사슬.