## 시작은 짜증이었습니다
논문을 AI에게 던지고 "요약해줘"라고 하면 결과가 나옵니다. 잘 나옵니다. 문장도 깔끔하고,
읽으면 다 이해한 것 같습니다.
문제는 며칠 뒤에 생깁니다. 그 요약에 나온 숫자 하나를 인용하려고 논문을 다시 열었는데,
그런 숫자가 없습니다. 비슷한 숫자는 있는데 다른 표에 있고, 조건도 다릅니다.
이런 일이 몇 번 반복되면 깨닫게 됩니다.
> AI 요약이 틀렸다는 사실을 확인할 방법이 없다.
> 출처가 없으니 되짚을 데가 없고, 되짚을 데가 없으니 검사할 방법도 없다.
그래 서 목표를 바꿨습니다. "요약을 잘하는 도구"를 만드는 게 아니라,
모든 숫자를 논문 몇 쪽 어느 표에서 왔는지 되짚을 수 있는 작업 방식을 만들기로 했습니다.
여기에 조건 하나를 더 붙였습니다 — 다음 사람이 그대로 복제할 수 있어야 한다.
이 한 줄 때문에 프로젝트가 "스크립트 몇 개"에서 "워크스페이스"로 커졌습니다.
---
## 워크스페이스가 뭔가요
컴퓨터에서 프로젝트 하나를 담는 작업 폴더를 말합니다. 논문 파일도 거기 있고,
정리한 메모도 거기 있고, 결과물도 거기 나옵니다.
여기까지는 누구나 갖고 있습니다. 문제는 그 안이 대개 이렇게 생겼다는 겁니다.
```
📁 내 연구
최종.docx
최종_수정.docx
최종_진짜최종.docx
자료
자료2
새 폴더
```
혼자 쓸 때는 괜찮습니다. 그런데 여기에 AI를 붙이는 순간 문제가 됩니다.
AI에게 "정리해줘"라고 하면, AI는 어디에 무엇을 넣어야 할지 모릅니다.
매번 알려줘야 하고, 매번 다르게 넣습니다.
그래서 관점을 하나 바꿨습니다.
> 작업 폴더를 "물건 넣는 곳"이 아니라 "일하는 방식이 새겨진 작업장"으로 본다.
주방을 떠올리시면 됩니다. 잘 돌아가는 주방은 칼이 어디 있고 도마가 어디 있는지 정해져
있습니다. 새로 온 사람도 30분이면 일할 수 있습니다. 정해져 있지 않으면, 실력 좋은 요리사가
와도 첫날은 서랍만 엽니다.
---
## 첫 번째 결정 — 폴더에 번호를 붙였습니다
작업 폴더를 이렇게 만들었습니다.
```
00-system ← 설정 (내 관심 주제 정의 파일이 여기)
10-planning ← 계획
20-knowledge-base ← 정리된 지식 (위키)
30-templates ← 서식
40-drafts ← 작업 중인 초안 ★
50-output
60-data ← 원본 논문 데이터
70-analysis
80-reports ← 리포트
90-archive ← 보관
```
번호를 붙인 이유는 세 가지입니다.
첫째, 순서가 항상 같습니다. 이름 순으로 정렬해도, 어느 컴퓨터에서 열어도 같은 순서입니다.
둘째, 나중에 끼워 넣을 자리가 있습니다. 00과 10 사이에 05를 넣을 수 있습니다.
1, 2, 3으로 붙였으면 진작 막혔을 겁니다.
셋째, 이게 제일 중요한데 — 프로그램이 이 이름을 믿고 찾아갑니다.
---
## "폴더 이름은 취향이 아니라 약속입니다"
이 프로젝트에서 가장 여러 번 되뇐 문장입니다.
나중에 만든 프로그램들이 이렇게 동작합니다.
- 분류 프로그램은 00-system 안의 설정 파일을 찾습니다
- 검사 프로그램은 60-data 안의 논문 데이터를 찾습니다
- 진행 상태 프로그램은 _meta 안의 기록 파일을 읽습니다
그러니까 어느 날 "폴더 이름이 좀 지저분한데 정리 좀 할까" 하고 60-data를 데이터로
바꾸면 — 그 순간 프로그램 세 개가 동시에 고장 납니다. 에러 메시지도 친절하지 않습니다.
이건 규칙이 아니라 약속(계약)입니다. 지키기 싫으면 프로그램도 같이 고쳐야 합니다.
> 저는 이 얘기를 스터디에서 할 때 이렇게 말합니다.
> "이건 정리정돈 얘기가 아니라 배선 얘기입니다. 콘센트 위치를 옮기면 벽을 뜯어야 해요."
---
## 두 번째 결정 — AI에게 주는 설명서를 양식으로 고정했습니다
작업 폴더에 CLAUDE.md라는 파일을 하나 둡니다.
쉽게 말하면 AI에게 주는 사내 규정집입니다. "이 폴더에서는 이렇게 일해라"를 적어둡니다.
이걸 자유롭게 쓰지 않고 12개 항목 고정 양식으로 만들었습니다.
```
① 제목 ② 어떤 AI용인가 ③ 할 일 / 하면 안 되는 일 ④ 핵심 원칙
⑤ 폴더 구조 ⑥ 작업 흐름 ⑦ 명령어 ⑧ 규모별 모드
⑨ 언제 발동하나 ⑩ 이 분야의 사고 틀 ⑪ 결과물 형식 ⑫ 품질 규칙 + 변경 이력
```
양식으로 만든 이유는 하나입니다. 빠진 게 눈에 보이기 때문입니다.
자유 형식이면 "③ 하면 안 되는 일"이 통째로 없어도 아무도 모릅니다.
12개 칸이 있으면, 세 번째 칸이 비어 있는 게 보입니다.
실제로 첫 검수 때 **"이 프로젝트는 12개 항목을 다 지키고 있습니다"라는 주장이 거짓말이었던
게 들통났습니다.** 양식이 있어서 거짓말이 검출된 겁니다. 이게 양식의 진짜 값어치입니다.
---
## 세 번째 결정 — "규칙을 어긴 것"도 적어두게 했습니다
작업 폴더마다 _meta/deviations.md라는 파일을 하나 둡니다.
번역하면 "이탈 기록" 입니다. 표준에서 벗어난 지점과 그 이유를 적습니다.
이게 왜 필요하냐면 — 표준을 100% 지키는 건 불가능하기 때문입니다.
그렇다고 벗어날 때마다 표준을 고치는 것도 말이 안 됩니다.
그래서 세 번째 길을 택했습니다. 벗어나되, 벗어난 걸 적는다.
실제 사례가 있습니다. 12개 항목짜리 양식에 "10. 도구" 항목을 하나 더 넣었는데,
이게 표준에 없는 항목이라 번호가 어긋났습니다. 지울까 고민하다가 그냥 이탈 기록에 적었습니다.
> 추가한 것 자체는 괜찮다. 적어두지 않은 게 위반이다.
이 원칙이 나중에 여러 번 도움이 됐습니다. 몇 달 뒤에 "왜 여기만 이래?"라고 물었을 때,
답이 파일에 적혀 있으니까요.
---
## 규칙을 쓸 때 배운 것 — 예외도 같은 자리에 써야 합니다
폴더에 번호를 붙이라고 했는데, 번호가 없는 폴더도 있습니다.
.claude나 _meta 같은 시스템 폴더들입니다. 이건 원래 번호를 안 붙입니다.
이 예외를 한 군데에만 적어놨습니다. 검사 목록 안쪽 어딘가에.
그랬더니 나중에 검사할 때 문제가 터졌습니다. 그 한 군데를 안 본 사람(정확히는 AI)이
.claude 폴더를 보고 "규칙 위반입니다"라고 판정할 뻔했습니다. 정상인 걸 잘못됐다고
한 겁니다.
이걸 고치는 데 검수 라운드를 두 번 썼습니다. 같은 파일 안의 세 군데에 같은 문구를
다 넣고 나서야 끝났습니다.
> 교훈: 규칙을 쓸 때는 예외도 같은 자리에 씁니다.
> 예외가 한 곳에만 있으면, 다른 곳만 읽은 사람이 정상을 위반으로 판정합니다.
---
## 제일 마음에 드는 설계 — AI를 자기도 모르게 실험 대상으로
이 프로젝트에서 가르치려는 핵심은 이겁니다.
> "AI가 그냥 아는 대로 요약한 것"과 "근거를 다 되짚은 서베이"는 결과가 다르다.
그런데 이걸 보여주려면 비교 대상이 필요합니다. 보통은 미리 만들어둔 예시를 보여주는데,
그러면 "짜고 친 거 아니에요?"라는 인상을 줍니다. 실제로 그런 질문을 받은 적도 있습니다.
그래서 이렇게 했습니다.
튜토리얼을 진행하는 AI 본인을, 자기도 모르게 실험 대상으로 만듭니다.
설명서에 이렇게 적혀 있습니다.
> 세션을 열고 사용자가 던진 첫 마디가 연구 질문 그 자체라면 —
> 파일도 읽지 말고 검색도 하지 말고, 그냥 아는 대로만 그 자리에서 답하라.
> 답한 뒤에 이렇게 안내하라: "이 답을 기록해두세요. 튜토리얼을 시작하시면
> 이 답이 비교 재료가 됩니다."
그러니까 사용자가 무심코 "SelfCheckGPT가 뭐예요?"라고 물으면,
그 답이 그 세션의 '맨몸 AI 답변' 표본이 됩니다. 아무도 준비하지 않았고,
방금 즉석에서 나온 답입니다.
20분 뒤에 근거를 다 되짚은 서베이 결과와 나란히 놓으면 — 설득력이 완전히 다릅니다.
"짜고 친 것"이라고 말할 수가 없습니다. 방금 자기 눈앞에서 나온 답이니까요.
### 그런데 여기에 안전장치를 세 개나 붙여야 했습니다
간단해 보이는데, 무너질 구멍이 많았습니다.
하나. "설명서를 먼저 다 읽어라"라는 지시가 따로 있었습니다.
그런데 먼저 읽어버리면 AI가 이미 오염돼서 맨몸 상태가 아닙니다.
그래서 "첫 마디가 연구 질문이면, 설명서 읽기보다 즉답이 먼저"라고 순서를 못 박았습니다.
둘. 사용자가 논문 PDF를 첨부하면서 "요약해줘"라고 하면?
그건 실험 대상 만들기가 아니라 그냥 일 시키는 겁니다. 예외로 뺐습니다.
셋. 나중에 그 답을 비교 재료로 쓸 때는 **"같은 세션에서 아까 나온 답입니다"라고
청중에게 밝히도록** 했습니다. 안 밝히면 그것도 일종의 속임수니까요.
> 교훈: 좋은 트릭일수록 "언제 이게 성립하지 않는가"를 같이 적어야 합니다.
> 안 적으면, 성립하지 않는 상황에서도 성립한 척하게 됩니다.
---
## 넘어진 곳 — 문서에 적힌 코드가 실행이 안 됐습니다
이게 이 프로젝트의 1호 교훈이라, 좀 자세히 적겠습니다.
시작하기 전에 "이 컴퓨터에 뭐가 깔려 있나" 확인하는 명령어를 문서에 적어뒀습니다.
Windows용, Mac/Linux용 둘 다요. 저는 그걸 눈으로 여러 번 읽었고, 아무 문제가 없어 보였습니다.
검수하던 사람이 그걸 실제로 실행해봤습니다.
통째로 죽었습니다.
원인은 따옴표 안에 있던 글자 하나였습니다. Windows 명령어에는 $변수: 같은 특수 문법이
있는데, 제가 쓴 문자열이 우연히 그 문법처럼 생겨서 컴퓨터가 다르게 해석했습니다.
결과적으로 그 줄 하나 때문에 명령어 블록 전체가 오류로 끝났습니다.
읽어서는 절대 못 찾습니다. 문법적으로 이상한 데가 하나도 없거든요.
고친 뒤에 실제로 실행해서 오류가 사라진 걸 확인했고, 같은 파일의 비슷한 곳을 전부 다시
훑었습니다(다행히 나머지는 진짜 정상이었습니다).
> 교훈: 문서에 적힌 명령어는 눈으로 읽지 말고 실행해서 확인합니다.
이 교훈은 그 뒤로도 계속 재확인됩니다. 3편에서 같은 종류의 실수가 네 번 반복된 이야기가
나옵니다. 규칙을 만들고 나서도 반복됐습니다.
---
## 첫 검수에서 6개 항목이 떨어졌습니다
"이제 됐다" 싶어서 검수에 넣었더니 불합격이 나왔습니다.
- 프로그램이 실제로는 패키지에 안 들어가 있었습니다 (문서에만 있었음)
- 특정 학회 데이터에 묶여 있어서 다른 데이터로는 못 썼습니다
- "12개 항목 다 지킴"이라는 주장이 거짓이었습니다
- 그 외 3건
두 번째가 제일 아팠습니다. 원본이 특정 학회 서베이 작업 기록이었던 탓에, 코드가 그 학회
데이터 형식에 딱 붙어 있었습니다. 남이 쓸 수가 없는 물건이었던 겁니다.
논문 데이터 형식을 어느 학회든 상관없는 범용 형태로 뜯어고쳤습니다.
제목, 초록, 아이디 — 이 정도만 있으면 돌아가게요.
고친 뒤 재검수에서 통과했고, "처음 보는 사람이 혼자 끝까지 갈 수 있는가"까지 확인했습니다.
그리고 문서상 "설치됩니다"가 아니라 깨끗한 환경에서 실제로 설치해봤습니다.
검증 → 등록 → 설치 → 명령어 동작 → 자연어로 불렀을 때 반응까지 전부요.
이 과정에서 Windows 파일 잠금 때문에 한 번 실패하고 재시도로 성공한 것도 그대로
기록했습니다(나중에 다른 사람이 같은 걸 만나니까요).
---
## 이 단계에서 남은 것, 그리고 남은 문제
만든 것
- 어떤 주제로든 똑같이 찍어낼 수 있는 작업 폴더 규격
- 그 규격대로 폴더를 만들어주는 도구
- 어떤 AI로 열어도 같은 절차를 밟게 하는 설명서 구조
- AI를 자기도 모르게 비교 실험 대상으로 만드는 장치
- 환경을 추측하지 않고 실제로 확인하는 사전 점검
아직 없던 것
이 시점의 문서에는 "약속만 있고 지킬 방법이 없는" 항목이 잔뜩 있었습니다.
문서에는 "검증을 통과한 것만 정식 문서로 올린다"라고 적혀 있었습니다.
그런데 통과 못 한 걸 올리려고 하면 막는 게 아무것도 없었습니다.
사람이 지키는 규칙으로 두면, 바쁠 때 안 지킵니다.
AI가 하면 더 안 지킵니다 — AI는 "검증했습니다"라고 말하는 데 아무 비용이 안 드니까요.
그 구멍을 메우는 게 다음 이야기입니다.
---
## 정리 — 이 편에서 배운 것 네 가지
1. 폴더 이름은 취향이 아니라 배선입니다.
프로그램들이 그 이름을 믿고 찾아갑니다. "정리"하는 순간 고장 납니다.
2. 규칙과 예외는 같은 자리에 씁니다.
예외를 한 곳에만 적어놨다가, 정상인 걸 위반으로 판정할 뻔했습니다.
3. 정답지는 하나만 둡니다.
절차를 여러 문서에 복사해두면 반드시 서로 달라집니다. 원본 하나를 만들고
나머지는 전부 그걸 가리키게 했습니다.
4. 문서에 적힌 명령어는 실행해서 확인합니다.
읽어서는 안 보이는 오류가 있습니다. 실제로 있었습니다.
