---
title: "클로드 코드를 진짜 업무 도구로 굴리는 법: 메모리, 스킬, 서브에이전트, MCP까지"
published: 2026-05-27T05:13:39.000Z
canonical: https://jeff.news/article/3468
---
# 클로드 코드를 진짜 업무 도구로 굴리는 법: 메모리, 스킬, 서브에이전트, MCP까지

이 글은 클로드 코드를 단순한 터미널 챗봇이 아니라 검증 루프를 가진 프로그래밍 가능한 개발 에이전트로 운영하는 방법을 정리한다. 핵심은 CLAUDE.md로 프로젝트 규칙을 축적하고, Skills와 Subagents로 반복 작업을 분리하며, Plugins와 MCP로 코드베이스 밖의 도구까지 연결하는 것이다. 특히 병렬 세션, 작업 트리, 리뷰 전용 에이전트, Playwright 검증 같은 패턴은 실제 개발 워크플로에 바로 적용할 만하다.

## 클로드 코드는 ‘프롬프트 잘 쓰는 도구’가 아니라 운영해야 하는 에이전트에 가까움

- 글쓴이가 말하는 핵심은 모델이 아니라 주변 운영 방식임
  - 같은 리팩터링을 사람이 40분 걸릴 때 클로드가 4분에 끝낼 수 있지만, 그 차이는 ‘좋은 모델’보다 검증 루프와 컨텍스트 설계에서 나온다고 봄
  - 그냥 프롬프트 넣고 첫 답변을 받는 사용자는 클로드를 고급 자동완성처럼 쓰는 셈이고, 글쓴이는 메모리, 커맨드, 병렬 세션, worktree까지 붙인 프로그래밍 가능한 에이전트처럼 굴림

- 가장 먼저 바꿔야 할 습관은 ‘탐색 → 계획 → 구현’ 순서임
  - 클로드 코드의 plan mode는 읽기 전용으로 파일을 읽고 흐름과 데이터 모델을 파악하게 하는 단계임
  - 작은 수정은 바로 해도 되지만, 변경이 여러 파일을 건드리면 먼저 계획을 만들게 하고 그 계획을 검토한 뒤 실행하는 게 낫다고 함
  - 보리스 체르니와 Anthropic 팀이 강조한 원칙은 단순함. 클로드가 자기 작업을 검증할 방법을 줘야 품질이 2~3배 오른다는 것

- 계획도 그냥 믿지 말고 다른 세션에 리뷰시키는 패턴을 추천함
  - 한 클로드 세션이 계획을 쓰고, 새 세션이 staff engineer 관점으로 계획을 비판하게 함
  - 구현이 틀어지면 다시 plan mode로 돌아가 검증 절차까지 포함해 재계획함
  - Ctrl+G로 클로드의 계획을 에디터에서 직접 수정할 수 있다는 팁도 나옴

- 컨텍스트는 설명보다 참조가 훨씬 강함
  - ‘auth 모듈 봐줘’보다 @src/auth/login.py처럼 정확한 파일을 찍는 게 낫다고 함
  - 에러도 복붙 설명보다 cat error.log | claude처럼 실제 로그를 파이프로 넣는 게 좋음
  - Cat Wu의 표현대로 클로드는 줄마다 지시하는 페어 프로그래머보다, 명확한 브리프를 받고 위임받는 엔지니어처럼 다룰 때 성능이 좋다는 주장임

> [!IMPORTANT]
> 이 글의 제일 큰 메시지는 ‘클로드에게 일을 시키려면 검증 가능한 종료 조건을 줘라’임. 테스트, 스크린샷, 실제 명령 출력 없이 성공했다고 말하게 두면 결과 품질이 바로 흔들림.

## .claude 디렉터리는 팀의 AI 작업 규칙을 담는 설정 레이어임

- .claude 디렉터리는 단순히 CLAUDE.md 하나만 두는 곳이 아님
  - 프로젝트 스코프는 레포 안의 .claude/에 있고 팀이 공유할 수 있음
  - 글로벌 스코프는 ~/.claude/에 있고 사용자의 모든 프로젝트에 적용됨
  - 정신 모델은 간단함. 프로젝트 파일은 프로젝트를 설명하고, 글로벌 파일은 사용자를 설명함

- 주요 파일 역할도 분리돼 있음
  - CLAUDE.md는 매 세션 로드되는 핵심 지시 파일이고, 프로젝트와 글로벌 양쪽에 둘 수 있음
  - CLAUDE.local.md는 프로젝트 안 개인 메모리로 쓰되 커밋하지 않고 gitignore에 넣는 파일임
  - settings.json은 권한, hooks, 환경 변수, 모델 기본값을 담고, .mcp.json은 팀 공유 MCP 서버 설정을 담음
  - skills, commands, agents, rules 폴더는 각각 재사용 작업, 단일 slash command, 서브에이전트, 경로별 규칙을 담당함

- CLAUDE.md는 길게 쓰는 문서가 아니라 짧은 가드레일이어야 함
  - 글쓴이가 인용한 보리스의 필터는 ‘이 줄을 지우면 클로드가 실수할까?’임
  - 답이 아니면 삭제하라는 식임. 꽤 빡세지만 맞는 말임
  - 표준 언어 컨벤션, 파일별 코드베이스 투어, 긴 튜토리얼, 자주 바뀌는 API 문서는 CLAUDE.md에 넣지 말라고 함

- 진짜 강력한 습관은 실수를 규칙으로 저장하는 것임
  - 클로드가 실수했을 때 프롬프트 끝에 ‘이걸 반복하지 않도록 CLAUDE.md를 업데이트해’라고 시킴
  - PR 리뷰에서 나온 실수도 규칙으로 남기면 다음 라운드에서 같은 코멘트가 줄어듦
  - 글쓴이는 이걸 compounding engineering이라고 부름. 한 번 발견한 실수가 팀의 지속 규칙으로 바뀌는 구조임

## Skills는 반복 프롬프트를 팀의 재사용 지식으로 바꾸는 단위임

- Skills는 클로드 코드가 ‘뭐든 할 수 있는 에이전트’에서 ‘우리 팀 방식으로 특정 일을 잘하는 에이전트’가 되게 만드는 장치임
  - ~/.claude/skills/<name>/SKILL.md 또는 .claude/skills/<name>/SKILL.md에 정의함
  - 폴더 이름이 slash command가 되고, SKILL.md 안에 frontmatter와 지시사항을 넣음
  - 템플릿, 참고 문서, scripts 폴더를 같이 둘 수 있어 단순 명령보다 확장성이 좋음

- Skills의 장점은 progressive disclosure임
  - 세션 시작 때는 skill 설명 정도만 읽고, 실제로 호출될 때 전체 SKILL.md와 보조 파일을 읽음
  - 덕분에 모든 규칙을 매번 컨텍스트에 올리지 않아도 됨
  - 반복 작업이 하루에 한 번 이상 나오면 skill로 만들라는 조언이 나옴

- commands보다 skills를 선호하라는 주장도 있음
  - .claude/commands/*.md도 slash command로 등록되지만, supporting files나 agent override가 필요해지면 skills가 더 적합함
  - 글쓴이도 예전에 repo automation을 commands로 만들었다가 나중에 supporting files가 필요해져 skills로 옮겼다고 함
  - 새 작업은 처음부터 skills로 만드는 게 낫다는 결론임

- 예시로 Go API conventions skill이 등장함
  - 새 HTTP 핸들러를 만들 때 팀의 라우팅, 에러 처리, 테스트, OpenAPI 갱신 규칙을 skill 안에 넣는 식임
  - 신규 개발자가 코드베이스를 다 뒤지지 않아도 첫날부터 팀 컨벤션에 맞는 endpoint를 만들 수 있다는 게 장점임
  - mattpocock/skills, Anthropic 공식 skills, 언어별 프로필 모음도 참고 대상으로 언급됨

## Subagents는 컨텍스트를 분리해서 리뷰와 디버깅을 맡기는 방식임

- 서브에이전트는 메인 세션의 컨텍스트를 오염시키지 않고 특정 작업을 처리하게 해줌
  - .claude/agents/ 또는 ~/.claude/agents/에 markdown 파일로 정의함
  - frontmatter에는 name, description, tools, model 같은 계약을 적음
  - 독립 컨텍스트, 제한된 도구 권한, 분리된 작업 반경이 핵심임

- 글쓴이가 든 PR 리뷰 에이전트 예시는 실용적임
  - 거의 놓칠 뻔한 null check 때문에 /pr-review agent를 만들었다고 함
  - 이 에이전트는 읽기 전용 도구만 갖게 해서 직접 수정하지 않고 문제만 찾게 함
  - model은 비용이 들더라도 보안 버그를 잘 잡기 위해 opus를 골랐다고 함

- 좋은 리뷰 에이전트는 ‘무엇을 지적하지 않을지’도 알아야 함
  - 변수명 취향 같은 잡음까지 다 잡으면 리뷰 결과가 못 쓰는 수준이 됨
  - 그래서 Do NOT flag 섹션으로 nitpick을 줄이는 게 중요하다고 함
  - security-reviewer, test-writer, debugger, performance-auditor, migration-writer, release-notes-writer 같은 역할도 대표 패턴으로 제시됨

- 에이전트를 체인으로 연결하는 방식도 추천됨
  - 세션 A가 구현하고, code-reviewer subagent가 신선한 컨텍스트로 검토함
  - 리뷰 결과를 다시 구현 세션에 넘겨 고치고, 반복해서 품질을 올림
  - migration처럼 큰 작업은 worktree isolation을 붙여 여러 에이전트가 병렬로 처리하게 할 수 있음

## Plugins와 MCP는 클로드 코드를 코드베이스 밖으로 확장함

- Plugins는 skills, hooks, subagents, MCP 서버를 하나의 설치 단위로 묶는 구조임
  - /plugin으로 marketplace browser를 열고 커뮤니티 marketplace도 추가할 수 있음
  - 글쓴이는 코드 리뷰, feature development, language server, security guidance 같은 플러그인을 초기 설치 후보로 봄
  - 2026년 중반 기준 75개 이상 marketplace와 1,000개 이상 plugins가 언급됨

- 특히 language server plugin은 높은 레버리지로 꼽힘
  - 심볼 수준 탐색과 on-edit diagnostics를 세션 안으로 가져오기 때문임
  - 타입 에러나 unused import 같은 문제를 수정 직후 잡을 수 있음
  - UI 작업에는 Playwright MCP를 붙여 실제 브라우저에서 클릭하고 확인하게 하는 패턴도 Anthropic 팀이 자주 쓴다고 함

- MCP(Model Context Protocol)는 외부 시스템을 클로드의 도구로 노출하는 표준 연결선임
  - MCP가 없으면 클로드는 파일을 읽고 명령을 실행하는 정도임
  - MCP가 있으면 Linear 티켓, Postgres 데이터베이스, Figma 컴포넌트, Sentry 스택트레이스, Obsidian vault까지 직접 읽고 다룰 수 있음
  - 대표 MCP로 GitHub, Context7, Sentry, Linear, Playwright, Figma, Postgres, Slack이 언급됨

- 다만 MCP를 무작정 많이 붙이는 건 경고함
  - 도구 목록이 커질수록 클로드가 어떤 도구를 써야 할지 판단하는 비용도 커짐
  - 스타터 세트로는 GitHub, Context7, 그리고 도메인 특화 MCP 한두 개 정도를 추천함
  - 연결 상태가 이상하면 /mcp로 활성 서버와 상태를 확인하라는 팁도 있음

```mermaid
sequenceDiagram
    participant 개발자
    participant 클로드코드
    participant 서브에이전트
    participant 외부도구
    participant 테스트
    개발자->>클로드코드: 기능 브리프와 검증 조건 전달
    클로드코드->>서브에이전트: 코드 흐름 조사와 계획 검토 위임
    서브에이전트-->>클로드코드: 위험 지점과 수정 계획 반환
    클로드코드->>외부도구: MCP로 티켓·오류·문서 조회
    클로드코드->>테스트: 구현 후 테스트와 검증 실행
    테스트-->>개발자: 성공 또는 실패 근거 반환
```

## 클로드 코드의 숨은 명령어들은 컨텍스트 관리가 핵심임

- 많은 사용자가 /clear, /compact, /init 정도만 알고 멈추지만 글쓴이는 나머지 명령어에서 생산성이 나온다고 봄
  - /insights는 사용 패턴을 분석하고, /context는 컨텍스트 사용량을 시각화함
  - /rewind는 세션 체크포인트로 돌아가고, /branch는 위험한 시도를 위해 세션을 분기함
  - /batch는 여러 worktree에 병렬 작업을 뿌리고, /loop와 /schedule은 반복 실행을 맡김

- /compact와 /clear를 구분하는 게 중요함
  - 완전히 새 작업이면 /clear 후 새 브리프를 직접 쓰는 편이 낫다고 함
  - 방금 작업한 맥락이 다음 작업에도 필요하면 /compact에 무엇을 보존할지 힌트를 넣는 식이 좋음
  - /compact는 손실이 있는 LLM 요약이고, /clear는 사람이 의도적으로 다시 쓴 출발점이라는 차이가 있음

- /rewind는 실패한 시도를 컨텍스트에 묻어두지 않기 위한 기능임
  - 클로드가 잘못된 길로 갔을 때 ‘그거 아니고 이렇게 해’라고 계속 말하면 실패한 시도도 대화 안에 남음
  - 그러면 모델이 나중에도 그 흔적에 끌릴 수 있음
  - 실패 전 체크포인트로 되돌리고, 실패에서 배운 내용을 반영해 다시 프롬프트를 주는 방식이 더 깨끗함

- /goal은 완료 조건을 걸어두고 클로드가 계속 시도하게 하는 루프임
  - 조건은 테스트 명령, CLI 종료 코드, grep 가능한 파일 상태처럼 검증 가능해야 함
  - ‘코드가 좋아질 때까지’ 같은 문장은 망한 조건이라고 봄
  - auto mode, /focus, Stop hook과 조합하면 장시간 작업을 덜 멈추게 할 수 있음

## 실제 업무 흐름은 병렬 세션과 검증 루프로 재편됨

- 글쓴이가 가장 크게 보는 생산성 전환은 병렬 세션임
  - 3~5개의 git worktree를 만들고 각각 다른 클로드 세션을 돌림
  - agent view로 여러 세션이 뭘 하는지 관리함
  - Anthropic 팀도 이 패턴을 강하게 추천한다고 함

- 새 기능 개발 흐름은 꽤 명확함
  - plan mode로 시작하고, Ctrl+G로 계획을 편집함
  - 구현 후에는 /pr-review subagent나 새 클로드 세션으로 신선한 리뷰를 받음
  - milestone마다 /compact로 결정사항, 변경 파일, 테스트 명령을 보존함

- 버그 수정은 재현부터 시작함
  - error.log를 파이프로 넣고 실패 테스트를 먼저 쓰게 함
  - 테스트가 빨간색이 된 뒤 수정하게 해야 추측성 수정이 줄어듦
  - 글쓴이는 ‘재현 없이 하는 수정은 양복 입은 추측’ 같은 뉘앙스로 강하게 비판함

- 대규모 마이그레이션은 /batch와 worktree 병렬화가 어울림
  - 먼저 작업 목록을 만들고, 3개 정도를 손으로 검증하며 프롬프트를 다듬음
  - 그다음 나머지를 병렬 에이전트에 뿌려 각자 테스트하고 PR을 만들게 함
  - 개발자는 타이핑하는 사람이 아니라 리뷰어에 가까워짐

> [!TIP]
> 팀에서 바로 적용하려면 CLAUDE.md부터 거창하게 쓰지 말고, 최근 PR에서 반복된 리뷰 코멘트 5개만 규칙으로 옮기는 게 현실적임. 그다음 테스트 명령과 단일 테스트 실행법을 추가하면 체감 효과가 빠르게 남.

## 결론은 ‘설정이 곧 실력’이라는 쪽에 가까움

- 글쓴이의 마지막 메시지는 꽤 단호함. 대부분은 프롬프트에서 멈추지만 진짜 가치는 그 너머에 있다는 것
  - CLAUDE.md는 실수를 쌓아 품질을 높이는 인프라임
  - CLAUDE.local.md는 개인 PR 피드백을 다음 작업에 반영하는 메모리임
  - Skills는 반복 전문성을 재사용 단위로 만들고, Subagents는 역할별 컨텍스트를 분리함
  - Plugins와 MCP는 개발 환경 전체를 클로드가 이해하고 조작할 수 있게 확장함

- 개발자의 역할도 살짝 바뀜
  - 직접 모든 코드를 쓰는 사람에서, AI가 잘 작성하도록 환경과 검증 루프를 설계하는 사람에 가까워짐
  - 글쓴이는 ‘설정이 작업이고, 실행은 검증’이라는 식으로 정리함
  - 좀 과격하게 들릴 수 있지만, AI 코딩 도구를 팀 단위로 쓰려면 이 관점이 꽤 현실적임

---

## 기술 맥락

- 이 글에서 가장 중요한 선택은 클로드 코드를 단일 챗봇이 아니라 여러 설정 파일과 에이전트로 운영하는 구조예요. 왜냐하면 코딩 에이전트의 실패는 대개 모델이 몰라서가 아니라, 테스트 방법·프로젝트 규칙·금지된 패턴 같은 작업 조건을 못 받아서 생기거든요.

- CLAUDE.md를 짧게 유지하라는 조언도 같은 맥락이에요. 모든 문서를 밀어 넣으면 컨텍스트는 커지지만 정작 중요한 규칙은 묻혀요. 그래서 빌드 명령, 단일 테스트 실행법, 실제로 반복된 실수처럼 지우면 바로 사고 나는 정보만 남기자는 쪽이에요.

- Skills와 Subagents를 나누는 이유는 반복성과 격리 때문이에요. Skills는 ‘우리 팀은 API 핸들러를 이렇게 만든다’처럼 재사용할 절차를 담고, Subagents는 리뷰나 디버깅처럼 별도 판단이 필요한 일을 독립 컨텍스트에서 처리해요. 이렇게 해야 메인 세션이 장황한 조사 로그로 흐려지지 않아요.

- MCP가 중요한 건 클로드 코드의 시야를 레포 밖으로 넓히기 때문이에요. 실제 개발 판단은 코드만 보고 끝나지 않고, 티켓, 장애 로그, 디자인, 데이터베이스 상태를 같이 봐야 하거든요. MCP는 그 외부 시스템을 표준 도구처럼 호출하게 만들어서 에이전트가 더 현실적인 결정을 하게 해요.

- 병렬 worktree 전략은 규모가 커질 때 특히 의미가 있어요. 하나의 거대한 세션에 모든 변경을 몰아넣으면 컨텍스트도 복잡해지고 실패 복구도 어려워요. 여러 worktree에서 구현, 리뷰, 마이그레이션을 나눠 돌리면 각 세션의 책임이 작아지고, 개발자는 최종 결과를 검증하는 쪽에 집중할 수 있어요.

## 핵심 포인트

- 클로드 코드 품질을 올리는 핵심은 모델 자체보다 검증 루프, 짧은 프로젝트 규칙, 정확한 컨텍스트 제공에 있다.
- CLAUDE.md는 지식 창고가 아니라 반복 실수를 막는 가드레일이어야 하며, 실제 실패를 규칙으로 축적할 때 효과가 커진다.
- Skills는 반복 프롬프트를 재사용 가능한 전문 작업 단위로 만들고, Subagents는 독립 컨텍스트에서 리뷰·디버깅·마이그레이션을 맡긴다.
- Plugins와 MCP는 코드 리뷰, 브라우저 테스트, Sentry, Linear, Figma, Postgres 같은 외부 시스템을 클로드 코드 작업 흐름 안으로 가져온다.
- 저자는 3~5개 병렬 세션과 git worktree를 함께 쓰는 방식을 가장 큰 생산성 전환점으로 꼽는다.

## 인사이트

이 글의 포인트는 ‘프롬프트를 잘 쓰자’가 아니라 AI 코딩 도구를 운영체계처럼 설계하자는 데 있다. 한국 개발팀도 온보딩, 코드리뷰, 테스트 검증, 장애 분석 같은 반복 업무를 에이전트 단위로 쪼개면 개인 생산성보다 팀 지식 축적 효과가 더 크게 날 수 있다.