내 클로드 코드 세팅

지난주에 세팅을 전부 갈아엎었다. 스물 몇 개가 쌓여 있었는데 절반은 언제 왜 깔았는지 기억이 안 났고, 코드 리뷰를 하는 물건은 세 개나 켜져 있었다. 어느 게 도는지도 모르고 결과만 받아본 셈이다.

정리하고 나서 지금 쓰는 게 이거다. 플러그인 열셋, 직접 만든 스킬 넷, CLAUDE.md 56줄. 뭘 왜 골랐는지 하나씩 적는다.

먼저, 세팅이 뭘로 이루어져 있나

클로드 코드는 터미널에서 도는 AI 코딩 도구다. 채팅창에 코드를 복붙하는 방식과 달리 내 컴퓨터의 파일을 직접 읽고 고치고 명령어를 실행한다. 그래서 "이 폴더에서 이렇게 일해라"를 미리 정해줄 수 있고, 그 정해주는 게 세팅이다. 용어가 좀 많은데 다섯 개만 알면 아래 내용이 전부 읽힌다.

이름	무엇인가	언제 작동하나
CLAUDE.md	작업 규칙을 적어둔 텍스트 파일	항상. 대화 시작할 때 통째로 읽힌다
플러그인	남이 만든 기능 묶음. 명령어 한 줄로 설치	설치하면 계속 켜져 있다
스킬	특정 상황용 설명서 한 장	그 상황이 오면 꺼내 읽는다
훅	정해둔 시점에 자동 실행되는 스크립트	그 순간마다 예외 없이
MCP	외부 프로그램을 연결하는 규격	그 프로그램이 필요할 때

비유하자면 CLAUDE.md는 신입에게 첫날 주는 근무 수칙이다. 짧아야 읽는다. 플러그인과 스킬은 책상에 올려주는 도구다. 많으면 어느 걸 쓸지 헷갈린다. 훅은 "퇴근할 때 무조건 책상 정리"처럼 예외 없이 도는 규칙이다. 여기에 둘이 더 붙는데, 모델은 어떤 AI를 쓸지고 추론 강도는 답하기 전에 얼마나 오래 생각할지다.

미리 알아두면 좋은 게 하나 있다. 위의 것들은 전부 AI가 읽는 글자를 차지한다. AI가 한 번에 읽을 수 있는 양은 정해져 있고 이걸 컨텍스트라고 부른다. 규칙 파일이 길고 스킬이 스무 개면 그만큼이 매번 채워진 채로 시작한다. 세팅을 줄여야 하는 첫 번째 이유가 여기 있다.

판단 기준 넷

새 물건을 깔지 말지 이 넷으로 거른다.

전역 세팅만 쓴다

설정을 두는 자리가 둘이다. 홈 폴더의 ~/.claude/는 모든 작업에 적용되고, 프로젝트 폴더의 .claude/는 그 프로젝트에서만 적용된다. 나는 전부 앞쪽에 둔다.

내 작업 습관은 레포가 바뀐다고 달라지지 않기 때문이다. "증거 없이 완료라고 말하지 마라"는 규칙이 이 프로젝트에서는 되고 저 프로젝트에서는 안 될 이유가 없다. 프로젝트별 설정은 팀 컨벤션이 특이하다거나 빌드 방식이 남다를 때 의미가 있는데, 혼자 쓰는 레포에는 그런 게 거의 없다.

부수 효과가 은근히 크다. 새 프로젝트를 시작할 때 세팅할 게 없어서 폴더 만들고 바로 일한다.

행동 규칙과 기능을 섞지 않는다

"어떻게 일해야 하는가"는 CLAUDE.md에 쓰고, "무엇을 할 수 있는가"는 플러그인에 맡긴다.

섞기 시작하면 CLAUDE.md에 "이 도구는 이렇게 쓰고, 저 명령어는 이런 옵션이 있고" 같은 사용법이 들어온다. 그러면 파일이 길어지고, 길어지면 안 읽힌다. 정확히는 AI가 앞부분만 반영하고 뒤쪽은 흐릿해진다. CLAUDE.md의 유일한 실패 조건이 이거라서 사용법은 전부 밖으로 뺐다.

항상 옳은 것만 자동화한다

가끔 틀리는 건 손으로 켠다. 이게 뒤에 나올 좀 이상한 선택 하나를 만들었다.

역할이 겹치면 하나만 남긴다

같은 일을 하는 물건이 둘 있으면 어느 쪽 때문에 그 결과가 나왔는지 알 수 없다. 리뷰 도구가 세 개였던 게 정확히 그 상태였다. 판단은 한 달로 한다. 지난 한 달에 한 번도 안 썼으면 지운다. "언젠가 쓸 것 같다"는 예측보다 지난 한 달을 세는 게 정확하다.

플러그인

플러그인은 명령어 한 줄로 깔리고, 깔면 계속 켜져 있다.

사고 방식을 바꾸는 셋

기능을 더해주기보다 AI가 일하는 태도를 바꾸는 쪽이다. 결과가 제일 많이 달라졌다.

superpowers 작업 절차서 열네 종 묶음이다. 브레인스토밍, 체계적 디버깅, 테스트 먼저 쓰기, 완료 전 검증 같은 것들. 개별 절차서보다 중요한 건 "작업 시작 전에 해당 절차서를 먼저 읽으라"는 강제 규칙 쪽이다.

AI에게 버그를 고치라고 하면 대개 코드부터 고친다. 증상을 보고 그럴듯한 곳을 짚어서 바로 수정한다. 맞을 때도 있는데, 틀리면 원인은 그대로 두고 증상만 덮어서 같은 버그가 다른 자리에서 또 나온다. 이걸 깔면 순서가 바뀐다. 재현하고, 원인을 좁히고, 고치고, 다시 확인한다. 시간은 더 걸리는데 두 번 고치는 일이 줄었다.

ponytail 게으른 시니어 개발자 모드다. 코드를 쓰기 전에 네 개를 순서대로 확인하고 먼저 걸리는 데서 멈춘다.

1. 이게 필요하긴 한가
2. 이미 코드베이스에 있나
3. 표준 라이브러리로 되나
4. 한 줄로 되나

채용한 이유는 LLM의 가장 확실한 약점 때문이다. AI는 시키지 않은 걸 만든다. 캐시 하나 붙여달라고 하면 캐시 클래스를 설계한다. 만료 정책이 있고, 통계를 수집하고, 설정 파일까지 딸려 나온다. 언뜻 잘 만든 것 같은데 실제로 필요했던 건 파이썬에 원래 있는 기능 한 줄이다.

@lru_cache(maxsize=1000)
def fetch(url): ...

함수 위에 저 한 줄을 붙이면 같은 입력에 대한 결과를 알아서 저장해둔다. ponytail은 아까 그 클래스를 이걸로 되돌린다. 짧게 쓰라고 시켜서 짧아지는 게 아니고 필요한 것만 쓰다 보니 짧아진다. 체감이 제일 컸다. 코드가 적으면 읽을 것도 적고, 고칠 것도 적고, 망가질 것도 적다.

caveman 출력을 압축한다. 이런 답이

물론입니다! 기꺼이 도와드리겠습니다. 말씀하신 문제는 여러 가능성을 검토해본 결과 토큰 만료를 검사하는 부분에서 비교 연산자가 잘못 사용된 것이 원인일 가능성이 높습니다.

이렇게 나온다.

인증 미들웨어 버그. 토큰 만료 검사에 <= 대신 <. 수정

오해하기 쉬운 게 하나 있다. 출력만 짧아지지 AI가 속으로 생각하는 양은 그대로라, 비용보다는 읽는 시간이 주는 쪽이다. 그런데 그것보다 좋은 게 있다. 내용 없는 문장이 사라지니까 내용이 있는지 없는지가 바로 보인다. 위쪽 답은 길어서 뭔가 열심히 검토한 것처럼 보이는데 실제 정보는 마지막 한 줄뿐이다. 예의 바른 문장은 빈 답변을 가려준다. 그게 사라지면 답이 부실할 때 부실한 게 그냥 보인다.

정보를 가져오는 것

앞의 셋이 태도라면 이쪽은 눈과 손이다.

typescript-lsp, pyright-lsp 언어 서버다. 에디터가 함수 정의로 점프시켜주고 오타에 빨간 줄을 그어주는 그 기능인데, 그걸 AI도 쓰게 해준다.

필요한 이유는 AI가 없는 함수를 부르기 때문이다. 이름이 그럴듯하면 있을 거라고 가정하고 쓴다. user.getFullName() 같은 게 실제로는 없는데 코드에 들어간다. 언어 서버가 붙어 있으면 그 자리에서 걸린다.

playwright, chrome-devtools-mcp 브라우저를 실제로 열어서 조작한다. 화면을 캡처하고, 버튼을 누르고, 콘솔 오류를 읽는다.

프론트 작업에서 특히 필요하다. AI가 "수정했습니다"라고 하는데 화면이 깨져 있는 경우가 많다. 내 CLAUDE.md에 "UI는 브라우저로 열어봐야 인정한다"고 적어뒀는데, 이 둘이 없으면 그 규칙을 지킬 방법 자체가 없다.

last30days 최근 30일치 커뮤니티와 시장을 훑는다. 레딧, 해커뉴스, 웹.

AI 모델은 학습 시점 이후를 모른다. 요즘 뭐가 뜨는지, 내가 만들려는 게 이미 있는지 물어보면 그럴듯하게 틀린 답을 준다. 검색 상위 글 대신 사람들이 실제로 반응한 글을 가져오는 게 이 도구의 요점이다.

나머지

security-guidance는 보안 판단을 돕고, ralph-loop는 조건이 만족될 때까지 같은 작업을 반복시킨다. 내가 만들고 있는 검증 도구도 깔아뒀는데 이건 자동 실행을 안 건다. 이유는 아래에 적는다.

CLAUDE.md 56줄

대화를 시작할 때마다 통째로 읽히는 규칙 파일이다. 홈 폴더에 하나 두면 모든 작업에 적용된다.

내용은 카파시가 정리한 LLM 코딩 지침을 압축했다. AI에게 코딩을 시키며 밟은 함정들을 모아둔 문서다. 전문 버전과 압축 버전을 둘 다 만들어두고 압축본을 골랐다. 앞에서 말한 이유 그대로다. 길면 안 읽힌다.

1. 코딩 전에 생각하기. 가정을 명시하고, 해석이 여러 개면 전부 제시하고, 더 단순한 방법이 있으면 말한다.
2. 단순함 우선. 문제를 푸는 최소한의 코드. 요청 범위 밖의 기능은 만들지 않는다.
3. 외과적 변경. 건드려야 할 것만 건드린다. 인접 코드를 개선하지 않고, 안 망가진 걸 리팩터링하지 않고, 기존 스타일을 따른다.
4. 목표 주도 실행. 작업을 검증 가능한 목표로 바꾸고 통과할 때까지 돈다.
5. 증거 기반 완료. "완료"는 증거를 요구하고 서술로는 인정하지 않는다. 테스트와 빌드는 실제로 돌린 종료 코드만, 파일은 디스크를 확인해야, UI는 브라우저로 열어봐야 인정한다.
6. 인수인계. 긴 작업이 끝나거나 대화가 지워지려 하면 먼저 인수인계 노트를 쓴다.
7. 문체. 산출물에 대시와 콜론을 쓰지 않는다. 답변은 짧게. 한국어로 물으면 한국어로 답한다.

네 개는 설명이 필요하다.

3번이 왜 있나. AI에게 함수 하나를 고쳐달라고 하면 옆에 있는 코드도 같이 손댄다. 변수명을 바꾸고, 주석을 추가하고, 비슷한 패턴을 통일한다. 선의인데 문제가 된다. 변경 사항에서 내가 요청한 게 어느 줄인지 찾을 수가 없고, 뭔가 깨졌을 때 원인 후보도 그만큼 늘어난다. 그래서 판정 기준을 붙여뒀다. 바뀐 모든 줄이 요청으로 곧장 추적되는가.

4번은 조건을 어떻게 쓰느냐가 전부다. "코드 깔끔하게 해줘"는 채점이 안 돼서 언제 끝났는지 알 수 없다. "테스트가 전부 통과하고 그 결과를 보여줄 것"은 된다. 뭘 하라고 말하는 대신 성공 기준을 주는 쪽으로 쓴다.

5번이 제일 중요하다. 6개월 쓰면서 제일 자주 겪은 사고가 "다 됐습니다"인데 안 된 경우였다. 테스트를 돌렸다고 하는데 안 돌렸거나, 파일을 만들었다고 하는데 없거나, 화면이 잘 나온다고 하는데 안 열어본 경우다.

이게 거짓말은 아니다. AI는 코드를 다 썼으니 논리적으로 될 거라고 판단하고 그 판단을 완료로 보고한다. 사람도 하는 실수인데, 사람은 보통 한 번 돌려보고 AI는 안 돌려도 확신에 차 있다는 게 다르다. 그래서 완료의 근거로 인정하는 걸 실제 실행 결과로 못박았다. 이 한 줄이 나머지 여섯 개보다 시간을 많이 아꼈다.

7번은 사소해 보이지만 실용적인 이유가 있다. 대시를 남발하는 문장은 AI가 쓴 티가 난다. 커뮤니티 글이나 커밋 메시지에 그 흔적이 있으면 신뢰가 깎인다. 나는 레딧에서 대시 하나 때문에 글 전체가 슬롭 취급을 받아봤다.

스킬 넷

스킬은 플러그인보다 가볍다. 특정 상황에 꺼내 읽는 설명서 한 장이고, 직접 만들어 ~/.claude/skills/에 넣으면 된다.

스킬	용도
handoff	대화를 인수인계 문서로 압축
design-taste-frontend	프론트 작업에 UI 규칙 강제
computer-use	로컬 앱 창 조작
orca-cli	워크트리와 터미널 조작

적게 유지하는 데 이유가 있다. 스킬 본문은 필요할 때만 열리는데 언제 쓰는 물건인지 설명하는 한 줄은 항상 올라와 있다. 개수가 늘면 모델이 어느 걸 써야 할지 헷갈린다. 비슷한 설명이 여러 개면 엉뚱한 걸 부르거나, 확신이 안 서서 아무것도 안 부른다.

첫 번째 것은 앞에서 말한 컨텍스트 문제를 다룬다. 대화가 길어지면 AI가 멍청해지는 느낌이 있는데 기분 탓이 아니다. 서류가 쌓인 책상처럼 필요한 한 장을 못 찾는 상태가 된다. 그래서 대화를 비우기 전에 인수인계 문서부터 쓰게 만든다. 정한 것, 만든 파일, 다음에 할 일. CLAUDE.md 6번과 짝이다.

두 번째 것은 기능 대신 취향을 강제하는 스킬이라 좀 특이하다. LLM에게 웹 페이지를 만들라고 하면 통계적으로 뻔한 데로 수렴한다. 가운데 정렬된 큰 제목, Inter 폰트, 보라색 그라데이션, 3열로 늘어선 카드. 학습 데이터에 그런 게 제일 많으니까 그렇게 나온다. 내가 바이브 코딩 냄새라고 부른 것이 정확히 그 화면이다. 이 스킬은 그것들을 금지 목록에 올리고 폰트·그림자·여백 규칙까지 지정한다. 모델의 기본 편향을 규칙으로 눌러놓는 셈이다.

훅을 거의 안 쓴다

훅은 "코드를 수정할 때마다 포매터 실행"처럼 정해둔 순간에 자동 실행되는 스크립트다. 내 세팅에는 거의 없고, 대신 세션마다 두 개를 손으로 켠다.

/caveman full     출력 압축
/ponytail full    최소 코드

자동화할 수 있는데 안 한다. 모드가 방해되는 세션이 있어서다. 남에게 보낼 문서를 쓸 때 caveman이 켜져 있으면 조사가 빠지고 문장이 토막 난다.

여기가 제일 반직관적인 부분이다. 나는 에이전트의 완료 주장을 검증하는 도구를 만들고 있다. 에이전트가 "완료했습니다"라고 하면 그 말을 가로채서 테스트와 빌드를 실제로 다시 돌려보는 물건이다. 그런데 정작 내 세팅에는 그 훅이 없다.

자기가 만든 걸 왜 안 거나? 훅은 조용히 실행되고 조용히 실패한다. 잘 돌 때는 안 보이니 편한데, 뭔가 이상할 때 원인 후보가 하나 늘어난다. 내가 잘못 시킨 건지, 모델이 틀린 건지, 훅이 죽은 건지 구분하는 데 시간이 든다. 그리고 문서 한 줄 고치는 작업에까지 전체 테스트가 도는 건 낭비다.

그래서 완료 선언이 미심쩍을 때, 또는 남에게 보낼 결과물일 때만 손으로 돌린다. 앞의 "항상 옳은 것만 자동화한다"가 여기서 나온 기준이다. 검증은 항상 옳은 게 아니고 대개 옳은 것이고, 대개 옳은 건 내가 판단해서 켠다.

모델과 추론 강도

추론 강도는 답하기 전에 얼마나 오래 생각할지를 정하는 값이다. 제일 높은 값으로 박아뒀다. 모델은 작업에 따라 바꾼다.

여기서 기준이 남들과 좀 다르다. 보통은 "이 작업에 필요한 최소 모델"을 찾는데, 나는 반대로 충분히 풀 수 있는 쪽으로 과하게 배정한다.

계산이 안 맞아서다. 작은 모델로 돌려서 틀리면 내가 발견하고, 다시 지시하고, 다시 검토해야 한다. 그 왕복에 드는 내 시간이 모델 비용 차이보다 훨씬 비싸다. 틀린 걸 못 잡고 지나가면 나중에 더 크게 돌아오고.

만들고 있는 도구의 벤치마크가 이걸 뒷받침한다. 작업 34개를 세 번씩 돌려서, 실제로는 안 됐는데 됐다고 보고한 비율을 셌다.

모델	거짓 완료 보고
프론티어 모델	0.0퍼센트
작은 모델	6.0퍼센트

프론티어 모델은 그 시점에 제일 성능이 높은 모델을 말한다. 100번 중 6번이면 별것 아닌 것 같은데 실제로는 그렇지 않다. 나머지 94번이 멀쩡하니까 보고를 믿게 되고, 믿게 되면 6번을 안 열어본다. 틀린 게 통과하는 경로가 그렇게 생긴다.

싼 모델은 싸게 일하지 않았다. 틀린 걸 맞다고 말하는 빈도가 높았고, 그게 진짜 비용이다.

기타 둘

커밋 메시지 끝에 자동으로 붙는 생성 도구 서명을 껐다. 커밋 로그는 코드 이력이지 도구 이력이 아니니까. 그리고 권한은 자동으로 뒀다. 파일을 고칠 때마다 확인받으면 흐름이 끊겨서, 되돌리기 어려운 작업은 CLAUDE.md와 프롬프트로 막는 쪽을 택했다. 위험을 없앤 게 아니고 옮긴 거라 이건 취향에 따라 갈릴 수 있다.

이 조합이 왜 굴러가나

여기까지가 목록이고, 이제 왜 이렇게 묶었는지를 적는다. 사실 이게 제일 하고 싶은 얘기다.

정리하다 보니 도구들이 제각각인 게 아니었다. LLM이 실패하는 방식이 몇 가지로 정해져 있고, 각 도구가 그중 하나씩 맡고 있었다.

LLM이 이렇게 실패한다	이게 막는다
시키지 않은 걸 만든다	ponytail, CLAUDE.md 2·3번
안 됐는데 됐다고 한다	CLAUDE.md 5번, 언어 서버, 브라우저 도구
절차 없이 뛰어든다	superpowers
대화가 길어지면 앞을 잃는다	handoff, CLAUDE.md 6번
내용 없이 길게 말한다	caveman, CLAUDE.md 7번
학습 시점 이후를 모른다	last30days
뻔한 디자인으로 수렴한다	design-taste-frontend

이 표를 만들고 나서 뭘 더 깔지 판단하기가 쉬워졌다. 새 도구를 보면 어느 칸에 들어가는지를 먼저 본다. 이미 누가 앉아 있는 칸이면 안 깐다.

층으로 보면 이렇게 나뉜다.

항상 켜져 있는 것    CLAUDE.md          어떻게 일할지
상황에 따라 도는 것   플러그인, 스킬      무엇을 할 수 있는지
내가 켜는 것         모드, 검증          판단이 필요한 것

맨 아래 줄에 뭘 둘지가 제일 어려웠다. 자동화하면 편한데, 편하다고 다 올리면 내가 판단을 안 하게 된다.

결국 세팅을 잘 한다는 게 좋은 걸 많이 까는 일이 아니었다. 내 작업 방식을 파일로 적어두는 일에 가까웠다. 갈아엎기 전에는 그게 어디에도 안 적혀 있었고, 그래서 리뷰 도구가 세 개였던 거다.