클로드 코드 심화 마무리: 체크리스트와 흔한 실수

"CLAUDE.md도 만들고 스킬도 만들고 훅까지 걸었는데, 이게 다 제대로 붙은 걸까요?"

이 구간에서 가장 많이 걸리는 실수는 여섯 가지입니다. CLAUDE.md가 길어져 매 세션 비용이 되는 것, 스킬을 만들었는데 Claude(클로드)가 안 부르는 것, 짧은 일에 서브에이전트를 써서 오히려 느려지는 것, 플러그인을 설치만 하고 안 쓰는 것, 자동으로 도는 게 늘수록 뭐가 도는지 모르게 되는 것, 예약 작업이 요금제나 플랫폼 조건 때문에 안 도는 것입니다. 지난 레슨에서 훅과 예약으로 손을 뗐다면, 오늘은 다섯 장치 중 어디서 걸렸는지 점검하고 트랙을 닫는 차례입니다. 어디서 막혔는지 헷갈려서 오셨다면 이 레슨만 보셔도 됩니다.

트랙 점검표

앞의 여섯 레슨에서 한 번씩 손으로 해본 것들입니다. 읽어서 아는 것과 해본 것은 다르니 O와 X로만 표시해 보시기 바랍니다.

1. .claude와 ~/.claude를 열어 다섯 장치가 실제로 어디 놓이는지 확인했다.
2. 프로젝트 CLAUDE.md에 형식, 표기 규칙을 적고 /context로 로드된 걸 확인했다.
3. 마켓플레이스를 등록하고 플러그인 하나를 실제로 설치해 /plugin의 Installed 탭에서 확인했다.
4. 반복 절차를 SKILL.md로 만들어 슬래시 명령으로 실제 실행해봤다.
5. 서브에이전트 파일을 만들어 실제로 위임하고 요약 결과를 받아봤다.
6. 훅 하나를 걸어 /hooks에서 등록을 확인하고 실제로 발동시켜봤다.
7. 예약(클라우드 루틴 또는 데스크톱 예약 작업) 방식 하나를 골라 요금제, 플랫폼 조건을 확인했다.

흔한 실수 여섯 가지

X가 찍히는 자리는 대체로 정해져 있습니다. 앞 레슨에서 짚었던 함정들이 실제로는 여기서 다시 걸립니다.

실수 1. 길어진 CLAUDE.md가 매 세션 비용

세션을 열 때마다 살짝 굼뜨고, Claude가 정작 중요한 규칙을 놓치기 시작한다면 이 증상입니다. 레슨 2에서 확인했듯 CLAUDE.md는 세션을 시작할 때마다 전체가 컨텍스트에 그대로 로드되고, 200줄 권장선을 넘겨 참고자료나 튜토리얼까지 욱여넣은 게 원인입니다. 200줄 이하로 유지하고, 항상 필요하지는 않은 절차는 레슨 4에서 배운 스킬로 옮기는 편이 해결입니다.

실수 2. 스킬을 만들었는데 클로드가 안 부르는 것

/스킬이름으로 직접 부르는 건 되는데 메뉴에 설명이 안 뜨거나, 관련 대화를 해도 Claude가 알아서 쓰지 않는다면 이 증상입니다. 레슨 4에서 짚었듯 description이 모호하거나, frontmatter YAML의 들여쓰기나 콜론 뒤 띄어쓰기가 깨져 본문은 읽히는데 frontmatter만 빈 채로 처리되는 게 원인입니다. description을 구체적인 상황으로 다시 쓰고, claude --debug로 열어 파싱 오류가 있는지 확인하면 해결됩니다.

실수 3. 짧은 일에 서브에이전트 쓰기

파일 하나 값을 확인하는 정도의 일인데도 새 컨텍스트가 열리고 결과가 돌아올 때까지 기다리게 된다면 이 증상입니다. 레슨 5에서 확인했듯 서브에이전트는 검색 결과나 로그로 대화창을 채울 만큼 큰 부작업에 쓰도록 설계됐는데, 그 기준에 못 미치는 짧은 확인까지 위임한 게 원인입니다. 결과를 실시간으로 봐야 하거나 금방 끝나는 일은 직접 하고, 대화창을 채울 만한 부작업만 서브에이전트에 맡기면 해결됩니다.

실수 4. 플러그인을 설치만 하고 안 쓰는 것

스킬 메뉴는 늘어났는데 정작 뭘 설치했는지, 왜 설치했는지 기억이 안 난다면 이 증상입니다. 레슨 3에서 짚었듯 설치 전 인벤토리를 보지 않고 일단 설치부터 한 게 원인이고, Claude Code(클로드 코드)는 2주 넘게, 10세션 넘게 안 쓴 플러그인을 "Not used recently"로 따로 모아 보여줍니다 (2026년 8월 기준 동작). 설치 전 인벤토리(담긴 스킬, 훅, MCP)를 먼저 보고, /plugin의 Installed 탭에서 안 쓰는 플러그인을 주기적으로 정리하면 해결됩니다.

실수 5. 뭐가 자동으로 도는지 모르게 되는 것

왜 이 파일이 자동으로 고쳐졌는지, 왜 이 알림이 왔는지 설명이 안 된다면 이 증상입니다. 레슨 6에서 짚었듯 훅의 matcher를 비워두거나 넓게 잡아 의도하지 않은 상황까지 발동한 게 원인입니다. matcher를 최대한 좁게 잡고, /hooks로 지금 걸려 있는 훅 목록을 가끔 다시 점검하면 해결됩니다.

실수 6. 요금제 조건에 막혀 안 도는 예약 작업

매달 1일에 뜨기로 한 리포트 초안이 안 뜬다면 이 증상입니다. 레슨 6에서 확인했듯 컴퓨터를 꺼둔 채로도 돌아야 하는 클라우드 루틴은 Free 플랜에서 지원되지 않고, 데스크톱 예약 작업은 컴퓨터가 잠들어 있으면 건너뛴 뒤 지난 7일 안에서 가장 최근 것 한 번만 따라잡는 게 원인입니다. 컴퓨터를 꺼둘 일이 많다면 클라우드 루틴 쪽 플랜 조건을 먼저 확인하고, 로컬 예약이라면 컴퓨터를 깨어 있게 해두거나 놓친 실행을 전제로 프롬프트 자체에 안전장치를 넣으면 해결됩니다.

여정이 끝난 다음

체크리스트에 O가 다섯 개 이상 찍혔다면 성장 계단 다섯 트랙을 전부 지나온 셈입니다. 트랙 ①에서 AI에게 처음 말을 걸었고, 트랙 ①.5에서 아티팩트와 프로젝트로 작업실을 차렸고, 트랙 ②에서 외부 서비스를 연결했고, 트랙 ③에서 터미널로 넘어와 Claude Code를 처음 켰고, 이 트랙에서 CLAUDE.md와 스킬, 서브에이전트, 훅과 예약으로 내 방식대로 길들였습니다.

더 깊이 갈 방향도 있습니다. 레슨 5에서 스쳐 지나간 에이전트 뷰, 에이전트 팀, 동적 워크플로우가 그 자리입니다. 여러 세션을 흩어두고 나중에 확인하거나, 여러 에이전트가 협업하거나, 대규모 작업을 스크립트로 조율하는 기능인데, 지금 단계에서 필요한 것보다 크고 개발자 영역에 가까워 이 트랙에서는 다루지 않았습니다. 지금 당장 손을 댈 필요는 없고, 서브에이전트 하나로는 감당이 안 되는 규모의 일이 실제로 생겼을 때 이름만 기억해두면 충분합니다.

스킬, 플러그인, 서브에이전트, 훅은 전부 Claude Code 자체 기능이라 릴리스마다 세부가 바뀝니다. 이 트랙 여섯 편에 적힌 명령어나 화면 구성도 예외가 아닙니다. 이 트랙에서 배운 걸 발판 삼아, 몇 달에 한 번씩 공식 문서의 변경 사항을 훑어보는 습관을 들이면 됩니다. 다섯 장치의 역할 구분과 배우는 순서라는 뼈대는 쉽게 바뀌지 않으니, 세부가 낯설어져도 이 트랙에서 잡아둔 기준으로 다시 찾아 읽으면 됩니다.

이 트랙을 마친 지금, 제 작업 환경을 돌아보면 이렇습니다. 글 쓰는 프로젝트에서는 주제 발굴부터 초안 쓰기, 팩트체크, 썸네일까지 글 하나가 지나는 길의 대부분을 스킬이 맡습니다. 훅은 세션을 열 때 몇 가지를 점검하는 정도로 조용히 일하고, 서브에이전트는 필요할 때 그 자리에서 만들어 씁니다. 회사 업무 쪽 프로젝트는 조합이 다릅니다. 스킬보다 서브에이전트의 비중이 커지고, 판단이 필요한 일은 상위 모델에, 기계적인 검증은 가벼운 모델에 맡기는 식의 역할 배정이 붙습니다. 결과물이 나가기 전에 반박자 관점의 검증을 거치게 하는 관문도 있습니다. 같은 다섯 장치인데 일의 모양에 따라 비중이 완전히 달라지는 셈입니다. 그리고 어느 프로젝트에서든, 홈 폴더에는 스킬을 만드는 스킬, 훅을 만드는 스킬, 서브에이전트를 만드는 스킬이 들어 있습니다.

마지막 문장이 이 트랙의 도착점을 말해줍니다. 솔직히 저는 이제 다섯 장치를 명확히 구분하면서 쓰지 않습니다. 예전에는 이런 구조를 사람이 엄격하게 설계해야 했다면, 지금은 에이전트와 논의하며 만들어가는 환경이 됐기 때문입니다. "이 일이 반복되는데 자동으로 안 될까?"라고 대화를 시작하면, 맞는 장치를 고르는 것부터 만드는 것까지 에이전트가 함께합니다. 그렇다고 이 여섯 레슨이 헛수고라는 뜻은 아닙니다. 무엇을 시킬 수 있는지 알아야 시킬 수 있고, 에이전트가 만들어온 것을 점검하는 눈은 결국 여기서 배운 구분에서 나옵니다.