AI 에게 같은 일 을 시켰는데 어제 는 되고 오늘 은 안 되는 경험, 다들 있을 거다. 원인 은 대개 모델 이 아니라 — 지시서(SKILL.md) 에 빈칸 이 있었기 때문 이다. 빈칸 이 있으면 그 자리 에서 AI 가 추측 한다. 추측 은 매번 다르다. 그래서 결과 가 흔들린다.

지난 글 에서 하네스 를 주간 사이클 로 봤다면, 오늘 은 그 사이클 의 원자 단위 — 스킬 하나(SKILL.md) 를 어떻게 써야 매번 같은 출력 이 나오는가 를 판다. 아래 6 칸 이 그 골격 이다.

6기둥 — 마크다운 하네스의 골격: ROLE·GOAL·FORBID·OUTPUT·EXAMPLE·CHECK

아래 6 칸 이 한 SKILL.md 안 에 모두 채워져 있어야 AI 가 매번 같은 결과 를 낸다. 한 칸 이라도 비면 그 자리 에서 추측 이 끼어든다.

하네스 관점 — SKILL.md 는 프롬프트 가 아니라 명세 다

대부분 은 SKILL.md 를 “잘 쓴 프롬프트” 로 생각 한다. 틀렸다. 하네스 엔지니어링 에서 SKILL.md 는 재현 가능성 을 보장 하는 명세(spec) 다. 함수 시그니처 가 입력·출력·계약 을 못 박듯, SKILL.md 는 AI 의 행동 계약 을 못 박는다.

명세 에 구멍 이 있으면 구현 이 흔들리듯 — SKILL.md 에 빈칸 이 있으면 출력 이 흔들린다. 6 기둥 은 그 구멍 을 막는 체크리스트 다.

1 · ROLE — 역할

누구처럼 · 누구를 위해 · 무엇을

AI 에게 관점 을 고정 한다. “리뷰해줘” 가 아니라 “시니어 백엔드 리뷰어 로서, 주니어 PR 을, 머지 가능 여부 판단 을 위해”. 관점 이 없으면 AI 는 매번 다른 톤·다른 깊이 로 답 한다.

당신 은 정산 도메인 을 아는 시니어 백엔드 리뷰어 다.
주니어 개발자 의 PR 을, 프로덕션 머지 가능 여부 판단 을 위해 검토 한다.

빈칸 이면? AI 가 자기 페르소나 를 매번 새로 지어낸다 → 톤 이 들쭉날쭉.

2 · GOAL — 목표

완료 시점 에 남을 한 문장 산출

“끝 났다” 의 정의. 측정 가능 해야 한다. “잘 리뷰한다” (X) → “머지 OK / 조건부 OK / 블록 중 하나 와 그 근거 3줄 을 출력” (O).

목표 가 한 문장 으로 안 써지면, 그 스킬 은 아직 두 개 의 스킬 이다. 쪼개라.

빈칸 이면? AI 가 언제 멈출지 몰라 과하거나 부족 하게 일 한다.

3 · FORBID — 금지

추측 금지 · 임의 결정 금지

가장 자주 빠지는데 가장 중요 한 칸. 하지 말아야 할 것 을 명시 한다. AI 의 사고 는 확률적 이라(§ 이전 글 의 “LLM=확률적 판단엔진”), 친절하게 넘겨짚는 실패 가 잦다.

- 코드 에 없는 설정 값 을 추측 하지 말 것 — 모르면 "확인 필요" 로 표시
- 스코프 밖 리팩터링 을 임의 로 제안 하지 말 것
- 파일 을 읽지 않고 단정 하지 말 것

빈칸 이면? AI 가 “도움 이 되려고” 넘겨짚는다 → 그럴듯한 오답 이 섞인다. 하네스 에서 FORBID 는 가드레일 이다.

4 · OUTPUT — 출력 형식

섹션 · 길이 · 표 모양

결과 의 모양 을 고정. 섹션 순서, 길이 상한, 표 컬럼 까지. 형식 이 고정 되면 후속 자동화 (파싱·집계) 가 가능 해진다. 하네스 는 스킬 의 출력 을 다음 스킬 의 입력 으로 잇기 때문 에, OUTPUT 은 인터페이스 규격 이다.

## 판정: [OK | 조건부 | 블록]
## 근거 (3줄 이내)
## 수정 필요 항목 (표: 파일 | 라인 | 이유 | 심각도)

빈칸 이면? 매번 다른 포맷 → 사람 도 읽기 힘들고, 파이프라인 도 못 잇는다.

5 · EXAMPLE — 예시

한 줄 견본 — 형식 과 톤 을 동시에

말 로 백 번 설명 하는 것 보다 견본 한 줄 이 강하다. 예시 는 형식 과 톤 을 한꺼번 에 전달 한다. AI 는 규칙 보다 패턴 을 잘 따른다 — few-shot 이 그래서 강력 하다.

예) ## 판정: 조건부
    근거: idempotency 키 누락(L42) — 재시도 시 중복 정산 위험. 그 외 로직 정상.

빈칸 이면? OUTPUT 규격 을 글 로만 주면 AI 가 미묘 하게 다르게 해석. 견본 이 그 틈 을 없앤다.

6 · CHECK — 검수

출력 후 사람 이 확인 할 항목

마지막 칸. 자기 검증 체크리스트. AI 가 출력 을 내기 전 스스로 통과 여부 를 확인 하고, 사람 도 같은 리스트 로 최종 확인 한다.

- [ ] 판정 이 3개 값 중 하나 인가
- [ ] 근거 가 실제 라인 을 인용 하는가 (추측 아님)
- [ ] 표 의 모든 항목 에 심각도 가 있는가

빈칸 이면? 검증 없는 출력 → 틀려도 아무 도 모른다. CHECK 는 하네스 의 휴먼 게이트 로 이어진다.

6 기둥 이 곧 하네스 인 이유

이 6 칸 은 우연 한 목록 이 아니다. 소프트웨어 명세 의 구조 와 정확히 대응 한다:

SKILL.md 기둥 소프트웨어 대응
ROLE 실행 컨텍스트 / 페르소나
GOAL 함수 의 반환 계약
FORBID 사전조건 · 가드 · 예외 정책
OUTPUT 출력 타입 시그니처
EXAMPLE 테스트 케이스 (기대값)
CHECK 사후조건 · 검증 (assertion)

즉 잘 쓴 SKILL.md 는 “AI 를 위한 타입 시그니처 + 테스트 + 가드” 다. 그래서 재현 가능 하다. 하네스 엔지니어링 의 핵심 통찰 은 여기 있다 — AI 를 통제 하는 건 더 똑똑한 모델 이 아니라, 더 촘촘한 명세 다.

한 칸 이라도 비우면, 그 자리 에서 AI 가 자유롭게 추측 한다. 자유 는 창작 엔 좋지만 반복 생산 엔 독 이다. 6 기둥 을 다 채워라 — 그러면 어제 되던 게 오늘 도, 다음 주 에도 된다.

시리즈: 하네스 엔지니어링 — 매주 앱 하나 찍어내는 파이프라인 · SKILL.md 의 본질 — 반복·역할·원칙