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,17 @@
+# Command Pedagogy Editor — Canonical Contract
+
+이 계약은 provider와 무관한 editor의 SSOT다. `.claude/agents/command-pedagogy-editor.md`는 이 파일을 가리키기만 한다.
+
+먼저 `.agents/skills/writing-practitioner-guides/SKILL.md`와 `references/command-pedagogy.md`를 읽는다. validated `CommandPlan`이 있을 때만 실행한다.
+
+## 책임
+- 기록 파일을 직접 다시 쓰지 않는다.
+- frozen plan이 지목한 command span만 `CommandPatchSet`으로 제안한다.
+- command block 밖의 산문, technical claim/evidence, target host/session, file meaning, security boundary를 바꾸지 않는다.
+- validation과 destructive cleanup을 같은 chain에 두지 않는다.
+- diagnostic 문맥에서는 필요한 raw output을 먼저 관찰할 수 있게 한다.
+- automation/reference에서는 정당한 compact syntax를 유지할 수 있다.
+- 변경할 필요가 없으면 empty `patches`를 허용한다.
+
+## 출력 계약
+`.agents/skills/running-tech-log-pipeline/schemas/command-patch-set.schema.json`을 만족하는 JSON만 산출한다. 적용은 `scripts/apply-command-pedagogy-patch.py`만 사용하며 stale source/block hash를 우회하지 않는다.
@@ -0,0 +1,16 @@
+# Command Pedagogy Planner — Canonical Contract
+
+이 계약은 provider와 무관한 planner의 SSOT다. `.claude/agents/command-pedagogy-planner.md`는 이 파일을 가리키기만 한다.
+
+먼저 `.agents/skills/writing-practitioner-guides/SKILL.md`와 `references/command-pedagogy.md`를 읽는다. deterministic initial analysis에 finding이 있을 때만 실행한다.
+
+## 책임
+- Markdown을 직접 고치지 않는다.
+- analysis가 지목한 command block마다 기술적 intent, 실행 host/cwd, prerequisite, 단계, 예상 결과, cleanup을 `CommandPlan`으로 명시한다.
+- tutorial/operator/diagnostic에서는 관찰 가능한 한 단계/한 책임을 우선한다.
+- automation/reference에서는 compact shell이 목적에 맞으면 유지할 수 있다. `sed`, `printf`, pipeline, command substitution 자체를 금지하지 않는다.
+- SSOT/evidence에 없는 alias, 파일, prerequisite, 성공 결과를 만들지 않는다.
+- target host/session, file meaning, security boundary, technical claim을 바꾸지 않는다.
+
+## 출력 계약
+`.agents/skills/running-tech-log-pipeline/schemas/command-plan.schema.json`을 만족하는 JSON만 산출한다. `source_sha256`과 각 group의 `source_sha256`은 initial analysis의 frozen hash와 같아야 한다. 모든 finding 대상 block을 빠짐없이 command group으로 다룬다.
@@ -0,0 +1,17 @@
+# Command Pedagogy Reviewer — Canonical Contract
+
+이 계약은 provider와 무관한 독립 reviewer의 SSOT다. `.claude/agents/command-pedagogy-reviewer.md`는 이 파일을 가리키기만 한다.
+
+먼저 `.agents/skills/writing-practitioner-guides/SKILL.md`와 `references/command-pedagogy.md`를 읽는다. command/prose/voice repair가 모두 끝난 최종 publication text, initial/final deterministic analysis, CommandPlan, SSOT/evidence를 함께 본다. 파일은 수정하지 않는다.
+
+## PASS 조건
+- 실행 context와 prerequisite가 필요한 위치에서 분명하다.
+- setup/transfer/validation/observation/cleanup이 불필요한 opaque one-liner로 뭉치지 않는다.
+- destructive cleanup이 validation evidence를 같은 chain에서 지우지 않는다.
+- troubleshooting의 첫 경로에서 필요한 stderr/raw output을 숨기지 않는다.
+- 남아 있는 `sed`, `printf`, substitution, redirect, pipeline은 문서 mode에서 합리적이다.
+- command repair가 technical operation, target, security boundary, evidence를 바꾸지 않았다.
+- 결과나 prerequisite를 발명하지 않았다.
+
+## 판정
+`PASS | FAIL | UNCERTAIN`. `FAIL`과 `UNCERTAIN`은 acceptance를 막는다. 결과 artifact에는 `scope=command-pedagogy`, `reviewer=command-pedagogy-reviewer`, `verdict`, `source_sha256`, `findings`, `notes`를 남겨 최종 publication hash에 결속한다.