Claude Code 사용법 7단계: 프롬프트부터 Agent Teams까지

Claude Code를 잘 쓰는 사람과 그렇지 않은 사람의 차이는 프롬프트 길이가 아닙니다.

처음에는 질문만 하다가 프로젝트 맥락을 알려주고, 실제 파일 작업을 맡기고, 반복 업무를 Skill로 저장하게 됩니다. 더 나아가면 역할별 에이전트가 결과를 주고받는 구조까지 만들 수 있습니다.

이 글에서는 Claude Code 활용 수준을 7단계로 나눕니다. 설명만 읽고 끝나지 않도록 단계마다 바로 따라 할 수 있는 예시와 실습도 함께 준비했습니다.

Claude Code 활용 7단계는 Prompt, Context, Tools, MCP, Skills, Subagents, Agent Teams입니다. 질문만 하는 단계에서 시작해 프로젝트 맥락을 제공하고, 파일 작업과 외부 도구 연결을 거쳐, 반복 절차와 역할별 에이전트를 운영하는 단계로 발전합니다.

Claude Code 7단계 한눈에 보기

지금까지 직접 해본 단계에 표시해보세요. 가장 마지막으로 해본 단계가 현재 레벨에 가깝습니다.

Lv.1 Prompt: 일단 질문하는 단계

Claude Code를 처음 사용할 때는 일반 챗봇처럼 원하는 것을 바로 질문합니다. 간단한 문제는 해결할 수 있지만, Claude가 프로젝트의 배경과 완료 기준까지 아는 것은 아닙니다.

이렇게만 요청하고 있나요?

이 코드 고쳐줘.

이 요청에는 어떤 파일을 봐야 하는지, 무엇이 문제인지, 어디까지 확인해야 끝난 것인지가 없습니다. Claude가 빈칸을 추측해야 하므로 결과도 들쭉날쭉해집니다.

네 칸만 추가해보기

작업 대상: 회원가입 폼
현재 문제: 잘못된 이메일도 제출됨
원하는 결과: 이메일 형식을 검사하고 오류 문구 표시
완료 기준: 기존 테스트와 새 검증 테스트 통과

길게 쓰는 것이 목표는 아닙니다. 작업 대상과 현재 문제, 원하는 결과와 완료 기준을 분명하게 만드는 것이 핵심입니다.

다음 레벨로 넘어갈 신호

새 대화를 열 때마다 프로젝트 구조와 작업 기준을 처음부터 설명하고 있다면 Context 단계로 넘어갈 차례입니다.

Lv.2 Context: 내 프로젝트를 이해시키는 단계

매번 유지되는 정보를 대화에 반복해서 붙여 넣을 필요는 없습니다. 프로젝트 목적과 기술, 작업 규칙처럼 Claude가 항상 알아야 하는 내용은 CLAUDE.md에 기록할 수 있습니다.

프로젝트 루트의 CLAUDE.md 또는 .claude/CLAUDE.md는 팀과 공유할 프로젝트 지침에 적합합니다.

실습: CLAUDE.md 만들기

# 프로젝트 소개

온라인 강의 소개 페이지입니다.

## 사용 기술

- Next.js
- TypeScript
- Tailwind CSS

## 작업 규칙

- 기존 컴포넌트 구조를 유지합니다.
- 새 라이브러리를 추가하기 전에 먼저 확인합니다.
- 모바일 화면을 함께 확인합니다.
- 작업 후 테스트를 실행합니다.

## 하지 말아야 할 것

- 기존 API 응답 형식을 변경하지 않습니다.
- 요청하지 않은 파일은 수정하지 않습니다.

프로젝트의 모든 정보를 넣으려고 하지 마세요. 새 팀원에게 업무를 맡길 때 꼭 알려줄 판단 기준만 남기면 됩니다.

제대로 불러왔는지 확인하기

Claude Code에서 다음 명령을 실행합니다.

/memory

현재 세션이 읽은 CLAUDE.md와 규칙 파일을 확인할 수 있습니다. 파일을 만들었는데도 규칙이 적용되지 않는다면 먼저 이 화면에서 로드 여부를 확인하세요.

비교 실습

아래 요청을 CLAUDE.md를 만들기 전과 후에 각각 실행해보세요.

이 프로젝트에 이메일 구독 폼을 추가해줘.

기존 컴포넌트 구조와 기술, 모바일 확인 규칙을 얼마나 잘 반영하는지 비교합니다.

다음 레벨로 넘어갈 신호

Claude가 내 상황을 이해하는 것에서 끝나지 않고 실제 파일을 수정하고 실행 결과까지 확인한다면 Tools 단계입니다.

Lv.3 Tools: 답변이 아니라 결과물을 만드는 단계

Claude Code에는 파일 읽기와 편집, 검색, 명령 실행 같은 도구가 기본으로 들어 있습니다. “실패한 테스트를 고쳐줘”라고 요청하면 테스트 실행, 오류 확인, 관련 파일 탐색, 코드 수정, 재실행을 이어서 처리할 수 있습니다.

실습: 작업 흐름 전체 맡기기

회원가입 폼의 이메일 검증 오류를 해결해줘.

1. 관련 파일과 테스트를 먼저 찾아줘.
2. 오류 원인을 설명해줘.
3. 필요한 파일만 수정해줘.
4. 테스트를 실행해줘.
5. 변경 내용과 테스트 결과를 정리해줘.

이 요청의 핵심은 바로 코드부터 수정시키지 않는 것입니다. 탐색, 원인 확인, 수정, 실행, 결과 보고가 하나의 작업 흐름으로 이어지게 합니다.

결과 보고에서 확인할 것

• 어떤 파일을 확인했는가
• 무엇이 원인이었는가
• 어떤 파일이 변경됐는가
• 테스트를 실제로 실행했는가
• 실패하거나 확인하지 못한 항목이 남아 있는가

“수정했습니다”라는 답변만 보고 끝내지 마세요. 실행 결과가 있는지 확인해야 실제 작업이 끝난 것입니다.

비개발 작업도 가능합니다

content 폴더의 기존 글 3개를 읽고 문체를 분석해줘.
그 문체를 참고해서 새 글의 목차를 작성하고,
content/claude-code-guide.md 파일로 저장해줘.
저장한 뒤 제목 구조와 링크 오류도 확인해줘.

Tools는 개발자만을 위한 단계가 아닙니다. 문서, HTML, 이미지용 소스, 강의 자료처럼 파일로 만드는 작업에도 같은 흐름을 사용할 수 있습니다.

다음 레벨로 넘어갈 신호

로컬 파일뿐 아니라 Notion, Gmail, Calendar, Slack 같은 외부 서비스의 정보가 필요하다면 MCP 단계로 넘어갑니다.

Lv.4 MCP: 채팅창 밖의 업무를 연결하는 단계

MCP는 Claude Code가 외부 서비스나 사내 도구를 정해진 방식으로 사용할 수 있게 연결합니다. 연결이 끝나면 외부 정보를 읽고 현재 파일 작업에 활용하는 흐름을 만들 수 있습니다.

연결 상태 확인하기

Claude Code 안에서 다음 명령을 실행합니다.

/mcp

연결된 서버와 인증 상태를 확인할 수 있습니다. 터미널에서는 다음 명령으로 등록된 서버 목록을 볼 수 있습니다.

claude mcp list

HTTP MCP 서버 연결 예시

claude mcp add --transport http sentry https://mcp.sentry.dev/mcp

연결 후 /mcp를 열어 필요한 인증을 진행합니다. 실제 서비스의 주소와 인증 방식은 해당 서비스의 공식 안내를 확인해야 합니다.

읽기 작업부터 시작하기

연결된 서비스에서 지난 24시간 동안 가장 많이 발생한 오류를 찾아줘.
아직 수정하지 말고 오류별 발생 횟수와 영향을 받는 기능만 정리해줘.

처음부터 외부 데이터를 수정하거나 메시지를 보내게 하지 마세요. 조회와 요약처럼 되돌리기 쉬운 작업으로 연결 상태와 결과를 먼저 확인하는 편이 좋습니다.

외부 정보와 로컬 작업 연결하기

연결된 문서 서비스에서 이번 주 콘텐츠 기획안을 찾아줘.
Claude Code와 관련된 주제만 정리한 뒤,
현재 프로젝트의 content 폴더에 초안 파일을 만들어줘.

MCP의 장점은 외부 앱을 사용할 수 있다는 사실 자체가 아닙니다. 외부에서 찾은 정보를 현재 프로젝트의 파일 작업과 연결할 때 실제 업무 흐름이 만들어집니다.

다음 레벨로 넘어갈 신호

비슷한 조회 방식과 작성 규칙을 매번 다시 설명하고 있다면 그 절차를 Skill로 저장할 차례입니다.

Lv.5 Skills: 반복 업무를 매뉴얼로 저장하는 단계

Skill은 Claude가 필요할 때 불러와 사용하는 지식과 작업 절차입니다. 블로그 초안, 코드 리뷰, 배포 점검처럼 반복되는 업무 방식을 저장하기 좋습니다.

프로젝트에서 함께 사용할 Skill은 .claude/skills/<skill-name>/SKILL.md에 만들 수 있습니다.

실습: 블로그 초안 Skill 만들기

---
name: blog-draft
description: 실습과 예제가 포함된 블로그 초안을 작성할 때 사용합니다.
---

# 블로그 초안 작성

1. 예상 독자와 검색 의도를 먼저 확인합니다.
2. 개념 설명보다 실제 예시를 우선합니다.
3. 각 주요 절마다 따라 할 수 있는 실습을 넣습니다.
4. 어려운 용어는 처음 등장할 때 풀어서 설명합니다.
5. 초안 작성 후 중복 표현과 긴 문장을 줄입니다.

description은 Claude가 언제 이 Skill을 불러올지 판단하는 데 사용됩니다. “좋은 글을 쓴다”처럼 모호하게 적기보다 사용 상황을 구체적으로 적는 편이 좋습니다.

Skill 확인하고 사용하기

/skills

사용 가능한 Skill 목록에서 blog-draft가 보이는지 확인합니다. 그다음 아래처럼 요청해보세요.

blog-draft Skill을 사용해서
Claude Code MCP 입문 글의 구성안을 작성해줘.

좋은 Skill은 완성된 결과의 모양만 정의하지 않습니다. 어떤 순서로 판단하고 작업해야 하는지도 함께 알려줍니다.

CLAUDE.md와 Skill 구분하기

항상 지켜야 할 코딩 규칙은 CLAUDE.md에 둡니다. 가끔 실행하는 배포 점검이나 콘텐츠 작성 절차는 Skill로 분리하면 기본 대화의 맥락을 덜 차지합니다.

다음 레벨로 넘어갈 신호

자료 조사와 작성, 검수처럼 서로 다른 일을 하나의 Skill과 세션에 모두 넣고 있다면 Subagents로 역할을 나눌 차례입니다.

Lv.6 Subagents: 역할별 작업자를 분리하는 단계

Subagent는 별도의 맥락에서 특정 작업을 처리하고 결과 요약을 메인 세션으로 돌려줍니다. 조사 과정의 긴 문서와 로그가 메인 대화를 가득 채우지 않게 하거나, 여러 독립 작업을 나눌 때 유용합니다.

프로젝트 전용 Subagent는 .claude/agents/ 폴더에 Markdown 파일로 정의할 수 있습니다.

실습: 리서처 만들기

---
name: researcher
description: 공식 문서를 조사하고 근거와 함께 요약합니다.
tools: Read, Grep, Glob, WebSearch, WebFetch
model: sonnet
---

당신은 기술 자료를 조사하는 리서처입니다.

- 공식 문서를 가장 먼저 확인합니다.
- 확인하지 못한 내용은 추측하지 않습니다.
- 핵심 주장마다 출처 URL을 기록합니다.
- 마지막에는 확인된 사실과 추가 확인이 필요한 내용을 나눠 보고합니다.

Claude Code에서 /agents를 열면 등록된 Subagent와 현재 실행 중인 Subagent를 확인할 수 있습니다.

실제 요청 예시

researcher Subagent에게 Claude Code MCP의 최신 연결 방법을 조사하게 해줘.
공식 문서를 우선하고, 글에 바로 반영할 수 있도록 명령 예제와 주의점을 정리해줘.

여러 역할이 필요하다면 에디터도 별도로 만들 수 있습니다.

---
name: editor
description: 기술 글을 입문자 관점에서 검수합니다.
tools: Read, Grep, Glob
model: sonnet
---

초안을 입문자 관점에서 검토합니다.

- 설명만 있고 예시가 없는 부분을 찾습니다.
- 처음 등장한 용어에 설명이 있는지 확인합니다.
- 길거나 반복되는 문장을 표시합니다.
- 사실을 직접 바꾸지 말고 수정 제안으로 보고합니다.

핵심은 ‘리서처’나 ‘에디터’라는 이름이 아닙니다. 무엇을 확인하고 어떤 형식으로 보고할지 명확히 정해야 역할 분리의 효과가 생깁니다.

Subagent와 Skill은 무엇이 다를까?

다음 레벨로 넘어갈 신호

여러 작업자가 서로의 결과를 공유하고 직접 조율해야 한다면 Agent Teams를 고려할 수 있습니다.

Lv.7 Agent Teams: 여러 Claude가 팀처럼 협업하는 단계

Agent Teams에서는 한 세션이 팀 리드가 되고, 여러 팀원이 독립된 Claude Code 세션으로 움직입니다. Subagent가 결과를 메인 세션에 돌려주는 구조라면, Agent Teams의 팀원은 공유 작업 목록을 사용하고 서로 직접 메시지를 주고받을 수 있습니다.

Agent Teams 활성화하기

프로젝트의 .claude/settings.json에 다음 환경 변수를 추가합니다.

{
  "env": {
    "CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS": "1"
  }
}

현재 버전도 확인합니다.

claude --version

공식 문서 기준 Agent Teams는 Claude Code 2.1.32 이상이 필요합니다.

첫 팀 요청 예시

Claude Code 7단계 블로그 글을 검수할 Agent Team을 만들어줘.

- 리서처: 공식 문서와 사실 관계 확인
- 실습 검수자: 명령과 파일 예제 검토
- 에디터: 입문자 관점에서 문장과 흐름 검토

세 역할은 독립적으로 검토하고,
서로 발견한 문제를 공유한 뒤,
팀 리드가 최종 수정안을 정리해줘.

이 작업은 세 역할이 같은 초안을 서로 다른 관점에서 검토할 수 있어 병렬 처리에 적합합니다. 반대로 한 작업이 끝나야 다음 작업을 시작할 수 있거나 같은 파일을 동시에 수정해야 한다면 팀을 만드는 비용이 더 클 수 있습니다.

Subagents와 Agent Teams 비교

Agent Teams의 핵심은 AI를 많이 실행하는 것이 아닙니다. 서로 독립적으로 진행할 수 있고, 결과를 공유하며 토론해야 하는 작업에만 사용하는 것입니다.

프로젝트 상태 파일도 함께 사용해보기

Agent Teams의 내부 팀 설정과 작업 목록은 Claude Code가 자동으로 관리합니다. 사용자가 직접 팀 설정 파일을 미리 만들거나 수정할 필요는 없습니다.

다만 콘텐츠나 프로젝트의 확정된 결정은 별도의 상태 문서로 남겨두면 다음 세션이 이어받기 편합니다.

# 프로젝트 상태

## 목표

Claude Code 7단계 블로그 글을 완성한다.

## 현재 진행 상황

- 자료 조사: 완료
- 본문 작성: 진행 중
- 코드 검증: 대기
- 최종 편집: 대기

## 확정된 기준

- 입문자를 대상으로 작성한다.
- 각 단계마다 실습 예제를 넣는다.
- 최신 기능은 공식 문서로 검증한다.

## 다음 작업

Skills와 Subagents 예제의 문법을 최종 확인한다.

대화 전체와 시행착오를 모두 전달하면 다음 작업자도 혼란스러워집니다. 확정된 결정과 현재 상태, 다음 작업만 짧게 남기는 것이 좋습니다.

마무리: 이번 주 한 단계만 올려보기

아래 표에서 지금 바로 할 수 있는 항목을 찾아보세요.

Claude Code를 잘 쓴다는 것은 가장 높은 단계를 무조건 사용하는 것이 아닙니다. 지금 하는 일에 필요한 만큼만 구조를 추가하고, 반복되는 지점이 생길 때 다음 단계로 넘어가는 것이 더 효율적입니다.

이번 주에는 일곱 단계를 한꺼번에 적용하지 마세요. 현재 단계에서 바로 다음 단계로 가는 실습 하나만 골라 직접 만들어보세요.

여러분은 지금 Claude Code를 몇 레벨로 사용하고 있나요?

자주 묻는 질문