Claude Code를 챗봇으로 쓰고 있었다 — 작업 루프로 바꾸기
SW마에스트로에서 팀 프로젝트 개발하면서 Claude Code를 꽤 오래 썼는데, 최근에 온보딩 문서랑 특강 슬라이드를 제대로 읽고 나서 “아, 나 이걸 완전 잘못 쓰고 있었다” 싶었다. 그냥 채팅창처럼 쓰고 있었던 거다.
내가 쓰던 방식
매번 이런 식이었다.
“이 프로젝트 Spring Boot야. JPA 쓰고 있어. Kafka도 있고. 이 코드 좀 고쳐줘.”
대화 시작할 때마다 프로젝트 소개부터 했다. 한 세션 내에서는 그나마 괜찮은데, 새 창 열면 또 처음부터. “아까 말했던 것처럼 해줘”가 안 통하니까 매번 설명을 반복했다. 프로젝트가 커질수록 설명도 길어졌고, 10분짜리 컨텍스트 세팅 끝에 겨우 작업 시작하는 패턴이 반복됐다.
더 짜증났던 건 따로 있었다. Claude가 “수정 완료했습니다!” 하는데 실제로 돌려보면 안 된다. 다른 곳이 망가졌거나, 내가 유지하고 싶었던 동작이 바뀌어 있거나. “왜 또 이래?” 싶어서 다시 수정 요청하면 또 다른 곳이 깨지는 악순환.
한번은 API 에러 처리 코드를 고쳐달라고 했더니 에러 처리뿐 아니라 성공 케이스 응답 형식까지 바꿔버렸다. 내가 말 안 한 부분을 Claude가 알아서 “더 낫겠다” 싶어 바꾼 거다. 결국 내가 원한 수정 반영하느라 30분, 바뀐 부분 되돌리느라 30분.
그때는 “Claude가 좀 부족하네” 싶었는데, 사실은 요청 방식이 문제였다. “에러 처리 좀 고쳐줘” 한 마디에 유지해야 할 것도, 완료 기준도, 검증 방법도 없었으니까 Claude가 빈칸을 전부 혼자 추측해서 채웠던 거다.
챗봇이 아니라 작업 루프
특강 슬라이드를 보고 나서 핵심을 이 한 줄로 이해했다.
Claude Code는 챗봇이 아니라 작업 루프다.
챗봇은 질문을 받으면 답한다. 끝이다. 다음 대화에서 이전 답변을 기억할 수도, 못 할 수도 있고 어차피 상태 없이 동작한다.
Claude Code는 다르다. 내가 요청을 보내면 내부에서 이런 순서로 일이 벌어진다.
1
2
3
4
5
6
7
8
01. Prompt → 사용자 요청 수신
02. Context → 파일, git 상태, CLAUDE.md, 대화 기록 불러옴
03. Plan → 다음 행동 후보 고름
04. Permission → 그 행동이 허용된 건지 확인
05. Tool Call → 허용됐으면 파일 읽기·실행·수정으로 변환
06. Execution → 실제 실행
07. Result → 결과 보고 다음 행동 다시 계획
08. State → 턴 저장, 사용자에게 응답 스트리밍
여기서 핵심은 07에서 다시 03으로 돌아가는 내부 루프다. Claude가 auth.ts를 읽고 → 에러 핸들러를 찾고 → 수정 계획을 세우고 → 수정 실행하고 → 테스트 돌리고 → 결과 확인하는 걸 혼자 반복한다. 그래서 Claude Code를 쓸 때 “파일 읽겠습니다”, “테스트 실행하겠습니다” 같은 중간 행동들이 보이는 거다. 한 번에 답을 뱉는 게 아니라 행동하면서 보정하는 방식이다.
- Context 단계가 얼마나 풍부하냐에 따라 03. Plan의 품질이 완전히 달라진다. 내가 매번 프로젝트 설명을 반복해야 했던 이유가 바로 Context 단계에 아무것도 없었기 때문이다. CLAUDE.md가 없으면 Claude는 대화 기록 말고는 참고할 게 없다.
이 루프를 사용자 입장에서 추상화하면 5단계 기본 루프가 된다.
1
이해 → 요청 → 수정 → 검증 → 마무리
이 흐름을 의식하고 쓰느냐, 그냥 채팅창처럼 쓰느냐가 결과 품질을 완전히 바꾼다. 특히 검증과 마무리를 건너뛰는 게 “완료했다는데 왜 안 돼?” 패턴의 원인이었다.
“완료했습니다”는 완료가 아니다
이 부분이 가장 인상 깊었다. 특강에서 이렇게 말했다.
Claude가 완료했다고 말해도 완료가 아니다. 완료는 검증 근거가 남았을 때다.
돌이켜보면 맞는 말이다. Claude가 “수정 완료했습니다” 하면 나는 그걸 믿고 다음 작업으로 넘어갔다. 근데 Claude가 확인한 건 파일을 수정했다는 사실뿐이다. 그게 실제로 동작하는지, 기존 기능이 안 깨졌는지는 확인 안 했다.
그래서 검증 조건을 요청에 같이 넣어야 한다.
1
2
3
4
5
6
완료라고 말하기 전에 다음을 확인해줘:
1. 수정된 코드 실행 또는 테스트 결과
2. 에러 케이스와 정상 케이스 시나리오 확인
3. 기존 기능 회귀 가능성
4. diff에서 의도 밖 변경 없는지
5. 확인하지 못한 부분이 있으면 명시해줘
이게 5계층 검증 체계인데, 최소한 1번(실행 결과)과 3번(회귀 확인)만 요청해도 “됐다는데 안 된다” 케이스가 확 준다. 직접 써보니까 그랬다.
요청 방식이 달라야 한다
특강에서 이걸 “작업 계약”이라고 표현했는데, 딱 맞는 말이다. 프롬프트가 아니라 계약이다.
약한 요청 (채팅 스타일):
1
로그인 버그 고쳐줘.
작업 계약 스타일:
1
2
3
4
5
로그인 실패 후 에러 메시지가 안 보이는 문제를 고쳐줘.
먼저 인증 흐름과 에러 표시 컴포넌트를 찾아서 원인을 설명해줘.
성공 로그인 흐름은 건드리지 마.
수정 후 실패 케이스와 성공 케이스 둘 다 확인해줘.
차이가 보이는가. 두 번째 요청엔 이게 들어있다.
- 목표: 에러 메시지가 안 보이는 문제
- 현재 상태: 인증 흐름부터 파악해줘
- 유지 조건: 성공 로그인 흐름은 건드리지 마
- 완료 기준: 문제가 수정됨
- 검증 방법: 실패/성공 케이스 둘 다 확인
이 다섯 가지가 다 들어가야 Claude가 추측 없이 움직인다. 하나라도 빠지면 그 부분을 Claude가 알아서 채운다. 그리고 Claude가 채운 추측이 내 의도와 다를 때 사이드 이펙트가 생긴다.
“더 깔끔하게 해줘”가 왜 항상 흔들리는지 이제 안다. 뭘 유지하고 뭘 바꾸는지 안 말했으니까. Claude 입장에서 빈칸을 채우는 수밖에 없었던 거다. 결과가 마음에 안 들었던 건 Claude 탓이 아니라 요청 탓이었다.
수정 요청도 마찬가지다. “조금 더 자연스럽게 해줘”가 약한 수정이라면, “저장 방식은 유지하고 에러 메시지 표현만 사용자가 다음 행동을 알 수 있는 문구로 바꿔줘. 성공 흐름은 건드리지 마. 수정 후 실패/성공 둘 다 확인해줘”가 좋은 수정이다. 바꿀 것, 유지할 것, 확인 시나리오를 함께 준다.
CLAUDE.md — 온보딩 문서를 파일로
매번 프로젝트 설명을 반복하던 문제는 CLAUDE.md로 해결됐다.
프로젝트 루트에 CLAUDE.md를 두면, 8단계 경로의 02. Context 단계에서 자동으로 읽혀서 모든 대화에 주입된다. 세션이 바뀌어도, 새 창을 열어도 Claude가 이 파일을 먼저 읽는다. 신규 팀원에게 프로젝트 온보딩 문서를 줬을 때랑 비슷한 효과다.
처음 이 블로그 프로젝트에 CLAUDE.md를 세팅할 때 이렇게 썼다.
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
# BigTae's Dev Log — 프로젝트 규칙
## 기술 스택
- Jekyll + Chirpy 7.5 + GitHub Pages
- 언어: 한국어 / 시간대: Asia/Seoul
## 브랜치 전략
- main: 배포 브랜치 (직접 커밋 금지)
- develop: 작업 브랜치 (여기서만 작업)
- develop → main PR → Merge = 발행
## 포스트 규칙
- 파일 위치: _posts/YYYY-MM-DD-제목.md
- Front Matter 필수: title, date, categories, tags
- 작성 스타일: 1인칭 구어체, "했다", "삽질했다"
- "본 포스트에서는", "알아보겠습니다" 사용 금지
## 완료 기준
- 새 포스트: Front Matter 형식 확인, develop 브랜치 커밋
- 배포: PR 생성 후 main으로 Merge
이걸 한 번 세팅해두니까 “이 프로젝트 Jekyll이야” 설명을 다시 안 해도 된다. Claude가 매번 이 파일을 읽고 시작하니까.
근데 처음엔 실수를 했다. “Claude가 알아야 할 게 많을수록 좋겠지” 싶어서 배포 절차, 카테고리 규칙, 포스트 아이디어 목록까지 다 집어넣었다. 결과적으로 CLAUDE.md가 200줄이 넘어갔다.
그랬더니 이상한 일이 생겼다. 파일 앞쪽에 쓴 “main 브랜치 직접 커밋 금지” 같은 중요한 규칙을 Claude가 자꾸 무시하기 시작했다. 컨텍스트 윈도우 안에서 앞 내용이 뒤 내용에 밀리는 것 같았다. 파일이 길어질수록 핵심 규칙이 묻힌다.
CLAUDE.md는 50줄 이하로 유지하는 게 맞다. 길어지면 짧아지게 만들어야 하는 신호다.
3층 기억 시스템
CLAUDE.md를 제대로 쓰려면 이 개념을 먼저 잡아야 한다. CLAUDE.md, SKILL.md, Lessons.md — 세 파일이 있는데 처음엔 다 같은 거라고 생각했다. 근데 역할이 완전히 다르다.
CLAUDE.md — 항상 필요한 규칙.
모든 대화에 자동으로 주입된다. 기술 스택, 브랜치 전략, 코딩 금지사항, 작업 완료 기준 같은 것들. “이 프로젝트에서 작업할 때 항상 알아야 할 것”을 담는다.
SKILL.md — 필요할 때 실행하는 절차.
/deploy, /debug 같은 슬래시 커맨드로 호출될 때만 로드된다. 배포 절차, 디버깅 체크리스트, 코드 리뷰 절차 같은 것들. 이걸 CLAUDE.md에 넣으면 코드 한 줄 수정할 때도 배포 절차 전체가 컨텍스트에 올라간다.
Lessons.md — 임시 교훈 후보.
세션 중에 실수한 것, “이건 주의해야겠다” 싶은 것을 그때그때 적어두는 파일이다. 나중에 이게 반복 확인되면 CLAUDE.md로 승격시키고, 한 번뿐인 실수면 버린다.
특강 슬라이드에 이 구분이 명확하게 나와 있었다.
“CLAUDE.md는 항상 필요한 규칙, Skill은 필요할 때 실행하는 절차다.
둘을 섞으면 메모리가 비대해지고 지시 준수력이 떨어진다.”
내가 CLAUDE.md를 200줄로 만들었을 때 정확히 이 문제였다. 배포 절차(SKILL이어야 할 것)와 프로젝트 규칙(CLAUDE.md에 있어야 할 것)을 한 파일에 때려넣었으니 비대해진 거다.
Lessons.md 승격 기준도 정해뒀다. 같은 실수를 세 번 이상 하면 CLAUDE.md에 올린다. 한 번짜리 실수는 올리지 않는다. 이 기준이 없으면 Lessons.md가 CLAUDE.md 비대화의 또 다른 경로가 된다.
CLAUDE.md에 넣을 것과 넣으면 안 되는 것
실제로 정리해보니까 이 기준이 제일 판단하기 어려웠다.
1
2
3
4
5
6
7
8
9
10
11
12
✅ CLAUDE.md에 넣을 것 (항상 필요한 규칙):
- 기술 스택 (Spring Boot 버전, DB 종류 등)
- 브랜치 전략, 커밋 전 필수 사항
- 코딩 금지사항 (System.out.println 금지 등)
- 파일 위치 규칙 (API 핸들러는 어디에 둬야 하는지)
- 작업 완료 기준
❌ CLAUDE.md에 넣으면 안 되는 것:
- 배포 절차 단계별 가이드 → .claude/commands/deploy.md로
- 버그 디버깅 체크리스트 → SKILL.md로
- API 전체 명세 300줄 → @docs/api-spec.md로 참조
- 지난번 버그 수정 과정 메모 → Lessons.md 후보
“코드 한 줄 수정할 때도 이게 필요한가?” 이 질문 하나로 판단이 된다. YES면 CLAUDE.md, NO면 따로 빼야 한다.
대용량 문서는 @파일명 문법으로 참조하면 된다. CLAUDE.md에 직접 쓰는 대신 “API 명세는 @docs/api-spec.md 참고”라고만 써두면, Claude가 API 관련 작업을 할 때만 그 파일을 로드한다. CLAUDE.md를 짧게 유지하면서 필요한 정보는 다 참조할 수 있게 된다.
CLAUDE.md는 3층으로 작동한다
CLAUDE.md는 하나가 아니다. 위치에 따라 세 층으로 나뉜다.
1
2
3
~/.claude/CLAUDE.md ← 내 모든 프로젝트에 적용
./CLAUDE.md ← 이 프로젝트 팀 전체에 적용
./backend/CLAUDE.md ← 이 폴더 작업 시에만 추가 적용
글로벌 파일(~/.claude/CLAUDE.md)에는 개인 선호를 넣는다. “항상 한국어로 답해줘”, “코드 설명할 때 주석 달아줘” 같은 것들. 매 프로젝트마다 이걸 반복하지 않아도 된다.
프로젝트 루트 CLAUDE.md는 git으로 관리해서 팀 전체가 같은 규칙으로 작업한다. 팀원이 Claude Code를 쓰든 나만 쓰든, 규칙이 코드베이스 안에 있으니 버전 관리도 된다.
서브폴더 CLAUDE.md는 모노레포나 프론트·백엔드가 한 레포에 있을 때 유용하다. 백엔드 폴더에서 작업하면 백엔드 규칙이 추가로 로드되고, 프론트 폴더에서 작업하면 프론트 규칙이 추가 로드된다. 세 층은 각자 대체하는 게 아니라 합쳐진다.
달라진 것
이걸 정리하고 나서 CLAUDE.md를 새로 썼다. 이 블로그 프로젝트 기준으로 딱 필요한 것만 넣었더니 50줄이 됐다. 이전 버전보다 절반 이상 줄었다.
달라진 게 체감으로 두 가지다.
하나, 세션 시작 설명이 없어졌다. Claude가 알아서 프로젝트 규칙을 알고 시작한다.
둘, 사이드 이펙트가 줄었다. 요청에 “유지 조건”을 명시하는 습관을 들이고 나서 “됐다는데 왜 이게 바뀌어 있어?” 케이스가 확 줄었다. 특히 수정 요청할 때 “A는 건드리지 마”를 한 줄 넣는 게 생각보다 효과가 컸다.
아직 SKILL.md, Hooks, Sub-agent는 제대로 세팅 안 했다. 다음 포스트에서 이어서 쓸 예정이다.