멍청 탈출! Claude Code 3가지 원칙
FOMO 방지 비개발자 위한 클로드 코드 3가지 원칙
왜 내 클로드'만' 멍청한가
너도나도 클로드 코드 한다, 비개발자도 마케터도 교사도 쓴다고 해서 결제한 후기가 한 달 전이다. 링크드인과 유튜브에서 '당신만 모르는~', '아직도 몰랐다면~' 등 FOMO를 자극하는 고급 스킬도 부랴부랴 다운로드하였다.
그런데 내 클로드만 뭔가 멍청하다. 계속 뭔가를 빼먹고, 작업 다 했다는데 실행시켜 보면 빈 화면이 보인다. 똑같이 Claude Pro 결제했는데 왜 아직 나의 클로드는 멋진 마법을 부리기는커녕 홀라당 토큰을 태워먹고 있을까?
출처 : Harry Potter클로드코드 공식 계정이 말아주는 원칙
클로드 코드 Claude Code를 만든 Antrhopic에서는 공식 가이드를 도식화하여 설명해주고 있고, Best Practices 도 공식적으로 공유해주고 있다. 공식 계정에서 친절하게 말아주는 원칙과 꿀팁을 복습해 보도록 하자.
한 줄 요약? '요구사항을 똑바로 전달하고, 그다음은 클로드 코드 에이전트한테 믿고 맡겨라'이다.
요구사항을 똑바로 전달하고:
여러 가지 목적과 장황한 설명 대신, 하나의 대화창(세션)에서는 딱 하나의 목적을 명확한 명칭과 구조를 가지고 전달해야 한다는 것이다.
클로드 코드 에이전트한테 믿고 맡겨라:
그리고 당신이 직접 안 하고 클로드한테 데이터 분석이든 기획이든 개발이든 시켰으니 적당한 권한과 안전장치만 세팅하고 위임하라는 것.
클로드 공식계정에서는 뻔한 도덕책 같은 말을 좋은 예시, 나쁜 예시로 풀어두었던데, 기억하기 쉽도록 해리포터와 마법 세계를 가져와서 풀어보았다.
공식 원칙 1. 항상 따라야 하는 원칙과 톤은
매번 새로운 대화창, 새로운 프로젝트마다 '중학생이 이해하기 쉽게 설명해줘', '기다리지 말고 병렬로 해', '작업 시작 전에 필요한 것 먼저 질문해줘' 라고 말하고 있는가?
앞으로는 CLAUDE.md에 저장하자. 여기에 작성된 작업 원칙과 톤 앤 매너를 어떤 작업을 수행하던 (거의) 대부분 경우 따를 것이다.
물론 해당 마크다운 파일을 직접 찾고 직접 수정할 필요는 없다. 잔소리가 길어지면 클로드도 나도, 내 토큰(마나)도 지친다. "어떤 프로젝트를 하든 항상 ~ 확인해줘"라고 요구하면 CLADUE.md에 한 줄 추가되어 있을 것이다.
나의 CLAUDE.md에는 이런 내용이 적혀있다. Conventions 인지 User Work Style 인지 분류도 알아서.
## Conventions
- 한국어로 소통
- 비개발자(PM) 대상이므로 기술 용어 사용 시 쉬운 설명 병행
## User Work Style
- **항상 병렬 작업**: 작업 하나당 agent 하나. 무슨 작업이든 병렬로 진행. 모든 프로젝트 공통
- **완료 전 검증 필수**: 작업 완료를 주장하기 전에 실제 실행/확인. 추측으로 "됐습니다" 금지...
공식 원칙 2. 무엇을 어떻게 할 지만, 짧고 굵게
Skills 클로드 스킬에도 CLAUDE.md처럼 SKILL.md가 존재한다. 서로 다른 요구사항과 프로젝트 안에서 반복적으로 하는 스킬의 한 장짜리 '레시피'.
그런데 어느 순간 가볍게 시도해볼만한 레시피가 아니라 냄새가 폴폴 나는 요리 그 자체가 되었다. 다음에 재사용하는 것이 잘 안 되거나 엉뚱한 요리에 활용되어 버리고.
갓 세팅한 클로드 코드 순정판은 SKILL.md를 잘 구성해서 description에 짧고 굵게 '무엇을 어떻게 한다'만 잘 기록한다.
그런데 단순 '데이터 분석'으로 시작한 마법 주문에 '이런 칼럼과 형식으로'라는 구체적인 형식 요구사항이 들어가고, '평가해 줘', '누락 보정해 줘' 등등 최초 목적과 다른 요구사항이 들어가면 원형을 알 수 없는, 재사용 불가한 퓨전요리가 되어버린다.
출처 : Claude Code Best Practices그러면 어떻게 해야 레시피를 짧고 명확하게 유지할까?
Rule 1. 일반명사보다는 '동명사'로 지칭을 한다 (OO 말고, OO를 XX 하는 것)
Rule 2. 각 작업마다 번호를 매기고, 체크[v] 하면서 진행하도록 유도한다. 실제로 하나의 스킬 안에서 분석-계획-개발-배포 순서대로 해야 한다면 필수적이다.
Rule 3. 무엇을-어떻게 라는 단 하나의 레시피로만 단순하게 구성한다. "어묵김밥" 레시피를 만들면 만들었지, 김밥 레시피 중간에 어묵 레시피가 끼어들면 뭣도 아니게 되어버린다.
공식 원칙 3. 백이면 백 실행할 것은, 말로 말고
출처 : Claude Code Best Practices백이면 백 실행할 작업은 프롬프트 즉 말로 쓰지말고, 시스템 차원의 셋팅이 필요하다.
꼭 클로드 코드가 아니더라도 생성형 AI 서비스를 사용하다 보면 - Gemini 제미니, ChatGPT 챗지피티, Claude 클로드, Perplexity, Wrtn 등등 똑같은 대화를 했는데 다른 정보를 찾아주는 경우를 종종 접한다.
모델과 회사와 무관하게, 확률적 언어를 구사하는 생성형 AI의 특성상 그다음에 나올 확률이 가장 높은 단어를 뱉어내다 보니 조금씩 다를 수밖에 없다.
창작과 구현의 영역에서는 이러한 자유도가 큰 문제는 안 되겠지만, 문제는 프로젝트를 수행하면서이다. 필수적인 보안 검사, 동일한 형식 유지, 무한 루프 종료 등은 안정적인 운영과 품질을 위해서는 항상 실행되어야 하는 것이다. 언제는 했다가 언제는 안 했다가 할 수는 없는 법.
이럴 때 if-then, 어떤 조건이 만족되면 무조건 XX를 해야 한다, 시스템 차원에서 설정하는 것이 대안이 될 수 있는데 그것을 Hook 훅이라고 한다.
멍청 탈출 클로드 공식 원칙 3가지 요약 그리고
클로드 코드 공식 7가지 마법은 이전 글에서도 소개한 바 다음과 같다.
그중 mcp, plugin 등은 외부의 자산을 활용하는 부분이라 아무 말 프롬프트 대잔치로 멍청해질 가능성이 없다.
1. 항상 따라야 하는 원칙과 톤은 : CLAUDE.md
2. 무엇을 어떻게 하는지만 짧고 굵게 : SKILL.md
3. 백이면 백 실행할 것은 말로 말고 : Hooks 훅
머글로서 이것저것 클로드한테 개떡같이 이야기해도 찰떡같이 알아먹어서 신기했는데 그 과정에서 이런저런 부산물이 쌓이면서 불필요한 테스트 파일, 불필요한 스킬 설명이 길어졌다. 그래서 공식 링크를 전달하고 요구했다.
"https://code.claude.com/docs/en/best-practices 공식 가이드 준수했는지 검토해 줘.
나의 클로드는 이제 (여기서 더) 멍청해지지는 않는다.
SKILL.md에서 '무엇과 어떻게'를 넘어서는 내용들은 자동으로 references 참조 폴더와 outputs 산출물 폴더로 분리해서 적재하게 되었다.
내가 자주 물어보는 확인 질문은 광역 원칙이라 판단되면 CLAUDE.md의 User Style에 기록한다. 그 중에서 보안, 포맷팅 등 기능적인 요구사항은 hooks로 제안한다.
생성형 AI의 환각과 중복을 막고 원활한 운영을 위해 오늘도 똑똑한 분들이 좋은 Skills과 Plugin을 오픈소스로 공유해주고 계시다. 그리고 점점 더 많은 웹서비스들이 MCP를 제공하면서 편하게 터미널 창 안에서 DB를, 캘린더를, 회의록을 가져오고 수정할 수 있게 되었다.
이런 좋은 자산을 활용 엄청난 마법을 부리기에 앞서 당신의 클로드에게 최소한 공식계정이 말아주는 가이드와 지침은 검토하게 하는 기초 체력을 만들어주는 것은 어떨까.
져니박 씀.