3장. 작업 환경 설계의 삼각 구조 — CLAUDE.md, 규칙, 문맥

이 챕터를 읽으면, AI를 잘 쓰는 비결이 "좋은 질문"이 아니라 "좋은 작업 환경 설계"라는 것을 이해하고, 세 가지 설계 수준(지시문/문맥/작업환경)을 직접 구성할 수 있어요.

박선생님의 고민

박선생님은 매주 월요일 아침 클로드코드를 열 때마다 같은 문장을 타이핑해요.

> 나는 초등학교 4학년 3반 담임 교사입니다. 학생은 30명이고,
  상위 20%, 중위 60%, 하위 20%로 구성되어 있습니다.
  이번 주 단원은 국어 3단원입니다. 퀴즈를 만들어주세요.

화요일에도 같은 소개를 반복해요. 수요일에도 같은 소개를 반복해요. 매번 자기소개를 하는 셈이에요. ChatGPT를 쓸 때도 이랬고, 클로드코드도 마찬가지예요.

"도대체 매번 같은 말을 반복해야 하나요?"

박선생님이 겪는 이 피로는 "질문을 잘 못 해서"가 아니에요. 작업 환경이 설계되지 않았기 때문이에요. 같은 피로를 매일 겪는 교사가 많아요. 이 챕터에서 그 반복을 끝내는 방법을 알려드려요.

김선생님이 말해요.

"저도 처음 2주는 매번 자기소개를 했어요. 그런데 파일 세 종류만 정리하니까, 그 반복이 완전히 사라졌어요. AI를 잘 쓰는 비결은 좋은 질문이 아니라 좋은 환경 설계예요."

김선생님 한마디

"AI에게 매번 같은 말을 반복하고 있다면, 질문 실력이 부족한 게 아니에요. 작업 환경이 비어 있는 거예요. 환경을 한 번만 채우면, 반복이 영구적으로 사라져요."

이게 왜 되나요? — 설계 삼각 구조

AI를 잘 쓰는 방법은 세 가지 층으로 나뉘어요. 교실에 비유하면 이해가 빨라요.

첫 번째: 지시문 설계 (Prompt Engineering)

수업 시간에 학생에게 "지금 이 활동을 해라"라고 말하는 것과 같아요. 오늘 이 순간, 이 대화에서 AI에게 내리는 구체적인 지시예요. "퀴즈 만들어줘"처럼 짧을 수도 있고, 조건을 여러 개 붙인 긴 요청일 수도 있어요.

정확히 말하면, 지시문 설계란 AI에게 보내는 한 번의 요청을 얼마나 명확하게 구성하느냐의 기술이에요. "퀴즈 만들어줘"보다 "선택지 4개짜리 퀴즈 5문항, 정답과 해설 포함, quiz.md로 저장해줘"가 더 좋은 지시문이에요.

지시문 설계는 가장 익숙한 방법이에요. 대부분의 교사가 여기에 집중해요. 하지만 지시문만으로는 한계가 있어요. 매번 같은 배경 설명을 반복해야 하고, 같은 형식 요구를 다시 적어야 해요.

두 번째: 문맥 설계 (Context Engineering)

교실 벽에 붙여둔 학급 약속, 게시판의 참고 자료와 같아요. 학생들이 수업을 시작할 때 벽을 보면 "아, 우리 반 약속이 이거였지"라고 떠올려요. AI도 마찬가지예요. 대화를 시작할 때 이미 읽어둔 배경 정보가 있으면, 매번 설명하지 않아도 돼요.

정확히 말하면, 문맥 설계란 AI가 작업을 시작하기 전에 자동으로 읽는 파일과 자료를 어떻게 구성하느냐의 기술이에요. CLAUDE.md, 규칙 파일, 참고 자료 폴더가 여기에 해당해요. 한 번 정리해두면 매 대화마다 자동으로 읽혀요. 교사가 매번 자기소개를 하지 않아도 되는 이유가 바로 이거예요.

세 번째: 작업환경 설계 (Harness Engineering)

학교의 교칙, 출입 금지 구역, 평가 기준과 같아요. "운동장에서 뛰어도 되지만 복도에서는 안 돼", "시험은 이 기준으로 채점해". 학생에게 매번 말하지 않아도, 교칙이 있으면 자동으로 적용돼요.

정확히 말하면, 작업환경 설계란 AI의 행동 범위를 바깥에서 잡아주는 구조예요.

안장(harness)이라는 단어가 낯설 수 있어요. 말에게 안장을 씌우는 것과 같아요. 안장이 잘 맞으면 말이 빠르게 달려도 기수가 안전해요. AI에게도 마찬가지예요. 좋은 안장이 있으면 AI가 빠르게 일해도 교사가 통제할 수 있어요.

작업환경 설계의 6대 요소:

1. 권한: AI가 읽을 수 있는 폴더와 수정할 수 있는 폴더를 정해요. "context/ 폴더는 읽기만, outputs/ 폴더에만 저장."
2. 검증: AI가 작업을 마친 후 확인해야 할 기준을 정해요. "퀴즈 정답이 교과서와 일치하는지 확인."
3. 실행 방식: AI가 어떤 순서로 일할지 정해요. "계획을 먼저 보여주고, 승인 후에 실행."
4. 상태 유지: 작업 진행 상황을 어디에 기록할지 정해요. "handoff.md에 매 세션 끝에 기록."
5. 결정 기록: 왜 이 방법을 택했는지 기록해요. "decision-log.md에 선택 이유를 남겨."
6. 외부 연동: 어떤 외부 도구를 연결할지 정해요. "MCP로 검색 도구를 연결."

처음부터 6가지를 다 설정할 필요는 없어요. 권한과 검증 두 가지만 먼저 설정해도 AI의 실수가 크게 줄어들어요. 나머지는 필요할 때 하나씩 추가하면 돼요.

이 세 가지를 표로 정리하면 이래요.

대부분의 교사가 지시문 설계(프롬프트 잘 쓰기)에만 집중해요. 프롬프트를 잘 쓰는 것은 중요해요. 그러나 프롬프트만으로는 매번 같은 자기소개를 반복해야 해요. 문맥 설계와 작업환경 설계가 갖춰지면, 프롬프트는 짧아지고 결과는 좋아져요.

하네스가 약한 요청은 이래요:

퀴즈 만들어줘.

하네스가 있는 요청은 이래요:

context/ 폴더의 교과서 본문을 읽고,
CLAUDE.md의 퀴즈 형식에 따라 만들어줘.
정답이 교과서와 일치하는지 확인하고,
outputs/ 폴더에 저장해줘.

"가드레일이 좋으면 작은 성공보다 큰 안전이 생긴다." 이 말은 AI 활용의 핵심을 요약해요. 작은 프롬프트 기교보다, 전체 작업 환경의 구조가 결과를 결정해요.

하네스의 실체: settings.json과 Hooks

하네스를 구성하는 구체적인 파일들이 있어요. 대표적인 것이 settings.json이에요. 이 파일은 "AI가 할 수 있는 일"과 "할 수 없는 일"을 목록으로 정해놓는 허용 목록이에요. 교무실에서 "이 앱만 설치 가능"이라는 IT 정책과 같아요.

{
  "permissions": {
    "allow": ["Read", "Glob", "Grep"],
    "deny": ["Bash(rm *)"]
  }
}

위 설정은 "파일을 읽고 검색하는 건 허용하지만, 파일을 삭제하는 명령은 차단"한다는 뜻이에요. 처음에는 읽기만 허용하고, 익숙해지면 하나씩 권한을 늘려가는 것이 안전해요.

Hooks는 "특정 시점에 자동으로 실행되는 규칙"이에요. 시험지를 제출하기 전에 자동으로 맞춤법 검사기가 돌아가는 것과 같아요. 예를 들어, AI가 파일을 수정하려 할 때마다 "학생 실명이 포함되어 있지 않은지" 자동으로 검사하는 Hook을 걸 수 있어요. (Hooks의 자세한 설정법은 8장에서 다뤄요.)

장시간 작업을 위한 하네스: 세션 이어받기 패턴

한 학기분 수업 자료(16주)처럼 큰 작업은 하루에 끝나지 않아요. 세션이 끊기면 AI는 이전 대화를 잊어버려요. 이 문제를 해결하는 것이 세션 이어받기 패턴이에요.

Anthropic 엔지니어링 팀이 공개한 방법은 이래요:

1. 첫 세션: 전체 작업 목록과 진행 상태를 progress.md 파일에 기록해요.
2. 이후 세션: AI가 시작할 때 progress.md를 먼저 읽고, "어디까지 했는지" 파악한 뒤 이어서 작업해요.
3. 매 세션 끝: 완료된 항목을 표시하고, 남은 작업을 업데이트해요.

<!-- progress.md 예시 -->
## 4학년 과학 수업 자료 제작 진행 상황

| 주차 | 단원 | 상태 | 비고 |
|------|------|------|------|
| 1주 | 식물의 생활 | ✅ 완료 | 퀴즈+활동지+수업안 |
| 2주 | 물의 상태 변화 | ✅ 완료 | 퀴즈+활동지 |
| 3주 | 혼합물 분리 | 🔄 진행 중 | 수업안 작성 중 |
| 4주 | 그림자와 거울 | ⬜ 예정 | |

AI가 새 세션을 시작하면 이 파일을 읽고 "3주차 수업안부터 이어서 작업합니다"라고 시작해요. 인수인계서(handoff.md)와 함께 쓰면, 세션이 100번 바뀌어도 작업이 끊기지 않아요.

실습해보기 — CLAUDE.md: 운영 계약서 쓰기

CLAUDE.md는 AI에게 건네는 업무 메모예요. 백과사전이 아니에요. 짧은 업무 메모예요.

새 학기 첫날, 보조교사가 교실에 들어왔다고 상상하세요. 선생님은 포스트잇 한 장을 건네요. "우리 반 4학년 3반, 30명, 퀴즈는 선택지 4개, 수업안은 도입-전개-정리 구조." 보조교사는 이 메모를 책상에 붙여놓고 매번 참고해요. 선생님이 매번 설명하지 않아도, 보조교사가 알아서 맞춰줘요.

CLAUDE.md가 바로 이 포스트잇이에요. 프로젝트 폴더의 최상위에 이 파일이 있으면, 클로드코드가 대화를 시작할 때마다 가장 먼저 읽어요. 매번 자동으로 읽으므로 선생님이 "이거 읽어"라고 따로 말할 필요가 없어요.

핵심 구성 요소 다섯 가지:

1. 수업 정보: 학교, 학년, 교과, 담당 과목
2. 학급 구성: 학생 수, 수준 분포, 특이 사항
3. 선호 형식: 퀴즈 형식, 수업안 구조, 피드백 양식, 파일명 규칙
4. 현재 단원: 지금 가르치고 있는 내용, 다음 평가 일정
5. 금지 사항: 학생 실명 사용 금지, 출처 없는 통계 사용 금지 등

짧을수록 좋아요. A4 10장짜리 매뉴얼을 보조교사에게 주면, 다 읽겠지만 핵심을 놓칠 수 있어요. 포스트잇 한 장이면 확실히 기억해요. 직접 써보면서 느낀 경험을 말씀드리면, 200줄을 넘기면 클로드코드가 앞쪽 내용을 놓치기 시작해요. 200줄이 넘는 CLAUDE.md를 써봤는데 정작 중요한 지시를 잊어버리는 경우가 생겼어요. 그 이후로는 항상 50줄 이하로 유지해요.

"많이 적어야 잘 알아듣겠지"가 아니라, "핵심만 적어야 잘 알아듣는다"가 맞아요.

실습: 나만의 CLAUDE.md를 3분 안에 만들기

VS Code에서 작업 폴더를 연 뒤, 새 파일을 만들어요. 파일 이름은 반드시 CLAUDE.md이에요. 대문자예요. 소문자 claude.md는 인식되지 않아요.

방법 A (Windows): VS Code 왼쪽 파일 탐색기에서 새 파일 아이콘(종이+플러스)을 클릭하고, CLAUDE.md를 입력해요. 방법 B (Mac): 같은 방법이에요. VS Code 왼쪽 파일 탐색기에서 새 파일을 만들어요.

템플릿 1: 초등 담임 교사용

# 교사 정보
- 학교: 서울 OO초등학교 4학년 3반 담임
- 학생: 30명 (상 20% / 중 60% / 하 20%)
- 담당: 전과목

# 선호 형식
- 퀴즈: 선택지 4개, 정답+해설 포함
- 수업안: 도입(5분)-전개(30분)-정리(10분)
- 피드백: 잘한 점 2개 + 개선점 1개 + 격려
- 파일명: YYYY-MM-DD-자료명.md

# 현재 상황
- 단원: 1학기 국어 3단원
- 다음 평가: 4월 15일 단원평가

# 금지 사항
- 학생 실명을 파일에 포함하지 마세요
- 출처 없는 통계를 사용하지 마세요
- 교과서 범위 밖 내용을 출제하지 마세요

이 파일이 총 18줄이에요. 이 18줄이 프로젝트 폴더에 있으면, 클로드코드가 매번 자동으로 읽어요. "퀴즈 5문항 만들어줘"라고만 말해도, 4학년 수준에 맞게, 선택지 4개로, 정답과 해설을 포함해서 만들어줘요.

템플릿 2: 중등 교과 교사용

# 교사 정보
- 학교: OO중학교 영어 교과 담당
- 담당 학년: 2학년 (3개 반, 총 90명)
- 교과서: 동아출판 영어2

# 선호 형식
- 퀴즈: 객관식+서술형 혼합, 배점 표기
- 수행평가: 루브릭 5점 척도
- 출력: 모두 한국어, 마크다운 형식

# 현재 상황
- 단원: Lesson 4 "Green Future"
- 수행평가: 5월 8일 영어 발표

# 금지 사항
- 학생 개인정보 포함 금지
- 교육과정 성취기준에 없는 내용 출제 금지

템플릿 3: 대학 강의용

# 강의자 정보
- 소속: OO대학교 교육학과
- 강의: 교육심리학 (3학년, 40명)
- 교재: 교육심리학 개론 (최신판)

# 선호 형식
- 강의안: 90분 기준, 이론-토론-실습 구조
- 과제: APA 양식, 참고문헌 필수
- 시험: 서술형 위주, 채점 기준 명시

# 현재 상황
- 주차: 7주차 "학습동기이론"
- 중간고사: 4월 20일

# 금지 사항
- 허위 연구 인용 금지
- 학생 성적 데이터 포함 금지

파일을 저장(Ctrl+S 또는 Cmd+S)한 후, 터미널에서 claude를 실행하고 물어보세요.

> 내가 담당하는 학년이 몇 학년이야?

CLAUDE.md에 적은 대로 대답하면 성공이에요. 만약 "어떤 학년을 담당하시나요?"라고 되물어본다면, 파일 이름이 정확한지(대문자 CLAUDE.md인지), 파일이 프로젝트 폴더 최상위에 있는지 확인하세요.

CLAUDE.md 업데이트 방법:

학기가 바뀌거나 단원이 바뀌면 업데이트가 필요해요. 두 가지 방법이 있어요.

방법 1: VS Code에서 직접 열어서 수정해요. 단원명과 평가 일정만 바꾸면 돼요. 5분이면 충분해요.

방법 2: 클로드코드에게 말해요. "CLAUDE.md에서 현재 단원을 4단원으로 바꿔줘." 클로드코드가 직접 파일을 수정해요.

작업 폴더 구조 — 교실 배치도 만들기

파일과 폴더는 AI 작업의 기본 단위예요. 교실에 칠판, 책상, 사물함이 정해진 자리에 있듯이, AI가 일하는 폴더도 역할별로 자리가 있어야 해요.

정확히 말하면, 클로드코드는 파일 단위로 읽고, 파일 단위로 써요. 폴더 구조가 정리되어 있지 않으면 AI가 어디를 읽어야 하는지, 결과를 어디에 저장해야 하는지 몰라요. 결과물이 여기저기 흩어지고, 참고 자료를 찾지 못해요.

교사용 폴더 템플릿:

내-수업-프로젝트/
├── CLAUDE.md              # 조교 업무 메모 (항상 자동으로 읽힘)
├── rules/                 # 상황별 규칙
│   ├── 수업자료-규칙.md    # 수업 자료 만들 때의 규칙
│   └── 행정문서-규칙.md    # 행정 문서 쓸 때의 규칙
├── context/               # 항상 참고할 자료 (읽기 전용)
│   ├── 학급정보.md         # 학생 수준 분포, 특이 사항
│   ├── 교육과정-성취기준.md # 이번 학기 성취기준
│   └── 교과서-3단원.txt    # 교과서 본문 텍스트
├── templates/             # 양식 모음 (재사용)
│   ├── 퀴즈-양식.md       # 퀴즈의 표준 형식
│   └── 수업안-양식.md     # 수업안의 표준 구조
├── outputs/               # 결과물 보관 (AI가 여기에 저장)
│   ├── quiz-unit3.md
│   └── 수업안-unit3.md
└── handoff/               # 인수인계 문서
    ├── handoff.md         # 작업 상태 기록
    └── decision-log.md    # 결정 이유 기록

왜 이렇게 나누나요?

세 가지 이유가 있어요.

첫째, 읽는 자료와 쓰는 결과를 분리해요. context/ 폴더는 AI가 읽기만 하는 곳이에요. outputs/ 폴더는 AI가 결과를 저장하는 곳이에요. 이 둘이 섞이면 AI가 자기가 만든 파일을 원본 참고 자료로 착각할 수 있어요. 교무실에서도 원본 문서함과 복사 문서함을 분리하는 것과 같은 원리예요.

둘째, 템플릿을 따로 둬요. 같은 양식을 매번 프롬프트에 설명하는 대신, templates/ 폴더에 양식 파일을 저장해요. "@templates/퀴즈-양식.md를 참고해서 만들어줘"라고 하면 돼요. 양식이 변하면 파일 하나만 수정해요. 10개 단원의 퀴즈가 모두 같은 형식으로 만들어져요.

셋째, 인수인계가 가능해져요. handoff/ 폴더에 작업 상태를 기록하면, 다른 날 다른 세션에서도 이어서 작업할 수 있어요. 보충교사에게 업무를 넘길 때도, 동료 교사에게 자료를 공유할 때도, 이 폴더만 보면 상황을 파악할 수 있어요.

당황하지 마세요. 이 폴더 구조를 처음부터 완벽하게 만들 필요 없어요. CLAUDE.md 하나와 outputs/ 폴더 하나만 있어도 시작할 수 있어요. 한 달 정도 쓰다 보면 "아, 규칙 파일이 필요하겠다" 싶을 때가 와요. 그때 rules/ 폴더를 만들면 돼요.

경로별 규칙 파일 — 상황에 맞는 교칙 만들기

CLAUDE.md에 모든 규칙을 다 넣으면 파일이 길어지고, 핵심이 묻혀요. 상황별로 규칙을 나누는 것이 더 효과적이에요.

교실에도 "수업 중 규칙"과 "체육 시간 규칙"이 달라요. 수업 시간에는 "발표할 때 손을 들어요"이고, 체육 시간에는 "운동화를 신어요"이에요. 같은 학생인데 상황에 따라 적용되는 규칙이 달라요.

AI에게도 마찬가지예요. 수업 자료를 만들 때와 행정 문서를 쓸 때의 규칙이 달라요.

정확히 말하면, rules/ 폴더 안에 상황별 마크다운 파일을 만들면, 클로드코드가 해당 작업 시 이 규칙을 자동으로 참고해요. CLAUDE.md에 "수업 자료를 만들 때는 rules/수업자료-규칙.md를 참고하세요"라고 한 줄 추가하면 돼요.

수업자료-규칙.md 예시:

# 수업 자료 제작 규칙

## 퀴즈
- 선택지는 반드시 4개
- 정답과 해설을 반드시 포함
- 난이도 표기 (상/중/하)
- 교과서 페이지 번호 명시
- 오답 선택지도 그럴듯하게 (너무 뻔한 오답 금지)

## 수업안
- 도입-전개-정리 3단 구조
- 각 단계별 시간 배분 명시
- 교사 발화와 학생 활동 구분
- 교육과정 성취기준 연결
- 시간 합계가 45분(또는 40분)과 일치하는지 확인

## 활동지
- A4 한 장 분량
- 학생 이름 기입란 포함
- 글자 크기 12pt 이상
- 그림이나 표를 적어도 1개 포함

행정문서-규칙.md 예시:

# 행정 문서 작성 규칙

## 공문
- 학교 공문 양식 준수
- 날짜와 요일 반드시 확인 (날짜 계산은 반드시 확인)
- 수신처 정확히 기재
- 존칭 사용

## 가정통신문
- 학교 로고 위치 표기
- 학부모 회신란 포함
- 간결한 문장 사용 (한 문장 50자 이하)
- 일정은 표로 정리

## 회의록
- 결정사항 / 논의사항 / 액션아이템 분리
- "결정되지 않은 것"을 결정사항에 넣지 않기
- 담당자와 기한 명시

## 공통
- 파일명: YYYY-MM-DD-문서명.md
- 출력 형식: 마크다운 기본, 필요시 DOCX 변환
- 학생 실명 포함 절대 금지

CLAUDE.md에 모든 규칙을 넣지 않는 이유가 분명해요. CLAUDE.md가 50줄을 넘어 200줄이 되면, AI가 정작 중요한 규칙을 놓쳐요. 핵심만 CLAUDE.md에 두고, 상세 규칙은 rules/ 폴더에 분리하는 것이 정답이에요.

토큰 비용 5대 원인: "뭘 넣지 않을 것인가"

AI의 기억력에는 한계가 있어요. 교무실 책상에 서류가 산더미처럼 쌓여 있으면, 정작 필요한 서류를 찾지 못해요. 중요한 공문이 서류 더미에 묻혀서 기한을 놓치는 것과 같아요.

토큰이라는 단어가 낯설 수 있어요. 교무실 용지라고 생각하세요. AI와 대화할 때마다 용지를 써요. 선생님이 말하는 것도 용지를 쓰고, AI가 읽는 파일도 용지를 쓰고, AI가 답하는 것도 용지를 써요. 용지가 많이 남아 있으면 오래 대화할 수 있고, 용지가 떨어지면 대화가 끊기거나 앞부분을 잊어버려요.

정확히 말하면, 토큰은 AI가 읽고 쓰는 텍스트의 최소 단위예요. 한국어 한 글자가 보통 1~2토큰, 영어 한 단어가 약 1토큰이에요. AI에게 보내는 모든 텍스트(프롬프트, CLAUDE.md, 규칙 파일, 이전 대화, 파일 내용)가 토큰으로 변환되어 처리돼요. 토큰이 많아지면 비용이 올라가고, 한 세션에서 다룰 수 있는 양이 줄어들어요. 용지를 아끼면 같은 돈으로 더 많은 일을 할 수 있어요.

토큰을 낭비하는 5가지 원인과 해결책:

1. 너무 긴 CLAUDE.md와 규칙 파일

200줄을 넘기면 핵심이 묻혀요. AI가 매 대화 시작마다 이 파일을 전부 읽으므로, 긴 파일은 매번 많은 용지를 소비해요.

해결: 핵심만 남기고, 자세한 내용은 context/ 폴더의 별도 파일로 분리해요. CLAUDE.md에는 "자세한 내용은 context/학급정보.md를 참고"라고만 적어요.

2. 모호한 프롬프트

"좋은 수업 자료 만들어줘"처럼 모호하게 요청하면, AI가 정보를 찾기 위해 더 많은 파일을 읽어요. "어떤 자료를 원하시나요?"라고 되묻는 왕복도 용지를 소비해요.

해결: "4학년 국어 3단원 퀴즈 5문항, 선택지 4개, 해설 포함"처럼 구체적으로 요청해요.

3. 긴 세션 누적

한 세션에서 오래 대화하면, 이전 대화 내용이 계속 쌓이에요. 매 턴마다 이전 대화 전체가 다시 전송돼요. 아침에 시작한 대화를 저녁까지 이어가면, 저녁 시점에는 아침의 모든 대화가 매번 포함돼요.

해결: 하나의 작업이 끝나면 새 세션을 시작해요. "퀴즈 만들기"가 끝나면 새 세션에서 "수업안 만들기"를 시작해요. 장기 작업일 때는 handoff.md에 상태를 기록하고 세션을 닫아요.

4. 도구 출력 과다

AI가 파일을 검색하거나 명령을 실행하면, 그 결과가 대화에 추가돼요. 테스트 로그가 수백 줄 출력되면, 그만큼 용지를 잡아먹어요. 파일 목록을 전부 출력하면 수십 줄이 돼요.

해결: "결과를 3줄로 요약해서 보여줘", "성공/실패만 알려줘"처럼 요약을 요청해요.

5. 한 세션에 너무 많은 역할

퀴즈 만들기, 수업안 쓰기, 성적 분석, 가정통신문 작성을 한 세션에서 다 하면, AI가 여러 맥락을 동시에 유지해야 해요. 네 가지 일의 맥락이 섞이면 각각의 품질이 떨어져요.

해결: 역할별로 세션을 나눠요. "수업 자료 세션"과 "행정 문서 세션"을 분리해요.

"뭘 넣을까"보다 "뭘 넣지 않을까"가 더 중요해요. 교무실 책상이 깨끗해야 일이 잘 돼요. AI의 작업 공간도 마찬가지예요.

Handoff 문서 — 세션을 넘기는 인수인계서

교사가 출산휴가를 가거나, 연수를 떠나거나, 학기말에 담임이 바뀔 때 인수인계를 해요. "지금까지 뭘 했고, 뭘 확인했고, 뭐가 막혀 있고, 다음에 뭘 해야 하는지"를 문서로 남겨요. 인수인계서가 없으면 새로 오신 선생님이 처음부터 다시 파악해야 해요.

AI 작업도 마찬가지예요. 오늘 세션에서 하던 일을 내일 이어서 해야 할 때, 인수인계 문서가 없으면 처음부터 다시 설명해야 해요. AI는 대화를 종료하면 이전 내용을 기억하지 못해요.

정확히 말하면, Handoff 문서는 AI 세션 간의 인수인계 파일이에요. 세션을 종료하기 전에 작업 상태를 기록해두면, 다음 세션에서 "handoff.md를 읽고 이어서 작업해줘"라고 말하면 돼요. /compact 명령으로 세션을 압축하는 방법도 있지만, 명시적으로 파일에 기록하는 것이 더 신뢰할 수 있어요. /compact은 AI가 알아서 요약하므로 중요한 내용이 빠질 수 있어요.

handoff.md 최소 형식:

# 인수인계 문서
## 날짜: 2026-03-31

## 바뀐 것 (완성된 산출물)
- quiz-unit3.md 완성 (10문항, 정답 확인 완료)
- 수업안-unit3.md 초안 작성 (시간 배분 검증 완료)

## 통과한 것 (확인 완료)
- 퀴즈 정답이 교과서와 일치하는 것 확인
- 수업안 시간 합계 45분 확인
- 금지 사항(학생 실명) 위반 없음 확인

## 막힌 것 (미해결)
- 루브릭 평가 항목 3개 미정 (교육과정 성취기준 재확인 필요)
- 활동지 그림 삽입 방법 미확인

## 다음 할 일
1. 루브릭 완성 (성취기준 확인 후)
2. 활동지 제작
3. 전체 자료 최종 검토

decision-log.md: 결정 기록

"왜 이 방법을 택했는가"를 기록하는 파일이에요. 한 달 뒤에 "왜 퀴즈를 객관식으로 했지?"라는 질문에 답할 수 있어요. 또한 AI가 다음 세션에서 이 기록을 읽으면, 같은 고민을 반복하지 않아요.

# 결정 기록

## 2026-03-31: 퀴즈 형식 결정
- 결정: 객관식 4지선다
- 이유: 4학년 학생에게 서술형은 채점 부담이 큼, 객관식이 단원 학습 확인에 적합
- 대안: 서술형+객관식 혼합 → 다음 단원에서 시도 예정

## 2026-03-31: 수업안 시간 배분
- 결정: 도입 5분 / 전개 30분 / 정리 10분
- 이유: 전개 활동이 모둠 활동 포함이라 30분 필요
- 검토: 정리 시간을 7분으로 줄이고 전개를 33분으로 늘리는 방안도 고려했으나, 형성평가 3문제에 10분이 적합

인수인계 문서는 AI를 위한 것만이 아니에요. 동료 교사에게 업무를 넘길 때, 보충교사가 수업을 이어받을 때, 다음 학기 같은 단원을 가르칠 때 — 이 문서 하나면 상황 파악이 돼요.

초보자 운영 규칙 10가지 + 검증 원칙

처음 AI를 쓰는 교사를 위한 교무실 생존 규칙 10가지예요. 교무실 벽에 붙여두고 참고하세요.

1. 읽는 폴더와 쓰는 폴더를 분리하세요. AI가 참고 자료를 실수로 덮어쓰는 사고를 막아요. context/는 읽기 전용, outputs/는 결과 저장 전용이에요. 교무실에서도 원본 서류함과 복사본 서류함을 따로 두는 것과 같아요.

2. CLAUDE.md는 짧게 유지하세요. 포괄적인 것보다 명확한 것이 나아요. 핵심 정보만 20~50줄 이내로 적으세요. 한 화면에 다 보이는 길이가 이상적이에요.

3. 긴 참고 자료는 별도 파일로 분리하세요. 교육과정 성취기준 전문, 학교 양식 원본, 학급 상세 정보는 context/ 폴더에 따로 저장해요. 필요할 때 @파일명으로 불러오세요.

4. 상황별 규칙은 rules/ 폴더에 나누세요. 수업 자료 규칙과 행정 문서 규칙을 한 파일에 섞으면 AI가 혼동해요. 상황별로 파일을 나누세요.

5. 반복 프롬프트는 Skill로 만드세요. 같은 형식의 퀴즈를 매주 만든다면, 그 프롬프트를 Skill 파일로 저장해요. /quiz만 입력하면 퀴즈가 나와요. Ch.8에서 자세히 다뤄요.

6. 중요한 검증은 AI에게만 맡기지 마세요. AI가 만든 퀴즈의 정답은 반드시 교사가 직접 확인해요. AI는 가끔 계산을 틀려요. 특히 수학과 날짜 계산에서 실수가 잦아요.

7. /compact을 쓰되, handoff.md를 더 신뢰하세요. 세션이 길어지면 /compact 명령으로 대화를 압축할 수 있어요. 하지만 handoff.md에 명시적으로 기록하는 것이 더 확실해요. /compact은 AI가 판단해서 요약하므로 중요한 디테일이 빠질 수 있어요.

8. 도구 출력은 요약해서 받으세요. "폴더 내 모든 파일을 보여줘" 대신 "폴더 내 .md 파일 이름만 보여줘"가 토큰을 절약해요. 필요한 정보만 요청하세요.

9. 실수 사례를 CLAUDE.md에 기록하세요. AI가 같은 실수를 반복하면, CLAUDE.md에 "주의: 날짜 계산은 반드시 확인"처럼 추가해요. 다음 세션부터 같은 실수가 줄어들어요. 실수에서 배운 교훈을 규칙으로 만드는 거예요.

10. 작업 시작 전에 완료 기준을 먼저 적으세요. "이 작업이 끝나면 무엇을 확인할 것인가"를 작업 시작 전에 정해요. "퀴즈 10문항 완성, 정답 확인, 파일 저장 완료"처럼요. 완료 기준 없이 시작하면 끝이 없어져요. 이것이 검증 원칙의 핵심이에요. 수업 지도안에 평가 기준을 먼저 적는 것과 같은 원리예요.

[Cowork] Projects에 자료 모아두기

CLAUDE.md가 클로드코드용 문맥 관리 도구라면, Projects는 교무실 허브(Cowork)용 문맥 관리 도구예요.

교무실 허브(Cowork)는 웹 기반 환경이에요. 터미널을 사용하지 않아요. 여기서는 CLAUDE.md 파일을 직접 만드는 대신, Projects 기능으로 배경 자료를 관리해요. 교육과정 문서, 학교 양식, 학급 정보를 Projects에 올려두면, Cowork가 매번 이 자료를 참고해요.

같은 "문맥 설계"라는 개념이 도구에 따라 다르게 적용되는 거예요.

두 도구를 함께 쓴다면, 같은 자료를 양쪽에 유지하는 것이 좋아요. 교육과정 성취기준은 Claude Code의 context/ 폴더에도, Cowork의 Projects에도 올려두세요. 어느 쪽에서 작업하든 AI가 같은 배경 정보를 참고할 수 있어요.

Cowork에서 프로젝트를 만드는 방법은 간단해요. claude.ai에 접속해서, 왼쪽 메뉴의 "Projects"를 클릭하고, "New Project"를 만들고, 파일을 업로드해요. 글로벌 지침에 "나는 초등학교 4학년 담임이에요" 같은 배경을 적으면, CLAUDE.md와 같은 효과예요.

오해 바로잡기

오해: "프롬프트만 잘 쓰면 AI를 잘 쓰는 것이다."

프롬프트는 중요해요. 그러나 프롬프트는 설계 삼각 구조의 한 꼭짓점일 뿐이에요. 매번 좋은 프롬프트를 쓰는 것보다, 한 번 좋은 환경을 설계하는 것이 10배 효율적이에요. CLAUDE.md 하나면 매주 10분씩 절약돼요. 한 학기면 5시간이에요.

오해: "CLAUDE.md에 많이 적을수록 AI가 더 잘 이해한다."

반대예요. 짧을수록 잘 따라요. 200줄을 넘기면 앞쪽 내용을 놓치기 시작해요. "많이 알려주면 좋겠지"라는 생각은 자연스럽지만, AI에게는 "핵심만 명확하게"가 더 효과적이에요.

🎯 이번 주 딱 한 가지

CLAUDE.md를 만들고, 작업 폴더에 rules/와 outputs/ 폴더를 추가하세요. 위의 템플릿을 복사해서 자신의 상황에 맞게 수정하면 3분이면 돼요. 그리고 클로드코드에게 "내 학년이 몇 학년이야?"라고 물어보세요. 제대로 대답하면 환경 설계가 성공한 거예요.

이 챕터의 핵심:

1. AI를 잘 쓰는 비결은 프롬프트가 아니라 환경 설계다 — 지시문/문맥/작업환경 삼각 구조를 이해하면 AI 조교가 3배 똑똑해진다
2. CLAUDE.md는 짧은 업무 메모다 — 200줄 이하, 핵심 5가지만 적고, 나머지는 별도 파일로 분리한다
3. "뭘 넣을까"보다 "뭘 넣지 않을까"가 토큰을 절약한다 — 5대 낭비 원인을 제거하면 같은 비용으로 더 많은 일을 할 수 있다

참고 출처

• Anthropic 공식 문서: Claude Code Settings, CLAUDE.md 가이드
• 원본 마스터 가이드 Ch.5 "시스템 설계: 문맥, 하네스, 검증" (CHOI @choi.openai)
• 원본 마스터 가이드 Ch.3 "Cowork와 Claude Code 실전 플레이북" (CHOI @choi.openai)
• Anthropic 2026 Agentic Coding Trends Report — 하네스 설계의 중요성
• 커뮤니티 실전 패턴: CLAUDE.md 운영 사례, 폴더 구조 모범 사례, 토큰 절약 팁