클로드 코드가 처음이라면, 이 글을 꼭 읽어주세요!

클로드 코드(Claude Code)란?

클로드 코드(Claude Code)를 이해할 때 가장 먼저 짚고 넘어가야 할 게 하나 있습니다.

이건 단순한 채팅형 AI가 아니라는 점이에요.

지시를 이해하고, 스스로 계획을 세우고, 작업을 실행하고, 결과를 확인하는 자율적인 AI 에이전트에 가깝습니다.

느낌으로 말하면, 물어보는 도구라기보다는 일을 맡길 수 있는 동료에 더 가깝죠.

그래서 클로드 코드를 쓸 때 가장 중요한 건 얼마나 코드를 아느냐가 아니라, 얼마나 명확하게 일을 맡기느냐입니다.

AI 에이전트와 에이전틱 워크플로우

이걸 이해하는 데 도움이 되는 개념이 바로 AI 에이전트와 에이전틱 워크플로우입니다.

일반적인 챗봇은 질문을 받으면 답을 주고 끝납니다. 반면 AI 에이전트는 목표를 받습니다. 그리고 그 목표를 달성하기 위해 스스로 판단하고, 필요한 도구를 쓰고, 여러 단계를 조정합니다.

예를 들어 논문 번역을 시킨다고 가정해볼게요.

Claude Code는 단순히 번역해드립니다하고 끝내지 않습니다.

• PDF를 읽고
• 텍스트를 추출하고
• 번역하고
• 다시 문서 형태로 정리하는

여러 단계를 스스로 계획해서 실행합니다.

이 전체 흐름을 에이전틱 워크플로우라고 부릅니다.

정해진 순서만 반복하는 자동화와 달리 중간에 문제가 생기면 판단을 바꿔가며 경로를 수정하는 게 특징이에요.

클로드 코드(Claude Code)가 할 수 있는 것, 그리고 할 수 없는 것

클로드 코드(Claude Code)는 만능이 아닙니다. AI가 다 해줄 거야라는 기대로 시작하면 어려움을 겪을 확률이 큽니다.

클로드 코드(Claude Code)가 잘하는 것

• 코드 작성과 수정. 파일을 읽고, 분석하고, 정리하는 일.
• 반복적인 작업을 자동화하는 일. 버그를 찾아서 고치는 일.
• Git(버전 관리 도구)으로 작업 이력을 관리하는 일.

클로드 코드(Claude Code)가 못하는 것

• 뭘 만들어야 할지를 대신 결정해주는 것.
• 비즈니스 방향성을 잡아주는 것.
• 창의적인 아이디어를 처음부터 만들어내는 것. 최종 판단과 책임.

정리하면 이렇습니다.

뭘 해야 하는지는 우리가 정하고, 어떻게 할 것인지는 Claude Code가 실행합니다.

방향을 정하는 건 여전히 사람의 몫이에요. 다만, 그 방향대로 실행하는 속도와 정확성이 압도적으로 빨라지는 겁니다!

클로드 코드, 어디서 쓰느냐에 따라 역할이 달라요

클로드 코드(Claude Code)는 같은 AI인데도 어디에서 쓰느냐에 따라 하는 일이 달라집니다.

쉽게 말하면 장소에 따라 클로드 코드의 역할이 바뀐다고 생각하면 돼요.

1️⃣ 터미널에서 쓰는 클로드 코드

👉 실제로 일을 시킬 때

이렇게 이해하면 쉬워요 → 손을 움직여서 직접 작업하는 직원

여기서 할 수 있는 일

• 파일을 직접 만들고 고치기
• 데이터 정리, 자동화 실행
• 반복 작업 대신 처리
• 작업 결과를 바로 만들어냄

이럴 때 쓰면 좋아요

• 엑셀 파일 정리
• 블로그 콘텐츠 자동 생성
• 웹사이트 수정
• 매번 반복되는 귀찮은 업무

2️⃣ VS Code 같은 편집기에서 쓰는 클로드 코드

👉 무슨 일이 벌어지는지 보면서 맡길 때

이렇게 이해하면 쉬워요 → 옆에서 같이 보며 일하는 직원

여기서 좋은 점

• 클로드 코드가 뭘 바꾸는지 눈으로 보임
• 잘못된 방향이면 바로 멈출 수 있음
• 불안하지 않게 작업 진행 가능

이럴 때 쓰면 좋아요

• 처음 클로드 코드를 써볼 때
• 파일이 여러 개 얽힌 작업
• 결과를 확인하면서 천천히 맡기고 싶을 때

3️⃣ 웹이나 아이폰 앱에서 쓰는 클로드 코드

👉 생각 정리하고 계획 세울 때

이렇게 이해하면 쉬워요 → 일을 맡기기 전 회의실

여기서 할 수 있는 일

• 하고 싶은 작업 정리
• 자동화 아이디어 구상
• 지시 문장 다듬기
• CLAUDE.md 초안 만들기

주의할 점

• 여기서는 실제 작업은 안 함
• 파일을 직접 고치지는 않음

4️⃣ 슬랙에서 쓰는 클로드 코드

👉 팀 안에서 이야기할 때

이렇게 이해하면 쉬워요 → 팀 대화에 끼어 있는 조력자

여기서 할 수 있는 일

• 작업 내용 정리해주기
• 누군가 한 작업 설명해주기
• 팀 질문에 답해주기

이럴 때 쓰면 좋아요

• 여러 사람이 함께 일할 때
• 개발자와 비개발자가 섞인 팀
• 작업 맥락을 공유해야 할 때

한 번에 정리하면 이렇게 생각하세요

클로드 코드(Claude Code)와 대화할 때 꼭 알아둘 것들

몇 가지 기본적인 약속을 알아두면 좋습니다.

Plan 모드를 무조건 활용하세요!

클로드 코드(Claude Code)를 쓰면서 꼭 경험하게 되는 기능이 하나 있는데, 바로 Plan Mode입니다.

클로드 코드(Claude Code)는 일을 바로 시작하지 않습니다. 먼저 이렇게 말하죠.

“이렇게 이렇게 할 건데, 이 방향 맞나요?”

이 단계에서 어떤 파일을 건드릴지, 어떤 명령을 실행할지, 어떤 결과물을 만들지
계획을 먼저 보여줍니다.

그리고 우리가 할 일은 단순합니다.

그 계획이 의도에 맞는지만 판단하면 돼요.

이게 비개발자에게 특히 중요한 이유는, 코드는 몰라도 계획은 읽을 수 있기 때문입니다.

“이건 아닌데?”
“이건 빼고 가자”

이 정도 판단만 해줘도, 결과물의 퀄리티가 완전히 달라집니다. Plan 모드에서 계획을 구체적으로 해둘 수록 결과물을 내 의도대로 만드는 데 수월해져요.

*   **Plan Mode**: Claude Code가 사용자의 요청을 분석하고, 어떤 파일을 수정하고, 어떤 명령어를 실행할지 등 구체적인 계획을 제시하는 단계입니다. 이 계획을 검토하고 승인하거나 수정할 수 있습니다.

*   **실행 모드 (Execution Mode)**: Plan Mode에서 승인된 계획을 Claude Code가 실제로 실행하는 단계입니다. 이 과정에서 Claude는 파일을 편집하고, 터미널 명령어를 실행하며, Git 작업을 수행하는 등 자율적으로 작업을 진행합니다.

슬래시 커맨드(/)를 활용하세요!

클로드 코드(Claude Code)는 터미널에서 /로 시작하는 특수 명령어를 지원합니다. 자주 쓰는 것만 정리하면 이렇습니다.

*   `claude`: 대화형 세션을 시작합니다.
*   `/help`: 사용 가능한 명령어 목록과 도움말을 확인합니다.
*   `/login`: 계정 로그인 또는 전환을 수행합니다.
*   `/compact`: 현재 대화의 맥락을 압축하여 토큰 사용량을 줄입니다.
*   `/review`: 현재 프로젝트의 변경 사항을 Claude에게 검토해달라고 요청합니다.
*   `/commit`: 변경 사항을 Git에 커밋하고 커밋 메시지를 작성하도록 지시합니다.
*   `/terminal`: Claude Code 세션 내에서 직접 터미널 명령어를 실행할 수 있는 모드로 전환합니다.
*   `/teleport`: 웹 또는 iOS 앱에서 시작한 작업을 터미널로 가져옵니다.
*   `/desktop`: 터미널 세션을 데스크톱 앱으로 전환하여 시각적 차이점 검토를 용이하게 합니다.

이것만 알아도 대부분의 상황에서 막힘없이 쓸 수 있습니다.

CLAUDE.md 파일을 만들어두세요

이건 정말 중요한 팁인데요.

프로젝트 폴더에 CLAUDE.md라는 파일을 하나 만들어두면, 클로드 코드(Claude Code)는 세션을 시작할 때 이 파일을 가장 먼저 읽습니다.

쉽게 말하면 이 파일은 AI에게 미리 건네주는 업무 가이드라인이에요.

우리가 매번 “이 프로젝트는 이런 목표고, 이런 방식으로 일해줘” 라고 설명하지 않아도, Claude Code가 기본 행동 원칙 + 프로젝트 맥락을 이미 알고 시작하게 됩니다.

그래서 결과물이 훨씬 안정적이고 불필요한 코드도 확 줄어들어요.

CLAUDE.md에 지침을 넣는 방법은 2가지가 있습니다

1️⃣ 이 가이드라인만 단독으로 넣는 방법

• 범용적으로 쓸 때
• 어떤 프로젝트든 Claude Code가 같은 코딩 습관으로 동작하길 원할 때

즉, “일단 이 원칙은 무조건 지켜” 라는 기본값을 세팅하는 용도입니다.

2️⃣ 프로젝트별 지침과 합쳐서 넣는 방법 (추천)

이게 더 많이 쓰이는 방식이에요.

• 문서 맨 위에 이 가이드라인을 두고 그 아래에 프로젝트 맥락을 추가합니다
  (목표, 기술 스택, 톤앤매너, 제약 조건 등)
• 아래 예시 가이드라인 자체에도 “Merge with project-specific instructions as needed” 라고 적혀 있죠.

이걸 전제로 만들어진 문서예요.

이렇게 하면 Claude Code가

• ❌ “괜히 이것도 해볼까?”
• ❌ “이 정도면 과하지 않나?”

같은 실수를 훨씬 덜 하게 됩니다.

대신,

• 물어볼 건 먼저 묻고
• 필요한 만큼만 만들고
• 목표 기준으로 끝까지 검증하는

아주 ‘일 잘하는 동료’ 같은 태도로 움직이게 돼요.

실제로 쓰는 CLAUDE.md 예시

아래는 그냥 그대로 복사해서 써도 되는 예시입니다. (출처 : andrej-karpathy-skills)

# Behavioral Guidelines for Claude Code

Behavioral guidelines to reduce common LLM coding mistakes.
Merge with project-specific instructions as needed.

Tradeoff:
These guidelines bias toward caution over speed.
For trivial tasks, use judgment.

---

## 1. Think Before Coding

Don't assume.
Don't hide confusion.
Surface tradeoffs.

Before implementing:
- State assumptions explicitly. If uncertain, ask.
- If multiple interpretations exist, present them.
- If a simpler approach exists, say so and push back if needed.
- If something is unclear, stop and ask before coding.

---

## 2. Simplicity First

Write the minimum code that solves the problem.
Nothing speculative.

- No features beyond what was asked.
- No abstractions for single-use code.
- No unrequested flexibility or configurability.
- No error handling for impossible scenarios.
- If 200 lines can be 50, rewrite it.

Ask:
"Would a senior engineer say this is overcomplicated?"
If yes, simplify.

---

## 3. Surgical Changes

Touch only what you must.
Clean up only your own mess.

When editing existing code:
- Don’t improve adjacent code or formatting.
- Don’t refactor what isn’t broken.
- Match existing style.
- If you see unrelated dead code, mention it — don’t delete it.

If your changes create orphans:
- Remove unused imports/variables/functions you introduced.
- Don’t remove pre-existing dead code unless asked.

Every changed line must trace directly to the user’s request.

---

## 4. Goal-Driven Execution

Define clear success criteria.
Loop until verified.

Transform vague tasks into verifiable goals:
- “Add validation” → write failing tests, then make them pass
- “Fix a bug” → reproduce with a test, then fix it
- “Refactor X” → ensure tests pass before and after

For multi-step tasks, state a brief plan:
1. Step → verify
2. Step → verify
3. Step → verify

여기에 프로젝트 지침을 추가한다면? 이 아래에 이런 걸 이어서 쓰면 됩니다.

---

## Project Context

### Goal
- 하이아웃풋클럽 블로그 콘텐츠 자동화

### Tech Stack
- Python 3.9+
- Markdown output

### Tone & Style
- 한국어
- 과장 없이, 실무자 시점
- 설명은 친절하지만 가볍지 않게

그리고 꼭 파일로 저장하지 않아도 괜찮아요.

처음 Claude Code 세션을 시작할 때 이 내용을 그냥 그대로 붙여넣어도 동일하게 작동합니다.

즉,

• CLAUDE.md 파일로 만들어두면 → 항상 자동으로 읽히는 영구 가이드
• 파일을 안 만들고 프롬프트로 주면 → 해당 세션 한정 가이드

이 차이일 뿐이에요.

왜 이게 그렇게 효과적이냐면?

Claude Code는 지금 뭐가 중요한지를 기준으로 행동하는 도구라서 그래요.

• 행동 원칙 → 코딩 습관
• 프로젝트 맥락 → 판단 기준

이 두 개를 동시에 쥐여주면,

• 쓸데없는 코드 덜 만들고 애매하면 먼저 묻고
• “이 정도면 됐나?”에서 멈추지 않고
• 검증까지 가는 흐름이 만들어집니다.

그리고 이 모든 걸 우리가 매번 말하지 않아도, Claude Code가 알아서 참고합니다.

그래서 CLAUDE.md는 한 번 잘 만들어두면 계속 써먹게 되는 파일이에요.

클로드 활용 사례

클로드 코드가 진짜 힘을 발휘하는 지점은 개발자가 아닌 사람이 자신의 업무를 자동화하기 시작할 때입니다.

코드를 몰라도 괜찮고, 기술 스택을 외우지 않아도 됩니다. 내가 반복해서 하고 있는 일을 정확히 설명할 수 있다면 무엇이든 가능해요.

예로 들자면, 이런 일들을 할 수 있어요.

마케터 | SEO 분석 및 자동 최적화

문제 상황

• 웹사이트 SEO가 필요하다는 건 알지만
• 어떤 파일을, 어디서, 어떻게 고쳐야 하는지 모름
• 메타 태그, 제목 태그, 이미지 alt 태그 점검이 부담됨

Claude Code에게 맡긴 일

• 웹사이트 전체 파일 구조 분석
• SEO 관점에서 취약한 요소 자동 탐색
• 개선이 필요한 코드 직접 수정

작업 방식

• 파일 전체 스캔
• SEO 문제 지점 목록화
• 수정 계획을 Plan Mode로 제시

콘텐츠 크리에이터 | 유튜브 → 블로그 자동 변환

문제 상황

• 유튜브 영상은 만들었지만
• 스크립트를 블로그 글로 옮기는 데 시간이 너무 많이 듦
• 콘텐츠 재활용이 늘 미뤄짐

Claude Code에게 맡긴 일

• 유튜브 영상 스크립트 추출
• 스크립트 기반 블로그 글 작성
• 마크다운 형식으로 구조화

작업 방식

• YT-DLP로 영상 스크립트 추출
• 핵심 내용 요약
• 소제목 중심의 글 구조 생성
• 초안 생성 후 사용자 피드백 반영

1인 사업가 | 고객 문의 자동 응답 챗봇

문제 상황

• 고객 문의가 늘어나면서 응대 부담 증가
• 같은 질문이 반복됨
• 모든 답변을 직접 처리하기 어려움

Claude Code에게 맡긴 일

• FAQ 데이터 기반 자동 응답 시스템 구축
• Slack 채널과 연동된 챗봇 생성

작업 방식

• FAQ 데이터 파일 참조
• Slack API 연동 코드 작성
• 자동 응답 로직 구현
• 실행 및 테스트까지 자동 처리

재무 담당자 | 엑셀 데이터 정리 및 보고서 자동 생성

문제 상황

• 매달 쌓이는 지출 엑셀 파일
• 수작업으로 정리하는 데 많은 시간 소요
• 보고서 작성이 반복 업무로 누적됨

Claude Code에게 맡긴 일

• 엑셀 파일 통합 및 분석
• 카테고리별 지출 분류
• 월별·분기별 요약 보고서 생성

작업 방식

• 엑셀 파일 자동 읽기
• 데이터 처리 라이브러리 활용
• 지출 구조 분석
• 마크다운 형식 보고서 작성

이 사례들의 공통점은 하나입니다.

우리는 무엇을 원하는지만 설명했고 어떻게 구현할지는 AI가 알아서 처리했다는 점입니다. 그래서 중요한 건 기술 용어가 아니라 업무를 설명하는 언어입니다.

지금 하고 있는 일 중에서 매번 똑같이 반복되는 작업이 있다면, 그걸 사람에게 설명하듯 정리해보세요.

그 정도 설명이 가능하다면, Claude Code는 충분히 그 일을 해낼 수 있습니다.

클로드 코드, 에러가 나도 당황하지 마세요

쓰다 보면 에러를 만나는 경우가 있습니다. 비개발자 입장에서 빨간 글씨가 뜨면 좀 무섭죠.

자주 만나는 에러 3가지만 알아두면 대부분 해결됩니다.

• 권한 에러 (Permission Error) : Claude Code가 특정 파일에 접근할 수 없을 때 나옵니다. → Claude에게 "이 파일 접근 권한을 확인해줘"라고 말하면 됩니다.
• 환경 변수 누락 에러 : API 키 같은 설정값이 빠져 있을 때 나옵니다. → ".env 파일을 만들어서 필요한 환경 변수를 추가해줘"라고 요청하세요.
• 맥락 상실 (Context Loss) — 대화가 너무 길어져서 Claude가 이전 내용을 잊어버릴 때 나옵니다. → /compact를 입력하거나, CLAUDE.md에 핵심 정보를 정리해두세요.

중요한 건, 에러가 나더라도 클로드 코드(Claude Code)한테 "이런 에러가 났는데 어떻게 해결해?"라고 물어보면 대부분 스스로 해결 방법을 찾아서 실행합니다.

한 가지만 기억하세요

Claude Code는 코딩을 배우기 위한 도구가 아니라, 코딩을 몰라도 원하는 결과물을 만들기 위한 도구입니다.

우리가 해야 할 일은 명확합니다.

1. 뭘 만들고 싶은지 구체적으로 말하기
2. Claude Code의 계획을 확인하고 방향 잡아주기
3. 결과물을 검토하고 피드백하기

이 세 가지만 하면 됩니다.

코딩 실력이 아니라 지시의 정확성이 결과를 결정합니다. 비즈니스 맥락을 가장 잘 아는 건 결국 우리니까요.