지저분한 데이터에 하네스 붙이기

이 차시에서 준비할 것

이 차시에서 처음 나오는 말

이 차시에서 배우는 것

• 실무 데이터가 왜 그냥 안 되는지 직접 확인한다
• 처리 규칙을 스펙 문서로 못 박고, 그 스펙으로 팀을 만든다
• 결과를 원본과 대조해 검증한다 — 하네스의 마지막 조각
• (선택) 스펙 쓰는 규칙 자체를 스킬로 만들어 어느 업무에나 쓴다

1. 문제 — 실무 데이터는 깨끗하지 않다

소재는 서울시청 인근 업무추진비 집행 내역입니다. "공무원이 법인카드로 반복 방문한 식당 = 검증된 맛집"이라는 가설로 분석할 수 있는 데이터입니다.

1-1. 먼저 그냥 시켜 봅니다

cd C:\harness-edu\map; claude

cd ~/harness-edu/map && claude

식당리스트_실습용.csv 를 열어서 어떤 데이터인지 알려주고,
방문 횟수 상위 10개 식당을 표로 뽑아줘.

UnicodeDecodeError: 'utf-8' codec can't decode byte 0xc7 ...
→ 인코딩을 cp949 로 바꿔 재시도
→ 컬럼이 하나로 붙어 나옴 → 구분자가 쉼표가 아니라 탭이었음
→ 다시 파싱 → 겨우 상위 10개 추출

1-2. 이 데이터에 숨은 함정 네 가지

이 네 가지는 이 데이터에만 있는 특수 사정이 아닙니다. 사내 시스템에서 내려받은 엑셀, 팀마다 다르게 쓴 양식, 오래된 CSV — 실무 데이터는 대개 이렇습니다. 2차시의 "분임조 은어"와 같은 문제가 형태만 바꿔 나타난 것입니다.

2. 개념 — 스펙이 계약이다

4차시에서 팀을 만들 때 도메인·입력·산출물·품질 기준 네 줄을 적었습니다. 데이터 작업에서는 그 정도로 부족합니다. 처리 규칙까지 못 박아야 합니다.

스펙은 사람이 읽는 기획서가 아니라 AI가 실행하는 계약서입니다.
모호함 하나 = AI의 임의 결정 하나. "깔끔하게", "적절히", "보기 좋게" 같은 말이 들어가면 그만큼 결과가 흔들립니다.

3. 실습 A — 스펙 쓰기

AI에게 스펙부터 쓰게 합니다. 바로 작업시키지 않는 것이 핵심입니다.

식당리스트_실습용.csv 를 분석해 "시청 주변 맛집 랭킹 리포트" 를 만들려고 해.
바로 만들지 말고, 먼저 처리 규칙을 정한 스펙 문서를 MATZIP_SPEC.md 로 써줘.

스펙에 반드시 들어갈 것:
1. 파일 읽는 법 — 인코딩과 구분자를 실제로 확인해서 명시할 것
2. 집행장소 컬럼에서 상호와 주소를 분리하는 규칙
3. 같은 식당으로 볼 기준 (법인명·지점 표기 처리 방침)
4. 집계 항목 정의 — 방문 횟수, 총 집행액, 평균 단가, 최근 방문일
5. 제외 규칙 — 식당이 아닌 항목(매점 등)을 어떻게 다룰지
6. 검증 기준 — 결과가 맞는지 확인할 숫자 (총 건수, 총액 등)

각 규칙은 "적절히", "깔끔하게" 같은 말 없이 실행 가능한 문장으로 써줘.
정하지 못한 것은 [확인 필요] 로 남겨줘.

4. 실습 B — 스펙으로 팀 만들기

이제 그 스펙을 실행할 팀을 구성합니다. 4차시와 같은 방식이되, 스펙이 이미 있으므로 설명이 훨씬 짧아집니다.

하네스 구성해줘.

MATZIP_SPEC.md 를 유일한 요구사항 문서로 삼는다.
데이터 정제 → 집계·분석 → 검증 순서의 팀으로 만들어줘.

- 정제 담당: CSV 파싱, 상호·주소 분리, 명칭 통합
- 분석 담당: 식당별 집계와 랭킹, 구별·월별 분포
- 검증 담당: 원본과 결과를 대조. 총 건수·총액이 일치하는지 확인하고
  불일치를 발견하면 담당자를 지목해 수정 요청

스펙의 처리 규칙은 스킬 파일로 만들어 정제 담당이 참조하게 해줘.

5. 실습 C — 돌리고 검증하기

만든 팀으로 MATZIP_SPEC.md 에 따라 작업을 진행해줘.
결과는 맛집랭킹.md 로 저장하고, 검증 담당의 대조 결과도 함께 보고해줘.

5-1. 규칙 하나를 바꿔 보기

하네스의 진짜 값어치는 여기서 드러납니다. 스펙 한 줄만 고치고 다시 돌려 보세요.

MATZIP_SPEC.md 의 제외 규칙에 "매점·편의점·구내식당은 집계에서 제외" 를 추가하고,
그 스펙으로 다시 돌려줘. 바뀐 결과와 이전 결과의 차이를 알려줘.

6. 실습 D (선택) — 스펙 쓰는 규칙을 스킬로

선택 실습입니다. 건너뛰어도 다음 차시에 지장이 없습니다. 다만 스펙을 앞으로 계속 쓸 사람이라면 여기가 이 차시에서 가장 남는 부분입니다.

3절에서 스펙을 요구할 때, 프롬프트가 열 줄이 넘었습니다. "반드시 들어갈 것 여섯 가지", "적절히 같은 말 금지", "모르는 건 [확인 필요]" — 이걸 다음 프로젝트에서도 또 씁니다.

2차시의 판단 기준을 그대로 적용합니다. "다음에도 또 나오나?" → 예 → 파일로.
이번에 파일로 만들 것은 업무 지식이 아니라 "좋은 스펙이란 무엇인가"라는 기준입니다.

6-1. 만들기

방금 MATZIP_SPEC.md 를 쓸 때 내가 요구했던 조건들을 스킬로 만들어줘.
.claude/skills/spec-writer/SKILL.md

description 에 넣을 것 — 언제 쓰는지가 분명하게:
"데이터 처리·분석·자동화 작업을 시작하기 전에 요구사항 명세서를 쓸 때 사용.
 바로 작업에 들어가지 않고 스펙부터 확정해야 하는 모든 작업에 적용."

본문에 넣을 것:
1. 스펙에 반드시 들어갈 항목 — 입력(파일/형식/인코딩) · 처리 규칙 ·
   산출물 형식 · 제외 규칙 · 검증 기준 · 범위 밖(하지 않을 일)
2. 금지 표현 목록 — "적절히" "깔끔하게" "보기 좋게" "알아서" "필요시"
   이런 말이 들어가면 그만큼 AI가 임의로 결정한다는 것을 명시
3. 구체성 규칙 — 값은 실제 값으로 쓴다
   (인코딩은 "CP949", 구분자는 "탭", 기준은 "노출 1,000 미만" 처럼)
4. 모르는 것 처리 — 추측하지 말고 [확인 필요] 로 남긴다
5. 스펙 검수 3문항 — 구체적 값이 있는가 / 안 할 일이 적혔는가 /
   [확인 필요] 가 남아 있는가

파일만 만들고 실행은 아직 하지 마.

6-2. 다른 일에 써 보기

같은 폴더에서 쓰면 "아까 대화 때문"인지 구분이 안 됩니다. 완전히 다른 주제로 시험합니다. Claude Code를 껐다 켠 뒤 — 스킬은 재시작해야 읽힙니다.

/exit

claude

사내 회의실 예약 현황을 정리해서 "어느 회의실이 언제 노는지" 알려주는
작업을 하려고 해. 스펙부터 써줘. 아직 데이터는 없어.

6-3. 스킬에는 두 종류가 있습니다

두 번째 종류를 몇 개 갖고 있느냐가 실력 차이로 나타납니다. 스펙 쓰기 · 회의록 정리 · 보고서 검수 · 데이터 검증 — 이런 "일하는 방식"을 파일로 갖고 있으면 새로운 업무를 만나도 시작이 빠릅니다. 7차시에서 다룰 하네스 100선이 통째로 이 두 번째 종류입니다.

7. 스스로 점검

• 이 데이터가 "그냥은 안 되는" 이유 네 가지를 말할 수 있다
• 스펙을 먼저 쓰게 하는 이유를 "모호함 = 임의 결정" 으로 설명할 수 있다
• MATZIP_SPEC.md 에 인코딩·구분자가 구체적 값으로 적혀 있다
• 결과를 정답 숫자(15,144건 / 20.3억)와 대조했다
• "파일이 생성되었습니다" 와 교차 검증의 차이를 안다
• 스펙 한 줄을 고쳐 결과가 바뀌는 것을 확인했다
• (선택) 스펙 쓰는 규칙을 스킬로 만들어 다른 주제에 써 봤다
• (선택) 업무 지식 스킬과 일하는 방식 스킬의 차이를 설명할 수 있다

흔한 실패와 대처

8. 더 해보기 (선택)

• 지도로 만들기 — 이 데이터로 실제 웹앱까지 만드는 과정이 원본 교안에 있습니다. 주소를 좌표로 바꾸고(지오코딩) 지도에 올리는 단계까지 다룹니다 → map/README.md
• 명칭 통합 강화 — 창고43시청점 과 창고43 무교점 을 한 브랜드로 묶는 규칙을 스펙에 추가해 보세요. 랭킹이 어떻게 바뀌는지 봅니다.
• 내 업무 데이터로 — 지저분한 파일이 있다면 같은 순서로 해보세요. 스펙 먼저, 팀 그다음, 검증 마지막.

9. 다음 차시

여기까지 Agent(누가) 와 Skill(무엇을·어떻게) 을 다뤘습니다. 그런데 정제와 집계를 아무리 잘해도, AI가 계산이나 사실을 지어내면 결과를 믿을 수 없습니다. 6차시에서 마지막 축 Tool 로 그 문제를 막습니다.