녀석과 만난지 벌써 두 달 - 클로드 코드 사용법, 내가 쓰는 기능과 스킬

녀석과 만난지 벌써 두 달

내가 클로드를 처음 사용한 날이 6월 23일이래.

그러니까 두 달이 조금 안 됐어. 그 사이에 블로그도 만들고 게임도 몇 개 만들고 유튜브 영상까지 하나 올렸으니 짧은 기간에 참 많이도 했다 싶네.

우선 오늘 할 얘기는 웹 브라우저로 쓰는 그 클로드가 아니라 클로드 코드야. 내 컴퓨터의 파일을 직접 조작할 수 있는 녀석이야. 나는 거의 클로드 코드만 사용하거든.

그래서 이제 사용해 본 스킬에 대해 얘기할텐데 처음엔 명령어 목록을 열어봐도 뭐가 뭔지 하나도 몰랐어. /를 치면 뭐가 주르륵 나오는데 이름만 봐서는 모르겠는 거지.

그런데 두 달쯤 지나니 손에 붙은 게 몇 개 생겼어. 재밌는 건 그게 남들이 첫손에 꼽는 기능이랑 좀 다르다는 거야. 아마 초보다보니 그런게 아니었을까. 정보가 없었거든.

오늘은 그 얘기를 해볼게. 내가 실제로 사용하는 것들 위주로.

조사가 반쯤 돌다 멈췄어

먼저 얘기해야 할 게 하나 있어. 내가 어쩌다 사용량 화면을 들여다보게 됐는지부터.

우리는 조사를 시킬 때 서브에이전트기능을 사용해. 녀석 밑에 일꾼을 여러 명 붙이는 셈인데 각자 다른 자료를 맡아서 뒤져.

조사할 내용이 많을 때 유용해. 한번에 하나씩 조사하는게 아니라 병렬로 조사할 수 있어서 시간을 절약할 수 있거든.

한 번은 서브에이전트 열 명을 한꺼번에 붙였어. 그런데 한참 뒤에 보니 멈춰 있는 거야.

"삼촌, 열 중에 아홉이 죽었어. 사용량 한도에 걸렸어."

전까지는 한도가 찰 만큼 일을 시킨 적이 없어. 그러다 조사가 커지고 하는 일이 많아지다 보니 처음으로 한도가 걸린 거야.

그때도 별생각은 없었어. 한도야 시간이 지나면 풀리는 거니까 그때 가서 다시 돌리면 그만이라고 여겼거든.

그러다 한도가 풀려서 다시 돌리려는데 녀석이 이러는 거야.

"토큰 때문에 죽어서 처음부터 다시 돌려야 해."

토큰 한도 때문에 멈추면 처음부터 다시 해야 한다고?

그제야 이 생각이 든 거야. 토큰도 토큰인데 시간을 또 써야 하는 게 더 싫었어.

그래서 뭐가 날아간 건데

"여태 한 건 하나도 안 남아?"

"남는 것도 있어. 그런데 삼촌이 걱정한 거랑 조금 달라."

녀석 말로는 이런 큰 조사를 워크플로라고 부르는데 중간에 멈춰도 다시 이어 붙일 수 있게 만들어져 있대. 끝난 에이전트의 결과는 어딘가에 적어두거든.

단 이건 워크플로로 돌렸을 때 얘기래. 에이전트만 여럿 붙인 건 해당이 없고.

만든 회사인 앤트로픽이 문서에 이렇게 적어놨어.

실행을 중지하면 재개할 수 있습니다: 이미 완료된 에이전트는 캐시된 결과를 반환하고 나머지는 라이브로 실행됩니다.

📄 출처 · 앤트로픽 공식 문서 「동적 워크플로우로 대규모 서브에이전트 조율하기」

여기까지만 보면 마음이 놓이잖아. 그런데 조건이 하나 더 붙어.

같은 문서 영어판엔 조건이 하나 더 붙어 있어.

Replay follows the order agents started. Cached results stop at the first agent that didn't finish, and every agent that started after that one runs again, even if it completed.

📄 출처 · 앤트로픽 공식 문서 「Orchestrate subagents at scale with dynamic workflows」

한꺼번에 시켰는데 순서가 왜 있나 싶었는데 동시에 붙여도 출발은 하나씩 매겨진대.

풀어보면 이래. 살아남는 건 먼저 출발한 순서대로 끊기지 않고 이어진 데까지야. 중간에 하나가 못 끝냈으면 그 뒤에 출발한 에이전트는 이미 끝났어도 전부 다시 돌아.

우리 경우엔 열 중에 하나만 살아남았어. 제일 먼저 출발한 놈이라 그거라도 건진 거지.

만약 살아남은 게 여덟 번째였으면 앞의 일곱이 안 끝났으니 그것도 같이 다시 돌았을 거야. 운이 좋았지.

마지막 줄이 제일 무서워. 창을 닫으면 그마저도 없어. 실수로 껐다가는 살아 있던 것까지 같이 버리는 셈이야.

"그럼 죽은 에이전트가 여태 쓴 건 그냥 날린 거야?"

"응. 결과를 못 냈어도 자료를 읽는 동안은 계속 깎였으니까."

얼마나 깎였냐고 물으니 71만 토큰이라더라(내 피 같은 토큰...). 토큰은 단어를 잘게 쪼갠 조각인데 쓴 만큼 한도에서 깎이는 단위야.

그러니까 그날 깎인 것 중에 손에 남은 건 에이전트 하나뿐이고 나머지는 그냥 사라진 거지.

그래서 /usage를 먼저 본다

그 뒤로 생긴 습관이 있어. 큰 걸 시키기 전에 /usage를 먼저 쳐보는 거야. 지금 한도가 얼마나 남았는지 보여주는 화면이야.

나는 VSCode를 쓰는데 계정 화면에서 같은 걸 볼 수 있어. 주로 그쪽으로 봐.

여기서 좋은 건 남은 양만 나오는 게 아니라는 거야. 뭐가 그걸 갉아먹고 있는지까지 쪼개서 보여주거든.

윗줄 둘은 사용량 얘기고 아랫줄 둘은 다음 절에서 할 얘기야.

MCP는 클로드에 바깥 도구를 붙이는 방식인데 지난 글에서 따로 다뤘어.

다만 이 화면을 믿을 때 알아둘 게 하나 있어. 공식 문서에 이렇게 적혀 있거든.

수치는 근사치이며 이 기기의 로컬 세션 기록에서 계산되므로 다른 기기 또는 claude.ai의 사용량은 포함되지 않습니다.

📄 출처 · 앤트로픽 공식 문서 「비용을 효과적으로 관리하기」

그러니까 한도는 웹이든 앱이든 다 합쳐서 세는데 이 화면은 이 컴퓨터에서 쓴 것만 계산한다는 거야. 폰으로 좀 쓰고 왔으면 화면에 보이는 것보다 실제로는 더 찼다는 뜻이지.

이걸 알고 나서는 화면 숫자를 딱 맞는 값으로 안 보게 됐어. 넉넉히 남았다 싶을 때만 큰 걸 시키는 정도야.

돈 내고 쓰는 입장에서 한도가 차면 별수가 없거든. 다시 열릴 때까지 기다리는 것 말고는 할 게 없어서 그 시간이 제일 아까워.

대화가 길어지면 정말 성능이 떨어지나

두 번째로 자주 치는 게 /context야. 지금 대화창이 얼마나 찼는지 보여주는 화면이지.

위쪽 막대가 전체 중 얼마나 찼는지고 아래가 뭐 때문에 찼는지야. 이 화면을 찍었을 땐 44퍼센트가 차 있었어.

눈에 띄는 건 비율이야. 대화 자체가 39퍼센트를 먹고 있고 내가 적어둔 지침이나 스킬은 다 합쳐도 몇 퍼센트가 안 돼. 자리를 잡아먹는 건 결국 주고받은 말이더라고.

이건 내가 알아낸 게 아니고 어디서 주워들은 거야. 기사였는지 영상이었는지는 기억이 안 나는데 컨텍스트가 차면 클로드가 제 기능을 못 한다는 얘기가 여기저기 있더라고.

그래서 글을 쓰는 김에 사실 조사를 해보기로 했어.

"이거 진짜야? 근거가 있는 얘기야?"

"있어. 그것도 앤트로픽이 문서에 대놓고 적어놨어."

대부분의 모범 사례는 하나의 제약 조건을 기반으로 합니다: Claude의 context window가 빠르게 채워지고, 채워질수록 성능이 저하됩니다.

📄 출처 · 앤트로픽 공식 문서 「Claude Code 모범 사례」

이게 어느 구석에 붙은 주의사항이 아니야. 사용법 문서를 여는 첫 문장이야. 여기서부터 시작한다고 못을 박아둔 거지.

증상까지 적혀 있어.

context window가 거의 가득 차면 Claude는 이전 지시사항을 "잊기" 시작하거나 더 많은 실수를 할 수 있습니다.

📄 출처 · 앤트로픽 공식 문서 「Claude Code 모범 사례」

읽고 나니 짚이는 게 있더라. 긴 작업을 하다 보면 어느 순간부터 아까 하지 말라고 한 걸 또 하고 있을 때가 있거든. 나는 그게 그날 녀석 상태가 안 좋은 줄로만 알았어.

"그럼 이게 AI 전체가 그런 거야, 아니면 클로드만 그런 거야?"

"전체야. 바깥에서 잰 것도 있어."

녀석이 연구자들이 잰 값도 찾아왔어. 2023년에 나온 논문 하나가 유명한 모양이야. 답이 들어 있는 문서를 자료 더미의 맨 앞에 두느냐 한가운데 두느냐로 성적이 갈리는지를 본 실험이래.

같은 모델에 같은 질문인데 정답 문서를 앞에 두면 75.8%를 맞히고 한가운데 묻어두면 53.8%로 떨어졌다는 거야.

For example, GPT-3.5-Turbo's multi-document QA performance can drop by more than 20%—in the worst case, performance in 20- and 30-document settings is lower than performance without any input documents (i.e., closed-book performance; 56.1%).

📄 출처 · Liu 외, 「Lost in the Middle: How Language Models Use Long Contexts」 (2023)

뒷부분이 더 뜨끔해. 자료를 스무 개 서른 개씩 넣은 경우가 아예 아무 자료도 안 준 경우보다 못했다는 거야. 도우려고 넣은 게 방해가 된 셈이지.

여기까지 듣고 그럼 무조건 짧게 가야 하나 싶었는데 녀석이 한쪽 말만 들으면 안 된다고 하더라고.

같은 종류의 다른 실험에서는 길이를 서른 배 넘게 늘려도 점수가 2.3점밖에 안 떨어진 모델도 있었어. 그러니까 길면 무조건 못 쓴다는 건 틀린 말이야. 얼마나 떨어지는지는 모델마다 다르고 해가 갈수록 나아지고 있고.

정리하면 방향은 맞는 얘기인데 정도는 사람들이 말하는 것만큼 떨어지진 않는다고 말하고 있어. 위 논문도 2023년 모델로 잰 거라 지금 것에 그대로 갖다 붙이면 안 되고.

다만 공식 문서에서도 언급하고 있는 만큼 컨텍스트 관리에 신경을 쓰는 게 좋을 거 같다는 생각이야. 내 경우에는 보통 50% 전후로 정리해서 사용하고 있어.

참고로 인터넷에 도는 얘기 중에 몇 퍼센트가 차면 자동으로 정리된다는 식의 숫자들이 있는데 그건 공식 문서에서 못 찾았어. 그래서 여기 안 적을게.

CLAUDE.md 파일 관리는 이렇게

기능 얘기에서 스킬 쪽으로 넘어가기 전에 그 사이에 있는 걸 하나 짚고 갈게.

CLAUDE.md라는 파일이 있어. 대화를 새로 열 때마다 녀석이 이걸 먼저 읽어. 여기 적어두면 매번 설명할 필요가 없거든.

우리는 이걸 층으로 나눠 뒀어. 어느 프로젝트에서 열든 적용되는 것, 블로그에서만 적용되는 것, 이런 식으로.

그런데 이게 자꾸 손톱처럼 자란단 말이지. 뭐 하나 겪을 때마다 다음엔 이러지 말자고 한 줄씩 붙이게 되거든.

그러다 어느 날 파일을 열어보고 좀 께름칙했어. 하지 말라는 목록만 길어지고 있었으니까.

"이거 이렇게 계속 늘리면 오히려 네가 일을 더 못하게 되는 거 아니야?"

"맞아. 그거 문서에도 적혀 있어."

느낌표까지 붙여서 적혀 있더라.

부풀려진 CLAUDE.md 파일은 Claude가 실제 지시사항을 무시하게 합니다!

📄 출처 · 앤트로픽 공식 문서 「Claude Code 모범 사례」

같은 문서 뒷부분은 더 야박해. 너무 길면 중요한 규칙이 잡음에 묻혀서 절반을 무시한다고 적어놨어.

재밌는 건 만든 사람들도 똑같이 하고 있다는 거야.

앤트로픽에서 일하는 사람이 지난 7월에 글을 하나 올렸어. 클로드 코드엔 시스템 프롬프트라는 게 있어. 회사가 제품에 미리 넣어둔 기본 지침인데 사용자는 못 건드리는 자리야.

그걸 80퍼센트 넘게 덜어냈다는 얘기야.

We removed over 80% of Claude Code's system prompt for models like Claude Opus 5 and Claude Fable 5 with no measurable loss on our coding evaluations.

📄 출처 · Thariq Shihipar(앤트로픽 기술 스태프), 「The new rules of context engineering for Claude 5 generation models」 (2026-07-24)

덜어냈는데 코딩 성적은 안 떨어졌다는 게 요지야. 모델이 좋아져서 굳이 시키지 않아도 알아서 하게 됐다는 거지.

클로드 코드를 만든 사람은 더 세게 말하더라고. 6개월마다 CLAUDE.md를 지워보라고, 스킬이랑 훅도 같이 지우고 모델이 어떻게 하는지 보면 놀랄 수도 있다고 했어. 훅은 정해진 시점마다 자동으로 실행되게 걸어두는 장치야.

📄 출처 · 보리스 체르니(클로드 코드 창시자), Y Combinator Startup School 2026 대담 (2026-07-27)

그런데 나 같은 초보 유저가 이걸 그대로 따라하기는 좀 무섭잖아. 그렇다고 완전 무시하기도 어렵고 말이야.

그래서 내 나름대로 규칙을 하나 만들었어. 매번 읽어야 하는 것만 남기고 지난 경위나 옛날 결정은 따로 빼두는 거야. 오래된 걸 빼는 게 아니라 안 읽는 걸 빼는 쪽으로.

정리하는 순서는 이렇게 했어.

1. 어디가 무거운지 먼저 본다앞에 나온 /context 화면이 항목별로 알려준다. 감으로 고르면 엉뚱한 걸 지운다.
2. 줄마다 묻는다「이게 없으면 AI가 실수하나?」 아니면 뺄 후보다.
3. 오래된 게 아니라 안 읽는 걸 뺀다날짜순으로 자르면 매번 봐야 할 것까지 같이 딸려 나간다.
4. 뺀 건 버리지 말고 딴 파일로 옮긴다필요할 때만 열면 되니까 없앨 이유가 없다.
5. 같은 내용을 두 곳에 두지 않는다한 곳만 정본으로 삼고 나머지는 경로를 적어둔다. 고칠 때 한 곳만 고치면 되니까.

두 번째는 내가 지어낸 게 아니야. 앤트로픽 문서에 "이것을 제거하면 Claude가 실수를 할까?" 라고 그대로 적혀 있어.

함정도 하나 알게 됐어. 대화 중간에 이 파일을 고쳐도 그 대화엔 안 먹혀. 이미 읽고 시작했으니까. 새로 열어야 반영돼.

절차를 파일로 굳혀둔 것, 스킬

스킬 얘기도 좀 해볼게.

스킬은 쉽게 말해 매번 채팅에 붙여넣던 긴 지시문을 파일 하나로 저장해두는 거야. 필요할 때 슬래시로 부르면 그때 열려.

나는 자주 하는 일부터 절차를 적어서 스킬로 옮겼어. 매번 같은 지시를 되풀이할 필요가 없어지더라고.

우리가 직접 만든 게 하나 있어. new-post라는 스킬인데 키워드 조사부터 발행까지 순서가 통째로 적혀 있어. 이 글도 그걸 불러서 쓰고 있고.

그 안에 humanizer라는 스킬도 걸어놨어. 한국어 글에서 AI 티가 나는 버릇 마흔 가지를 잡아주는 건데, 유튜브 보다가 알게 돼서 받아왔어.

DaleSeo라는 개발자가 깃허브에 공개해둔 거야. 받기 전에 안을 열어봤는데 스크립트도 없고 어디로 뭘 보내지도 않는 순수한 문서 뭉치더라고. 외부 스킬을 가져올 땐 조심하는 게 좋다고 알고있어.

한국어 AI 문장을 가려내는 연구를 바탕으로 뽑은 마흔 가지래.

매번 돌리진 않아. 이 블로그는 내 말투로 쓰다 보니 대체로 걸릴 게 없더라고. 대신 문장이 뻣뻣하게 읽힐 때 불러.

스킬이 왜 좋냐면 CLAUDE.md랑 성질이 정반대라서 그래.

앤트로픽도 같은 얘기를 해.

CLAUDE.md is loaded every session, so only include things that apply broadly. For domain knowledge or workflows that are only relevant sometimes, use skills instead. Claude loads them on demand without bloating every conversation.

📄 출처 · 앤트로픽 공식 문서 「Best practices for Claude Code」

CLAUDE.md는 매번 읽히니까 넓게 적용되는 것만 넣고, 어쩌다 한 번 쓰는 건 스킬로 빼라는 얘기야. 스킬은 부를 때만 열리니까 대화가 무거워지지 않는다는 거고.

처음부터 알고 나눈 건 아니야. CLAUDE.md가 뚱뚱해져서 옮길 데를 찾다가 여기가 맞겠다 싶었던 거지.

그리고 클로드에 기본으로 들어 있는 스킬도 있어. 내가 제일 많이 쓴 건 artifact-design이야. 아티팩트를 만들 때 클로드가 부르는 스킬이지.

아티팩트는 결과물을 웹 페이지 한 장으로 뽑아주는 건데, 나는 주로 썸네일 후보를 나란히 놓고 고르거나 표가 실제로 어떻게 보이는지 확인할 때 써. 오늘 이 글 썸네일도 그렇게 골랐고.

세어보라고 했더니 스무 번쯤 됐다네.

그런데 셋을 다 돌려도 마지막은 내가 읽어. 이 글도 거의 내가 쓰거든.

물론 글만 말이야. 표, 인용구 등 나머지는 다 이 녀석이 만든 거야. 나는 요청만 하고.

정리하고 보니 별로 없네

글을 쓰다 보니 처음 의도와 조금 다르게 흘러갔는데 나름 괜찮은 것 같아서 그냥 이렇게 갈게.

사례와 같이 글을 써서 그런가 몇 개 안 되네. 뭐, 아무튼.

슬래시로 부르는 건 위의 둘뿐이야. CLAUDE.md는 파일에 적어두는 거고, 스킬은 /스킬이름으로 부르고, 서브에이전트는 그냥 말로 시키면 돼.

그런데 지금 와서 보니 손에 붙은 건 전부 내가 어디서 데인 다음이더라고.

조사가 날아가고 나서 사용량 화면을 보게 됐어. 아까 한 말을 또 어기길래 컨텍스트를 보게 됐고 CLAUDE.md가 뚱뚱해지고 나서 스킬로 옮겼지.

순서가 반대였으면 아마 안 썼을 거야. 좋다는 얘기를 먼저 들었어도 내 일이 아니면 손이 잘 안 가니까.

스킬이나 기능은 너무 많은데 아직 안 써본 게 대부분이야. 손이 안 간 것들 말이야. 그중엔 진작 썼으면 좋았을 게 섞여 있을 것 같기도 하고 나한텐 끝까지 필요 없는 것도 있을 것 같아.

그래서 다음 포스트에는 클로드의 다른 기능과 스킬에 대해서 포스트를 한번 작성해볼까 해. 정리하다 보면 나도 얻을 게 있을 것 같거든.