69 lines
3.4 KiB
Markdown
69 lines
3.4 KiB
Markdown
# 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를 적용한다.
|