한 덩어리였던 단어시험지 Skill. 오류발생 시 수정을 위해 upgrade
2026.08.11
## 한 줄 요약
1주차에 만든 vocabulary-test-maker를 입력 검수, 시험지 생성, 독립 검증의 세 작은 Skill로 나누고, 상위 Umbrella가 실행 순서와 실패 반환을 맡도록 연결했다. 공개용 가상 단어 10개로 실제 실행한 결과 정상 입력은 PASS, 오류 입력은 partial과 Human Gate HOLD로 구분됐다.
## 왜 1주차 Skill을 다시 보게 됐나
1주차에는 단어 목록 하나를 넣어 학생용 시험지와 정답지를 만드는 데 성공했다. 하지만 하나의 Skill 안에 다음 일이 모두 들어 있었다.
- 입력 형식과 중복 확인
- 문제 순서와 시험지 형식 결정
- 학생용 시험지와 정답지 생성
- 문항 수·정답·답 노출 검증
- 실제 배포 전 교사 승인
처음에는 한 번에 처리돼 편했지만, 오류가 생겼을 때 어디를 고쳐야 하는지가 흐렸다. 입력이 잘못된 문제와 정답지 순서가 어긋난 문제는 실패 원인도, 확인 방법도, 수리 방법도 달랐다.
## 원본과 작업 사본을 먼저 분리했다
기존 Skill은 learner-owned 원본으로 보존하고, 2주차 작업은 별도 working copy에서 진행했다. 후보 파일을 만들기 전 자동 백업을 수행하고 파일별 SHA-256을 대조했다. 백업 payload를 새 경로에 복사해 다시 해시를 비교하는 복원 리허설도 PASS였다.
작업 중 변경 전 백업 영수증은 총 10개가 남았고 모두 PASS다. 배포받은 수업 자료나 기존 1주차 원본은 수정하지 않았다.
## 전체 절차를 빠짐없이 펼쳐 본 결과
요청을 받는 순간부터 실제 외부 배포 전까지 절차를 18개로 펼쳐 분류했다. 그 결과 작은 Skill로 분리할 경계는 세 곳이었다.
1. `vocabulary-list-validator`
word | meaning 목록을 읽고 유효 항목, 형식 오류, 중복을 구분한다.
2. `vocabulary-test-composer`
검수된 pair와 제목·배점·seed를 받아 학생지와 정답지를 같은 순서로 만든다.
3. `vocabulary-test-verifier`
생성기와 독립적으로 문항 수, 순서, 입력 뜻, 학생용 답 노출, 재현성을 판정한다.
제 판단으로 실제 인쇄·배포 승인은 아직 별도 Skill로 만들지 않았다. 현재는 단어시험에만 쓰고 있고 외부 행동도 없으므로, 상위 Umbrella 안의 교사 Human Gate로 유지하는 편이 더 단순했다.
## 나누지 않고 남긴 것
모든 작은 동작을 Skill로 만들지는 않았다.
- 제목·배점·문항 수 결정: 전체 요청을 조정하므로 Umbrella 내부
- pair를 섞는 동작: 독립 판단이 없는 Composer의 지원 코드
- 파일 쓰기와 SHA-256 계산: 각 Skill의 지원 코드
- 중복을 유지할지 판단: 교사가 결정하므로 Human Gate
- 실제 인쇄·발송·게시: 이번 Skill Tree 밖의 별도 작업
이렇게 나누니 “작은 함수”와 “독립적인 책임을 가진 Skill”이 같은 것은 아니라는 점이 보였다.
## 만든 Interface
각 후보에 공통으로 다음 경계를 적었다.
name / role / use_when / input / steps / output / verifier / failure_return가장 중요한 연결은 파일 이름보다 출력 계약이었다.
Validator → validation-report.json
Composer → test.md + composition-receipt.json
Verifier → proof.json
Umbrella → 다음 Skill 선택 또는 실패 책임으로 반환
## Umbrella Tree: 어디에 속하는가
vocabulary-test-maker-umbrella
├─ vocabulary-list-validator
├─ vocabulary-test-composer
├─ vocabulary-test-verifier
└─ Human Gate: 교사 배포 승인
└─ 실제 print/send/publish는 Tree 밖 별도 작업## Circuit: 무엇이 전달되고 어디로 돌아가는가
Teacher request
↓
Umbrella(scope + spec)
↓
Validator ── malformed/duplicate ──→ 교사 판단 → Validator
↓ validation JSON
Composer ── invalid spec ─────────→ Umbrella → Composer
↓ test.md + composition receipt
Verifier ── input/count error ────→ Validator
├────── order/answer error ────→ Composer
└────── PASS
↓
Human Gate ── HOLD/REJECT ────────→ 해당 책임 Skill
└────── APPROVE → 별도 배포 작업Tree의 선은 소속만 나타내고, Circuit의 화살표는 실행·전달·실패 반환만 나타내도록 구분했다.
## 테스트를 먼저 실패 시킨 뒤 구현했다
세 실행 스크립트는 테스트를 먼저 만들고, 해당 스크립트가 없어 실패하는 것을 확인한 뒤 최소 구현했다.
입력 검수 테스트: RED → GREEN
시험지·정답지 순서 대응 테스트: RED → GREEN
정상 산출물 검증 테스트: RED → GREEN
정답 변조 검출 테스트: RED → GREEN
최종 자동 테스트: 4개 모두 OK후보 문서를 처음 기록할 때 본문이 잘린 문제가 한 번 있었다. 파일이 생성됐다는 메시지만 믿지 않고 다시 읽어 파일 크기와 내용을 확인했기 때문에 발견했다. 즉시 백업한 뒤 네 SKILL.md를 전체 내용으로 다시 기록했고, frontmatter·본문·잘림 문자열 검사를 모두 통과시켰다.
## 정상 입력으로 전체 Circuit을 실행했다
학생 정보나 실제 내부 단어장은 사용하지 않고 공개 가능한 가상 단어 10개를 사용했다. seed는 1주차와 같은 23으로 고정했다.
Validator: status=pass valid=10 issues=0
Composer A: status=pass selected=10 seed=23
Composer B: status=pass selected=10 seed=23
Verifier: verdict=PASS checks=5 repair_target=None두 번 생성한 시험지의 SHA-256도 같았다.
run A: b9dced4497ca4723417b9678454587aed81fbef6a1948720c49cc365bab9f8cd
run B: b9dced4497ca4723417b9678454587aed81fbef6a1948720c49cc365bab9f8cd
identical: true문항 순서는 gather, improve, effort, familiar, compare, benefit, journey, achieve, ancient, decide로 동일했고, 학생용 영역에는 한글 뜻이 노출되지 않았다.
## 오류 입력에서는 실패를 숨기지 않았다
중복 1개, 구분자 누락 1개, 빈 뜻 1개가 있는 입력도 실행했다.
Validator: status=partial valid=2 issues=3
Composer: status=partial selected=2 seed=23
Verifier Code Gate: PASS
Human Gate: HOLD여기서 중요한 점은 Code Gate와 Human Gate가 다르다는 것이다. 만들어진 2문항의 구조와 정답 대응은 맞아서 코드 검사는 통과했지만, 입력 이슈 3개가 해결되지 않았으므로 교사 승인 단계에서는 배포를 보류해야 한다.
## 결과와 배운 점
이번 분해로 문제가 생겼을 때 전체 Skill을 다시 고치지 않고 책임 지점으로 돌아갈 수 있게 됐다.
- 입력 오류는 Validator
- 문항 순서·정답 오류는 Composer
- 완료 주장과 증거 판정은 Verifier
- 실제 배포 결정은 교사 Human Gate
분해의 목적은 Skill 수를 늘리는 것이 아니라 실패 원인과 수리 범위를 작게 만드는 것이었다. 또한 파일이 생겼다는 메시지가 아니라 readback과 실제 실행 결과가 완료 증거라는 점도 확인했다.
## 기본과제 실행 당시 상태
- 학습자 선택 반영: 완료
- 작은 Skill 후보 3개 작성·readback: 완료
- Umbrella Tree와 Circuit: 완료
- 자동 테스트 4개: 통과
- 정상 입력 전체 실행: PASS
- 오류 입력: partial, Human Gate HOLD
- W2 최소 통과 상태: PASS
- 이 기본과제 단계에서는 Hermes 런타임 자동 발견: not_checked (후속 확장 사례에서 실제 설치·검증)
- 이 기본과제 단계에서는 실제 학생 단어장 적용: not_checked (후속 OCR 확장 사례에서 스캔 샘플 적용)
- 실제 인쇄·배포·외부 게시: 미실행


한 덩어리였던 단어시험지 Skill을 단순히 작은 함수로 쪼개지 않고, 입력 검수·생성·독립 검증이라는 서로 다른 실패 책임으로 나눈 점이 좋았습니다. Validator의 JSON, Composer의 시험지와 영수증, Verifier의 proof를 출력 계약으로 연결하고 Umbrella에는 순서와 실패 반환만 남겨 Tree의 소속과 Circuit의 실행 화살표도 구분했어요.
가상 단어 10개와 seed 23으로 두 번 만든 시험지의 SHA-256이 같았고, 오류 입력에서는 중복·구분자 누락·빈 뜻 3건을 남긴 채 유효한 2문항만 `partial`로 생성했습니다. 두 문항의 구조는 Code Gate를 통과했지만 입력 이슈가 남아 Human Gate는 `HOLD`였다는 결과가 특히 중요합니다. 파일이 잘려 저장된 실패도 생성 메시지로 넘기지 않고 readback으로 찾아 네 문서를 다시 기록했고, 이 단계의 Hermes runtime discovery는 `not_checked`로 분리했습니다.
Skill 수를 늘리는 데서 멈추지 않고 실패가 돌아갈 책임 지점을 작게 만든 분해가 선명했어요. 오류 입력에서도 구조 PASS와 배포 HOLD를 함께 남긴 덕분에 자동 검증과 교사 판단의 경계가 실제 실행으로 보였습니다.