refactor: 문서 개선 중

2026-09-21 14:30:55 +09:00
parent c93cdea150
commit 805a18f486
1497 changed files with 525837 additions and 59152 deletions
@@ -0,0 +1,68 @@
+# Command Pedagogy Policy
+
+이 문서는 `writing-practitioner-guides`의 명령 작성 원칙을 command-pedagogy 보조 흐름에서
+같은 기준으로 쓰기 위한 계약이다. **명령을 짧게 만드는 것보다 사람이 실행하면서 원인과 결과를
+볼 수 있게 만드는 것이 우선**이다.
+
+## 모드
+
+| mode | 기본 판단 |
+|---|---|
+| `tutorial` | 명시적 단계, 목적, 전제조건, 예상 결과가 우선 |
+| `operator` | 한 단계에서 무엇을 바꾸고 무엇을 확인하는지 드러나야 함 |
+| `diagnostic` | 필터링·stderr 억제 전에 원래 출력을 먼저 보여 줌 |
+| `automation` | compact shell 허용. 왜 자동화하는지 이유가 있어야 함 |
+| `reference` | 숙련자가 복사할 compact form 허용. 의미가 숨겨지면 안 됨 |
+
+기본 모드는 `operator`다. 기록이 학습용 절차라면 `tutorial` 또는 `diagnostic` 쪽 판단을
+우선한다.
+
+문서 전체의 성격과 특정 command block의 성격이 다르면 block 바로 앞에서 mode를 좁힐 수 있다.
+
+````markdown
+<!-- command-mode: operator -->
+```bash
+kubectl get pods
+```
+````
+
+기존 문서를 corpus 검증할 때는 문서 전체를 함부로 operator로 간주하지 않고 `reference`를
+기본으로 읽은 뒤 이 marker를 우선한다. 실행 명령이 아니라 CLI 이름을 사용해 흐름만 설명하는
+`text` fence도 명시적으로 `reference` 또는 `automation`으로 분류할 수 있다. marker가
+없는데 command처럼 보이는 `text` fence는 자동 수정하지 않고 reviewer가 분류할 신호로만 남긴다.
+
+## 검토 규칙
+
+- 같은 관리 호스트를 반복한다면 raw IP를 계속 쓰기보다 안정적인 SSH alias를 먼저 설명한다.
+- transfer, login, validation, observation, cleanup을 한 줄로 합쳐 인과를 숨기지 않는다.
+- validation과 destructive cleanup은 분리한다. 검증 실패를 보기 전에 증거를 지우면 안 된다.
+- 사람이 읽으며 작성해야 하는 작은 설정 파일은 생성용 `printf`보다 파일 내용을 먼저 보여 준다.
+- command substitution을 첫 학습 경로로 쓸 때는 그 값이 어디서 오는지 먼저 드러낸다.
+- troubleshooting의 첫 경로에서 stderr나 raw output을 숨기지 않는다.
+- multi-stage pipeline의 중간 출력이 개념 이해에 필요하면 나누거나 각 단계를 먼저 설명한다.
+- 명령 하나에 의미 단위 하나를 두는 편이 관찰 가능성을 높인다면 keystroke 절약보다 그쪽을 택한다.
+
+## 전역 금지 규칙이 아니다
+
+다음 문법 자체를 금지하지 않는다.
+
+- `sed`
+- `printf`
+- pipeline
+- command substitution
+- redirect
+- remote shell
+
+자동화나 reference가 목적이면 그대로 둘 수 있다. 핵심 질문은 **“이 표현이 기술적으로 맞는가?”만이
+아니라 “이 문서의 독자가 이 표현으로 시스템을 읽고 실패를 진단할 수 있는가?”**다.
+
+## 보존 경계
+
+command repair는 기술 의미를 단순화하는 작업이 아니다.
+
+- 대상 host/session을 바꾸지 않는다.
+- 파일의 의미와 보안 경계를 바꾸지 않는다.
+- SSOT/evidence에 없는 prerequisite, alias, 파일, 성공 결과를 발명하지 않는다.
+- command block 밖의 기존 산문은 editor가 직접 수정하지 않는다.
+- editor는 `CommandPatchSet`만 만들고 `scripts/apply-command-pedagogy-patch.py`가 원래 command
+  span에 patch를 적용한다.