3.4 KiB
3.4 KiB
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를 좁힐 수 있다.
<!-- 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 절약보다 그쪽을 택한다.
전역 금지 규칙이 아니다
다음 문법 자체를 금지하지 않는다.
sedprintf- 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를 적용한다.