저만의 클로드 사용법

많은 개발자분들이, 개발자의 역량이 AI를 잘 사용하는 것으로 변경되었다고 말합니다.

그래서 많은 주변 동료들이 AI를 사용하는 다양한 기법들인 스킬, 슬래시 커맨드, 서브에이전트, MCP, 훅스.... 등 많은 기술을 익히려고 하는 것 같습니다.

다만 이 다양한 기능들이 나오게 된 이유와, 사용하는 이유를 모르고 사용하는 사람들이 많다고 생각합니다.

제 의견이 모두 맞는 것은 아니지만,

개인적으로 생각하기에 모든 기능들은 하나의 가장 큰 목표를 가지고 있다는 점에서 모두 같다고 생각합니다. 클로드 처음이면 꼭 한번만 읽어주세용

컨텍스트를 덜 차게, 질 좋은 컨텍스트만, 동일한 인풋으로.

1. AI는 기억하지 않음

LLM이 뭘까요.

클로드 같은 파운데이션 모델은 텍스트로 학습한 뒤 가장 그럴듯한(확률 높은) 다음 텍스트를 내주는 모델입니다.

단순히 말하면 그냥 언어예측모델입니다.

계산 능력이 없어서 "1+1"처럼 학습된 건 답해도 아주 큰 숫자 연산은 못 할 수 있습니다.

그래서 못 하는 일은 도구(Tools)를 쥐어주고, AI가 도구를 실행해 결과값을 받아 응답하게 합니다.

계산이 필요하면 계산기를 실행하는 식입니다.

PDF나 이미지를 읽는 멀티모달도 원리는 같습니다. 파일을 읽는 도구를 주고 결과를 텍스트로 변환해 처리하는 겁니다.

그리고 , AI는 대화를 "기억"하는 게 아닙니다. 무상태성.

질문할 때마다 이전 대화 전체가 프롬프트에 쌓여서 매번 다시 전송됩니다. 대화가 길어질수록 모델이 한 번에 이해할 수 있는 컨텍스트 윈도우 (보통 20만 토큰, 큰 모델은 100만 토큰)가 점점 차오릅니다.

여기서 문제가 두 개 생깁니다.

첫째, 공간이 유한합니다. 쓸데없는 내용이 차지한 만큼 정작 필요한 내용이 들어갈 자리가 줄어듭니다.

둘째, lost in the middle.<-이게 젤 중요함

긴 컨텍스트의 중간 내용을 모델이 잃어버리는 현상이 있습니다.

왜 그런지는 만든 사람도 모르지 않을까요.

확실한 건 시작과 끝은 잘 활용되고 중간은 흐려진다는 것,

그리고 컨텍스트 자체를 줄이면 잃는 부분도 줄어든다는 것입니다.

그래서 컨텍스트 축소는 비용 절감 이야기가 주가 된다기 보다는, 답변 품질 이야기가 주 입니다.

이 두 가지를 알고 나면 스킬이니 서브에이전트니 하는 개념들이 쉽게 느껴집니다.

기능이 아니라 컨텍스트 관리 전략의 시점으로.

2. 실제 겪은 문제: 검증 스무 번이 컨텍스트에 포함됨

상황을 말씀드리면, PLick은 프리미어리그 이적 루머를 릴스처럼 넘겨보는 앱이고, 저는 프론트엔드에서 목데이터로 퍼블리싱한 화면에 로컬 백엔드 API를 하나씩 붙이는 작업을 반복하고 있었습니다.

엔드포인트 하나를 붙일 때마다 클로드와 함께 밟는 절차가 있었습니다.

스웨거 JSON을 받아 해당 경로만 jq로 파내고, BE 저장소의 시크릿으로 JWT를 직접 민팅하고, 공유 DB에 psql로 붙어 일회용 테스트 유저를 만들고, curl로 성공/401/409 시나리오를 밟고, DB를 다시 조회해 진짜 반영됐는지 보고, 테스트 유저를 지웁니다.

스웨거 문서를 안 믿고 실제로 때려보는 이유는 문서가 실제 동작과 달랐던 전례가 있어서입니다. 팀원을 안믿는다기 보다는, 확실한 방법을 택했습니다.

이 검증에 툴 호출이 한 번에 스무 번, 서른 번씩 나왔습니다.

문제는 그 출력이 전부 메인 대화에 쌓인다는 것입니다.

정작 화면 코드를 짜야 할 시점에는 컨텍스트가 curl 출력과 psql 결과로 가득 차 있습니다.

위에서 말한 두 문제가 실제로 나옵니다. 공간은 낭비되고, 정작 중요한 화면 요구사항은 대화 중간 어딘가에 묻혀 흐려집니다.

게다가 JWT 민팅 코드와 psql 접속 명령을 세션마다 새로 짰습니다. AI는 세션이 바뀌면 기억을 잃으니까, 같은 일을 매번 처음부터 반복한 것입니다.

3. 정적 컨텍스트: CLAUDE.md는 컴팩트하게

CLAUDE.md는 세션이 열리면 반드시 맨 앞에 들어가는 정적 컨텍스트입니다.

맨 앞이라는 위치는 lost in the middle 관점에서 가장 좋은 자리입니다.

그래서 여기에 뭘 넣을지가 중요한데, 원칙은 반대로 다이어트입니다.

어떤 작업을 하든 반드시 알아야 하는 최소한만 넣는게 좋습니다.

제 CLAUDE.md 첫 줄이 이렇습니다.

어떤 작업이든 반드시 알아야 할 최소한만 여기 둔다. 제품과 기술 세부는 필요할 때 아래 "더 읽을 것"에서 골라 읽는다.

폴더 구조, 실행 명령어, 절대 어기면 안 되는 컨벤션(디자인 토큰 강제, 브랜치 규칙)까지만 있고,

API 연결 규칙이나 화면 퍼블리싱 세부는 없습니다.

대신 "BE API 연결은 api-integration 스킬을 봐라" 같은 포인터만 있습니다.

모든 걸 CLAUDE.md에 넣으면 세션마다 그 전부가 컨텍스트를 선점하고, API 작업을 하는 세션에서 퍼블리싱 규칙은 필요도 없는데 컨텍스트만 차지합니다.

4. 스킬: 필요할 때만 로드되는 동적 컨텍스트

스킬은 .claude/skills 폴더에 SKILL.md로 두는 동적 컨텍스트입니다.

핵심은 YAML 프론트매터의 description입니다.

AI는 세션 시작 때 스킬 본문이 아니라 description 목록만 봅니다.

그리고 지금 하는 작업이 어떤 스킬의 description과 맞아떨어진다고 판단하면 그때 본문을 읽어 컨텍스트에 넣습니다.

제 api-integration 스킬의 description은 이렇게 생겼습니다.

description: >-
  PLick에서 퍼블리싱 끝난 화면에 로컬 백엔드(스웨거) API를 하나씩 붙일 때(mock→fetch 교체)
  따르는 규칙. … Use when connecting backend APIs, replacing mock data with fetch,
  reading a Swagger/OpenAPI spec, wiring endpoints into apps/web or apps/mobile, …

"언제 이걸 읽어야 하는지"를 한국어와 영어로 다 적었두었습니다.(물론 둘다 적는것도 당연히 컨텍스트 낭비가 될 수 있긴 합니다. 감안하고 진행)

스킬이 안 읽히면 본문이 아니라 description이 잘못된 거라서, 히트가 안 되면 description을 디버깅해야합니다.

실제로 스킬을 만들고 나서 의도한 상황에 로드가 되는지 몇 번 돌려보며 문구를 고쳤습니다.

본문도 한 덩어리로 만들지 않았습니다.

SKILL.md에는 아키텍처 결정과 판단 기준만 두고, 세부 코드 패턴은 data-layer.md, tanstack-query.md 같은 참조 파일로 쪼갰습니다.

AI가 필요한 파일만 골라 읽게 하기 위해서입니다. 스킬 안에서도 동적 로딩을 한 번 더 하는 느낌.

이때, 스킬은 슬래시 명령어로 직접 호출하는 게 아닙니다.

제가 "API 붙여줘"라고 하면 AI가 알아서 골라 읽는 역할입니다. 직접 호출하는 건 다음에 나오는 커맨드입니다. 안헷갈리게 주의.(사실 / 로 호출은 가능하긴 한데, 스킬의 기본 역할 자체는 그런게 아닙니다)

5. 커맨드: 잘 만든 프롬프트의 추상화

같은 작업을 시켜도 프롬프트를 어떻게 쓰느냐에 따라 결과물 품질이 달라집니다.

팀이라면 팀원마다 프롬프트 실력이 다르다는 게 그대로 결과물 편차가 될수도 있습니다.

슬래시 커맨드는 이 문제를 해결합니다.

잘 만든 프롬프트를 .claude/commands에 MD 파일로 굳혀서 /명령어로 공유하는 것입니다.

함수로 치면 검증된 로직의 추상화고, 호출하는 사람은 인자만 넘기면 됩니다.

제 /wire-api 커맨드 입니다.

description: 로컬 BE(스웨거) API 하나를 화면에 연결(mock→fetch)하고, 공용화 여부를 판단해 PR까지 올린다
argument-hint: <KAN-티켓번호> [엔드포인트/스코프]

/wire-api KAN-264 엔드포인트라고 치면 지라 티켓 번호가 인자로 들어가고, 본문에 적어둔 8단계 절차가 프롬프트로 실행됩니다.

계약 검증을 위임하고, 타입을 대조하고, 브랜치를 따고, 데이터 레이어를 쓰고, 페칭 도구를 고르고, 공용화를 판단하고, 검증하고, PR까지 올립니다.

티켓에 내용을 충실히 채우는 것 자체가 AI에게 줄 컨텍스트를 만드는 일이라, 지라를 잘 쓰는 것과 커맨드가 한 파이프라인으로 이어집니다.

여기서 커맨드와 스킬의 역할 차이가 갈립니다.

커맨드는 절차(무엇을 어떤 순서로)를,

스킬은 규칙(각 단계를 어떻게)을.

/wire-api 커맨드 본문은 "시작 전에 api-integration 스킬을 읽어라"로 시작합니다.

절차는 워크플로마다 다르지만 규칙은 여러 워크플로가 공유하기 때문에 이렇게 나눴습니다.

실제로 web 이식용 /web-wire-api 커맨드는 절차가 다르지만 같은 스킬을 읽습니다.

6. 서브에이전트: 일을 잘하게 하는 도구 X. 컨텍스트를 아끼는 도구 O

아까 2번의 문제, 검증 스무 번이 대화를 잡아먹는 문제를 서브에이전트로 풉니다.

서브에이전트는 메인 대화와 별개의 컨텍스트에서 도는 또 하나의 클로드입니다.

프로세스와 스레드 라 생각하면 편합니다.

메인이 "이 일 해줘"라고 넘기면, 서브에이전트가 자기 컨텍스트에서 툴을 몇십 번 두들기고, 끝나면 최종 텍스트 하나만 메인에게 돌려줍니다.

중간 과정은 메인 컨텍스트에 한 글자도 안 들어옵니다.

이게 핵심입니다. 서브에이전트는 일을 더 잘하게 만드는 도구가 아니라 메인 컨텍스트를 오염시키지 않는 도구입니다.

그래서 넘길 일을 고르는 기준도 성능이 아니라 컨텍스트입니다.

• 넘기기 좋은 일: 툴 호출은 많은데 결론은 한 문단인 일. 검증같은 일.
• 넘기면 안 되는 일: 결론이 아니라 과정을 봐야 하는 일. 화면을 눈으로 보며 고치는 퍼블리싱은 넘기는 순간 내가 못봐서 알맞지 않음.

이 기준으로 /wire-api의 검증 단계를 둘로 쪼갰습니다.

계약과 DB 검증은 be-verify 서브에이전트,

화면 확인은 메인(=나).

계약 검증은 "응답이 이 모양이다, 이 에러 코드가 온다"라는 결론만 있으면 되니 위임하고, 퍼블리싱 디테일은 제가 봐야 아니 분리하지 않습니다.

be-verify는 .claude/agents/be-verify.md에 정의했습니다.

도구를 안 주는 것도 설계

tools: Bash, Read, Grep, Glob

일부러 Write와 Edit이 주지 않습니다.

이 에이전트가 프론트 코드를 고칠 수 있으면, 검증하다가 "아 이거 타입이 틀렸네" 하고 고쳐버릴 수 있습니다.

그 변경은 메인 컨텍스트에 안 들어오니 나중에 diff를 보고 어디서 바뀐건지 헷갈릴 수 있습니다.

권한을 안 주면 고치는게 불가능합니다.

코드 변경이 필요하면 리포트에 문장으로 적어 올리고, 고치는 건 메인이 하게 했습니다.

프롬프트로 "고치지 마세요"라고 부탁하는 것보다 확실합니다.

지시는 확률적으로 어길 수 있지만 없는 도구는 못 쓰니까요.

LLM이 확률 모델이라는 본질을 기억하면, 지켜야 하는 제약은 프롬프트가 아니라 구조로 걸여야 하는 걸 알 수 있습니다.

리포트 형식을 고정해야 격리가 완성됨

처음엔 리포트 형식을 안 정했습니다.

그러면 서브에이전트가 자기가 밟은 과정을 다 적어 올릴 수 있습니다.

너무 많은 툴 호출 로그가 요약이라는 이름으로 메인에 그대로 들어오면, 컨텍스트를 아끼려고 뗀 의미가 없습니다.

그래서 템플릿을 작성했습니다.

인증 필요 여부, 요청 형태, 응답 200의 shape, 에러 code 문자열, 스웨거와 다른 점, 밟은 시나리오, FE에 반영할 것, 테스트 데이터 정리 결과

그리고 명령어 로그는 붙이지 말라고 명시했습니다.

메인이 코드를 짜는 데 필요한 사실만 넘어옵니다.

그리고 BE가 안 떠 있거나 스크립트가 실패하면 추측으로 채우지 말고 막혔다고 그대로 보고하라고 적었습니다.

LLM은 그럴듯한 답을 내는 모델이라서, 검증에 실패하면 그럴듯한 거짓 계약을 지어낼 수 있습니다.

반복 코드는 스크립트로 굳히기

세션마다 새로 짜던 JWT 민팅과 psql 접속은 저장소 스크립트(scripts/be-verify/)로 고정했습니다.

사람이 기억 못 하면 메모하듯, AI가 세션마다 잃는 지식은 파일로 저장해야함을 이제 감이 오실 겁니다.

에이전트 지침에는 "node crypto나 psql 명령을 새로 짜지 않는다. 이 스크립트를 실행한다"라고만 적었습니다.

매번 코드를 생성하는 것보다 토큰도 아끼고, 결과의 편차도 적어집니다.

7. 결과물

그래서 /wire-api 커맨드의 전체 흐름은 이렇게 됩니다

나:      /wire-api KAN-264 엔드포인트   ← 커맨드: 검증된 절차의 진입점
메인:    api-integration 스킬 로드      ← 스킬: 필요할 때만 들어오는 규칙
메인:    be-verify에 계약 검증 위임      ← 서브에이전트: 지저분한 과정의 격리
서브:    (자기 컨텍스트에서 스웨거·JWT·curl·DB 30여 회) → 리포트 한 장 반환
메인:    리포트 기반으로 타입·데이터 레이어·화면 작성, PR까지
나:      화면을 브라우저로 직접 확인      ← 과정을 봐야 하는 일은 위임하지 않는다

커맨드는 무엇을 어떤 순서로(절차), 스킬은 각 단계를 어떻게(규칙), 서브에이전트는 지저분한 과정을 어디서(격리) 를 담당하는것을 이제는 이해할 수 있습니다.

그리고 셋 다 결국 하나를 위해 있는걸 알수 있습니다.

컨텍스트를 덜 차게, 질 좋은 컨텍스트만, 동일한 인풋으로.

8. 지침 문서는 코드가 아니라서 아무도 안 고쳐준다

다만 이런 상황이 발생할 수 있습니다

작업 중에 api-integration 스킬에 "인증: 아직 없음" 이라고 적혀 있는 걸 발견했는데, 실제로는 그 사이 로그인, 토큰 refresh, 온보딩까지 인증이 전부 붙은 상태였습니다.

스킬만 첫 API 연결 시점에 멈춰 있을 수 있습니다.

새로 만든 be-verify가 이 스킬을 읽고 "공개 API구나" 하고 토큰 없이 검증할 수 있습니다.

지침 문서가 틀리면 그걸 읽는 에이전트가 전부 틀립니다. 스킬은 코드가 아니라서 컴파일 에러도 안 나고 테스트도 안 깨집니다.

그래서 규칙을 하나 세웠습니다.

작업하다 지침이 틀린 걸 발견하면 그 자리에서 고치고 커밋에 포함합니다.

컨텍스트 자산도 코드처럼 유지보수 대상임을 잊지 말아야 합니다.

9. 원리를 파악하기

제말이 다 정답인것은 아닙니다.

모델마다 성격이 달라서 어떤 모델에선 잘 되고 어떤 모델에선 이상하게 될 수도 있습니다.

description 문구 하나로 스킬 히트율이 달라지고, 그건 돌려보기 전엔 모릅니다.

다만 원리를 알고 나니 시야가 넓어졌습니다.

새 기능이 나와도 "이건 컨텍스트를 어떻게 다루는 도구인가"라는 질문으로 접근할 수 있습니다.

스킬은 동적 로딩이고, 커맨드는 프롬프트 추상화고, 서브에이전트는 격리다. MCP는 외부 도구 통신 규약이고, 훅스는 특정 시점에 프로그램을 거는 겁니다.

어쨌든 전부 컨텍스트를 덜 차게, 더 질 좋게, 동일하게 넣으려는 시도라고 생각합니다.

사실상 사람이랑 동일하게 생각하면 될 것 같습니다.

기억 못 하면 메모하고(스크립트, CLAUDE.md), 필요할 때만 매뉴얼을 펴고(스킬), 검증된 업무 절차를 문서로 공유하고(커맨드), 반복 업무는 담당자에게 위임하되 보고서 양식을 정해주고 권한은 필요한 만큼만 준다(서브에이전트).

결국 AI에게 일을 잘 시키는 문제는 신입에게 일을 잘 나눠주는 문제와 같은 모양인 것 같습니다.

물론 저는 신입개발자이지만, 이제는 모든 신입개발자도 상황을 파악하고 리더의 역할을 할 수 있어야한다는게, 클로드를 잘 사용하는 역량으로 나타나기 때문이라고도 볼 수 있을 것 같습니다.