지식을 파일로 — 왜 매번 결과가 다른가

이 차시에서 준비할 것

이 차시에서 처음 나오는 말

이 차시에서 배우는 것

• 결과가 매번 달라지는 원인을 지목할 수 있다 — 기준이 AI 머릿속에만 있기 때문
• 같은 일을 지식 없이 / 지식 파일과 함께 두 번 시켜 차이를 직접 확인한다
• 내 업무의 판단 규칙을 용어집 파일 한 장으로 뽑아낸다

1. 문제 상황 — 같은 양식, 다른 언어

냉장고 공장(가상)의 6개 분임조가 매일 생산보고서를 씁니다. 양식은 똑같습니다. 6개 공정 × (계획/생산/양품/불량/불량률/가동/비가동/비고). 그런데 쓰는 말이 전부 다릅니다.

날짜도 2026-07-02 / 26.7.2 / 20260702 세 가지, 합계도 합계 / 토탈 / 계 / TTL 네 가지로 씁니다.

왜 이 문제가 AI에게 딱 맞나: 사람이 취합하면 매일 반복되는 단순 노동이고, 엑셀 함수나 프로그램으로 짜기엔 표현의 변형이 너무 다양합니다. "빵꾸"와 "NG"와 "불량난거"가 같은 뜻임을 아는 것 — 이런 의미 기반 정리가 AI가 가장 잘하는 일입니다.

여러분 업무에도 같은 문제가 있을 겁니다. 팀마다 다른 항목명, 사람마다 다른 표기, 문서마다 다른 형식.

2. 실습 A — 지식 없이 그냥 시켜 보기

먼저 규칙을 주지 않고 시켜 봅니다. 실습 폴더의 xlsx 안에서 Claude Code를 실행합니다.

cd C:\harness-edu\xlsx; claude

cd ~/harness-edu/xlsx && claude

이 폴더의 생산보고서 6개를 하나로 통합해줘.

이제 대화를 비우고 똑같은 요청을 다시 합니다.

/clear

이 폴더의 생산보고서 6개를 하나로 통합해줘.

대개 셋 다 다릅니다. AI가 잘못한 것이 아닙니다 — 우리가 기준을 주지 않았습니다.

3. 개념 익히기 — 기준을 어디에 둘 것인가

3-1. 프롬프트에 다 적으면 되지 않나요?

물론 됩니다. "빵꾸는 불량으로, 데나오시는 재작업으로…" 를 요청문에 다 적으면 결과는 좋아집니다. 문제는 그 다음입니다.

하네스 4원리 중 두 가지
① 역할 분리 — "무엇을(스펙) · 누가(에이전트) · 어떻게(스킬)" 를 한 덩어리로 뭉치지 않습니다.
② 지식의 외부화 — 매핑 규칙·도메인 지식·표준 양식은 프롬프트가 아니라 파일에 둡니다. 지식이 바뀌어도 절차는 그대로입니다.

3-2. 스킬(Skill) — AI가 읽는 설명서

이렇게 밖으로 뺀 지식 파일을 이 과정에서는 스킬이라고 부릅니다. 이번 실습의 스킬은 엑셀 파일 하나입니다.

좋은 설명서의 3요소 — 내 업무 용어집을 만들 때도 이 세 가지가 들어가야 합니다.

3-3. "모르면 멈춰라" — 가장 중요한 규칙 하나

용어집에 없는 말이 나오면 어떻게 할까요? AI는 기본적으로 그럴듯하게 추측합니다. 그리고 그 추측이 데이터에 섞여 들어가면 나중에 찾아내기 어렵습니다.

그래서 이 실습의 지시서에는 이런 규칙이 들어 있습니다.

용어집에 없는 표현은 임의로 해석하지 말고
[미확인 용어] 목록으로 별도 보고

4. 실습 B — 지식을 주고 다시 시키기

이번에는 용어집과 지시서를 함께 씁니다. 지시서는 이미 xlsx/prompt.md 에 들어 있으니, AI에게 그 파일을 읽고 수행하라고 하면 됩니다.

/clear

이 폴더의 prompt.md 를 읽고, 거기 적힌 절차대로 수행해줘.

지시서에는 다음 5단계가 순서대로 적혀 있습니다. 실행되는 동안 화면에서 이 순서가 지켜지는지 보세요.

통합_생산보고서.xlsx
├ 라인별 표준보고   6개 라인 × 6개 공정, 합계·불량률은 엑셀 수식
├ 전사 집계        공정코드별 크로스탭 (공정 × 라인)
└ 이슈 요약        [조치요청] / [데이터 이상] / [미확인 용어] 분류

4-2. 결과 검수 — 눈으로 확인할 6가지

AI가 만들었다고 그대로 쓰지 않습니다. 검수도 실습의 일부입니다.

• 6개 공정명이 모두 표준용어 + 공정코드(P10~P60)로 통일되었는가
• 은어(빵꾸·데나오시·콤프 등)가 표준용어로 치환되었는가 — 손실 우려 시 (원문: ○○) 병기
• 숫자가 원본과 100% 같은가 (표현만 바뀌고 수치는 불변)
• 양품 + 불량 = 생산수량 크로스체크를 했는가
• 합계·불량률이 엑셀 수식으로 들어갔는가 (값만 박혀 있지 않은가)
• 치환 이력이 보고되었는가 — 나중에 추적할 수 있어야 합니다

4-3. 재현성 — 두 번 돌리면 같은가

2절에서 지식 없이 두 번 돌렸을 때 결과가 흔들리는 것을 이미 보셨습니다. 같은 비교를 지시서와 함께 했을 때가 이렇습니다.

5. 비교 정리 — 무엇이 달라졌나

이 차시의 한 문장 — 프롬프트는 절차만, 파일은 지식만 담당합니다. 이 분리가 하네스의 출발점입니다.

6. 사례 — 광고 AE의 용어집

1차시의 정하늘 대리가 자기 업무에서 머릿속 규칙을 파일로 꺼낸 결과입니다.

data/2026-07-W2_*.csv   지난주 (전주 대비 계산용)
data/2026-07-W3_*.csv   이번주
   네이버GFA   노출수 / 광고비(VAT별도) / 2026-07-13
   카카오모먼트 노출 / 소진금액(VAT포함)  / 26.7.13
   메타        Impressions / Results(목적에 따라 의미가 다름)
   구글애즈     Impr. / Cost / 2026/07/13
   틱톡        Imp / Spend / 20260713 (노출 600대 테스트 캠페인)
매체_표준용어집.md   ← 아래 ②의 완성본
prompt.md          ← 통합 지시서

cd C:\harness-edu\ad; claude

cd ~/harness-edu/ad && claude

내 업무 용어집을 만들려고 해.

업무: 매주 월요일, 5개 매체(네이버GFA·카카오모먼트·메타·구글애즈·틱톡)
     성과 데이터를 합쳐 광고주 주간 리포트를 만드는 일

용어 매핑:
- 노출수 / 노출 / Impr. / Impressions 는 "노출" 과 같은 뜻
- 소진액 / 광고비 / Cost / Spend 는 "집행액(VAT 별도)" 과 같은 뜻
- 전환 / 구매 / Purchases 는 "전환" 과 같은 뜻
- 단, 메타의 "결과" 컬럼은 캠페인 목적이 구매일 때만 전환으로 인정

형식 규칙:
- 날짜는 YYYY-MM-DD, 금액은 원 단위 정수에 천 단위 콤마
- 비율은 소수점 둘째 자리
- 매체명은 네이버GFA / 카카오모먼트 / 메타 / 구글애즈 / 틱톡 다섯 가지만 사용

금지 사항:
- 원본 수치 변경 금지
- 매체 리포트의 ROAS·CPA를 그대로 쓰지 말고 (전환매출 ÷ VAT별도 집행액)로 재계산
- 노출 1,000 미만 소재는 CTR을 계산하지 말고 "데이터 부족"으로 표시
- 용어집에 없는 컬럼은 추측하지 말고 [미확인] 으로 표시할 것

이 내용을 나의_업무_용어집.md 로 정리해줘.
"언제 쓰는지 / 무엇을 지키는지 / 예시" 세 부분이 들어가게 해줘.

data 폴더의 매체 파일 10개를 열어서, 컬럼 이름과 값 형식이 매체마다
어떻게 다른지 비교표로 정리해줘. 같은 뜻인데 다르게 적힌 항목,
단위·통화 기준이 다른 항목, 뜻이 애매한 컬럼을 각각 표시해줘.

6-1. 내 업무에 대입해 보기

세 가지만 떠올려 보세요. 적지 않아도 됩니다.

7. 실습 C — 용어집을 "스킬"로 만들어 자동으로 불리게 하기

지금까지는 매번 "용어집을 읽고" 라고 말했습니다. 한 번이라도 빼먹으면 4절 이전으로 돌아갑니다. 사람에게 의존하는 규칙은 언젠가 깨집니다.

같은 문서를 정해진 자리에 정해진 형식으로 두면, AI가 알아서 찾아 읽습니다. 그 형식이 스킬(Skill) 입니다.

7-1. 스킬은 형식이 하나뿐입니다

---
name: media-glossary
description: 광고 매체 성과 데이터를 다룰 때 사용. 컬럼 매핑, VAT 기준,
             전환 정의, 지표 재계산 규칙을 정의한다.
---

# 매체 성과 표준용어집

## 용어 매핑
...

## 금지 사항
...

7-2. 만들어 보기

매체_표준용어집.md 를 스킬로 만들어줘.

- 위치: .claude/skills/media-glossary/SKILL.md   (폴더 이름은 영문으로)
- 내용은 지금 용어집 그대로 옮기되, 맨 위에 name 과 description 을 붙여줘
- description 은 "광고 매체 성과 데이터를 통합하거나 주간 리포트를 만들 때 사용" 처럼
  언제 써야 하는지가 분명하게. 여기에 컬럼 매핑·VAT·전환 정의가 들어 있다는 것도 적어줘

다 만들면 description 한 줄만 다시 보여줘.

7-3. 진짜 자동으로 불리는지 확인

스킬은 Claude Code를 다시 켤 때 읽힙니다. 껐다 켜고, 용어집 얘기를 한 마디도 하지 않고 시켜 봅니다.

/exit

claude

data 폴더의 매체별 성과 파일을 하나로 통합해서 주간 리포트를 만들어줘.

7-4. description 한 줄이 전부를 결정합니다

본문은 아무리 잘 써도 description 이 부실하면 한 번도 안 읽힙니다.
스킬을 만든 뒤 이 한 줄만 소리 내어 다시 읽으세요. "내가 처음 보는 사람이라도, 이 문장으로 언제 써야 할지 알겠는가?"

description: 우리 팀 매체 용어 정리

description: 광고 매체(네이버GFA·카카오모먼트·메타·구글애즈·틱톡) 성과 데이터를
  통합하거나 주간/월간 리포트를 만들 때 반드시 사용. 매체별 컬럼 매핑, VAT 기준,
  전환 인정 조건, CTR·CPA·ROAS 재계산 식을 정의한다.
  단일 매체 원본을 그대로 확인만 할 때는 사용하지 않는다.

7-5. 새 용어를 표준으로 등록하기 — 스킬은 살아 있는 문서입니다

만들고 끝이 아닙니다. 업무는 계속 바뀝니다. 새 매체가 추가되고, 새 지표가 생기고, 기준이 개정됩니다. 그때마다 어떻게 하느냐가 이 스킬이 6개월 뒤에도 살아 있을지를 가릅니다.

등록은 세 단계입니다

새 매체 당근마켓 광고가 추가됐습니다. 파일은 ad/new/2026-07-W3_당근.csv 에 준비돼 있습니다 — 컬럼명이 또 다르고, 우리 표준에 없는 컬럼도 하나 섞여 있습니다.

data/ 가 아니라 new/ 에 따로 둔 이유: 앞 절의 정답 숫자(전환 5,705건·ROAS 366.9%)가 바뀌지 않게 하기 위해서입니다. 등록 절차만 연습합니다.

new/2026-07-W3_당근.csv 를 열어서 컬럼을 확인하고,
media-glossary 스킬의 용어 매핑 표에 당근마켓 행을 추가해줘.

- 우리 표준 항목(노출·클릭·집행액·전환·전환매출·캠페인·일자)에
  각각 어느 컬럼이 대응하는지 확인해서 넣어줘
- VAT 포함인지 별도인지, 날짜 형식이 무엇인지도 형식 규칙 표에 반영
- 확신이 안 서는 컬럼은 넣지 말고 [확인 필요] 로 표시해서 따로 알려줘

[확인 필요] 로 표시한 것 중 "노출당과금" 컬럼은 우리 표준에 없는 개념이야.
집계에 쓰지 말고, 리포트 비고란에만 원본 값을 표시하도록 규칙을 추가해줘.

스킬 문서 맨 아래에 "변경 이력" 표를 만들고 이번 변경을 기록해줘.
날짜 · 무엇을 · 왜 세 칸으로. 앞으로 수정할 때마다 여기에 한 줄씩 쌓을 거야.

## 변경 이력

| 날짜 | 무엇을 | 왜 |
|---|---|---|
| 2026-07-20 | 당근마켓 매핑 추가, 매체명 6종으로 확대 | 신규 매체 집행 시작 |
| 2026-07-20 | 노출당과금은 집계 제외, 비고 표시 | 우리 표준에 없는 개념 |

"왜" 칸이 가장 중요합니다. 반년 뒤 누군가 "이 규칙 왜 이래요?" 라고 물을 때, 답이 파일에 있으면 규칙이 유지되고 없으면 누가 마음대로 지웁니다.

무엇을 등록하고 무엇을 등록하지 않나

한 달에 한 번, 스킬을 점검합니다

media-glossary 스킬을 점검해줘.

1. data 폴더의 최근 파일들에 있는 컬럼 중 스킬 매핑 표에 없는 것을 찾아줘
2. 스킬에는 있는데 요즘 안 쓰는 매체·지표가 있으면 알려줘
3. 서로 충돌하거나 중복된 규칙이 있으면 지적해줘

고치지는 말고, 목록만 보여줘. 무엇을 반영할지는 내가 정할게.

6. 브랜드검색 캠페인의 전환은 "검색 유입 후 구매"라
   일반 디스플레이와 성격이 다르다. 통합 CPA 계산에 합산하지 말고
   별도 표로 분리한다. (2026-09-14 추가 — 9월 보고에서 CPA가
   비정상적으로 낮게 나온 원인이었음)

8. 스스로 점검

• 지식 없이 시켰을 때와 있을 때의 차이를 한 문장으로 설명할 수 있다
• 용어집을 스킬로 만들어, 말하지 않아도 적용되는 것을 확인했다
• description 이 스킬의 유일한 트리거라는 것을 안다
• 새 용어가 생겼을 때 파일에 등록하는 절차(추가 → 확정 → 이력)를 안다
• "다음에도 또 나오나?" 로 파일에 넣을지 프롬프트에 둘지 판단할 수 있다
• 통합_생산보고서.xlsx 가 생성되었고 검수 6항목을 확인했다
• 같은 지시를 두 번 돌려 구조가 같은지 비교했다
• 내 업무 규칙 5개를 뽑아 나의_업무_용어집.md 로 만들었다
• "모르면 멈춰라" 규칙을 내 용어집에도 넣었다

흔한 실패와 대처

9. 더 해보기 (선택)

• 용어집을 고쳐 보기 — 공정_표준용어집.xlsx 에 새 은어를 한 줄 추가하고 다시 실행하세요. 지시서는 건드리지 않아도 결과가 달라지는 것이 이 구조의 핵심입니다.
• 일부러 모르는 말 넣기 — 보고서에 없는 이상한 표현을 넣고 [미확인 용어] 로 잡히는지 확인하세요.
• 원본 교안 읽기 — xlsx/README.md 에 설계 의도와 심화 과제가 더 있습니다.

10. 다음 차시

지식을 파일로 꺼내니 결과가 안정됐습니다. 그런데 모든 일에 이만큼 준비가 필요할까요? 3차시에서는 "이 일은 몇 단계짜리 일인가" 를 판단하는 눈을 기릅니다 — 혼자 시킬 일, 팀을 붙일 일, 시스템으로 만들 일을 구분합니다.