AI 에이전트 사용 매뉴얼

1부 · 시작하기

1이게 뭔가요

먼저 이름부터 정리합니다. 세 가지가 자주 섞여 쓰입니다.

이름 구분하기

이름	정체	비유
Claude	Anthropic이 만든 AI 모델. 실제로 생각하고 답하는 주체입니다.	사람
Opus 5	Claude의 버전 이름. 여러 버전 중 가장 성능이 높은 쪽입니다.	그 사람의 실력 등급
Claude Code	Claude가 내 컴퓨터의 파일을 읽고 고칠 수 있게 해 주는 프로그램입니다.	그 사람에게 준 책상과 도구

이 매뉴얼은 Claude Code 사용법을 다룹니다.

웹 Claude와 무엇이 다른가요

claude.ai 웹사이트에서도 Claude와 대화할 수 있습니다. 가장 큰 차이는 하나입니다.

	웹 Claude (claude.ai)	Claude Code
파일 접근	내가 올린 것만 봅니다.	내 컴퓨터의 폴더를 직접 읽고 고칩니다.
결과물	화면에 답을 보여줍니다.	파일이 실제로 바뀝니다.
명령 실행	못 합니다.	합니다. (승인을 받고)

이 차이가 핵심입니다 Claude Code는 대화만 하는 것이 아니라 실제로 내 파일을 바꿉니다. 그래서 4장(승인 창 읽는 법)과 5장(하면 안 되는 것)이 이 매뉴얼에서 가장 중요합니다.

할 수 있는 일

폴더 안의 문서·자료를 읽고 요약합니다.
문서를 새로 쓰거나 고칩니다. 여러 파일을 한 번에 고칠 수도 있습니다.
여러 파일에 흩어진 내용을 찾아 정리합니다.
표·자료를 다른 형식으로 바꿉니다.
반복 작업을 대신 실행합니다.

못 하는 일 — 먼저 알아 두세요

기대를 정확히 잡는 것이 도입 실패를 막는 가장 빠른 길입니다.

지정한 폴더 밖은 보지 못합니다. 내 컴퓨터 전체를 아는 것이 아닙니다.
지난 대화를 자동으로 기억하지 못합니다. 창을 닫으면 대화는 사라집니다. 6장과 7장이 이 문제를 다룹니다.
사내 시스템·사내망 자료에 접근하지 못합니다. 별도 연결 설정이 필요합니다.
틀릴 수 있습니다. 특히 숫자, 날짜, 고유명사는 사람이 확인해야 합니다.
승인 없이 무엇을 삭제하거나 외부로 보내지 않습니다. 다만 사용자가 승인하면 실행합니다. 그래서 승인 창을 읽어야 합니다.

2설치하고 첫 실행

Claude Code를 쓰는 방법은 두 가지입니다. 둘 중 하나만 하면 됩니다.

방법	이런 분께	화면
A. VS Code 확장	대부분의 직원	편집기 안에서 마우스로 사용합니다.
B. 터미널(CLI)	명령어 입력이 익숙한 분	검은 화면에 명령어를 칩니다.

권장 처음이라면 A(VS Code 확장)로 시작하세요. 설치가 클릭 몇 번이고, 파일이 어떻게 바뀌었는지 눈으로 볼 수 있습니다.

방법 A · VS Code 확장 설치

VS Code를 실행합니다. (없으면 먼저 VS Code를 설치합니다.)
왼쪽 세로 막대에서 확장(Extensions) 아이콘을 누릅니다.
검색창에 Claude Code를 입력합니다.
만든 곳이 Anthropic인 항목을 찾아 설치(Install)를 누릅니다.
설치가 끝나면 VS Code 안에서 Claude Code를 열고 로그인합니다.

(확인 필요) 설치 후 로그인 화면의 정확한 문구와 버튼 이름, 회사 계정으로 로그인하는지 개인 계정으로 로그인하는지는 사내 정책 확인 후 채워 넣습니다. 지금 단계에서는 임의로 적지 않습니다.

방법 B · 터미널에서 쓰기

주의: 확장을 설치해도 터미널 명령은 바로 안 됩니다 VS Code 확장만 설치한 상태에서는 터미널에 claude라고 쳐도 command not found가 나옵니다. 터미널에서 쓰려면 별도 설치가 필요합니다.

(확인 필요) 사내 표준 설치 방법(npm 설치 / 공식 설치 스크립트 / 확장에 포함된 실행 파일 사용) 중 무엇을 표준으로 삼을지 정해지면 이 자리에 명령어를 적습니다. 검증 전까지 명령어를 적지 않습니다. 틀린 설치 명령은 전 직원의 시간을 낭비시킵니다.

설치가 잘 됐는지 확인하기

터미널에서 아래를 입력하면 버전이 나옵니다.

claude --version

이 매뉴얼을 쓴 시점의 사내 확인 버전은 2.1.259입니다.

설치 상태를 점검하는 명령도 있습니다.

claude doctor

3폴더와 대화

Claude Code를 이해하는 핵심 개념은 딱 하나, 작업 폴더입니다.

작업 폴더란

Claude Code는 시작할 때 폴더 하나를 정합니다. 그 폴더 안에 있는 파일만 읽고 고칩니다. 바깥 파일은 보지 못합니다.

이렇게 생각하세요 Claude에게 서류함 한 칸을 열어 주는 것과 같습니다. 그 칸 안의 서류는 모두 볼 수 있지만, 옆 칸은 열지 못합니다. 그래서 어떤 폴더를 열어 줄지가 곧 보안 설정입니다.

일을 시작하기 전에 그 일에 필요한 파일만 모아 둔 폴더를 만드는 것이 좋습니다.

시켜 보기

대화창에 한국어로 그냥 쓰면 됩니다. 명령어 문법을 외울 필요가 없습니다.

이 폴더에 어떤 파일들이 있는지 정리해 줘

보고서.md 를 읽고 세 줄로 요약해 줘

회의록.txt 에서 결정된 사항만 뽑아서 표로 만들어 줘

결과 확인하기 — 반드시 하세요

Claude가 "완료했습니다"라고 해도 사람이 직접 파일을 열어 확인합니다.

바뀐 파일을 엽니다.
숫자·날짜·사람 이름·회사 이름을 특히 봅니다. 여기서 틀리는 일이 가장 많습니다.
이상하면 그대로 말합니다. 예: 3번 항목 날짜가 틀렸어. 원본은 8월 12일이야.

2부 · 안전하게 쓰기

4승인 창 읽는 법

Claude Code가 파일을 고치거나 명령을 실행하기 전에 물어보는 창입니다. 이 장이 이 매뉴얼에서 가장 중요합니다.

왜 물어보나요

Claude Code는 실제로 내 컴퓨터를 건드립니다. 그래서 위험할 수 있는 동작 앞에서 멈추고 사람에게 확인합니다. 이 창은 형식적인 절차가 아니라 마지막 방어선입니다.

승인 전에 볼 세 가지

무엇을 하려는가 — 파일을 읽는지, 고치는지, 지우는지, 명령을 실행하는지 봅니다.
어떤 파일인가 — 경로를 확인합니다. 내가 생각한 그 파일이 맞습니까?
되돌릴 수 있는가 — 삭제와 덮어쓰기는 되돌리기 어렵습니다.

바로 승인해도 되는 것

파일을 읽는 동작
폴더 안 파일 목록을 보는 동작
내용을 검색하는 동작

멈추고 확인할 것

아래가 보이면 승인하기 전에 한 번 더 읽으세요

삭제 — 지운 파일은 돌아오지 않을 수 있습니다.
덮어쓰기 — 원본이 사라집니다. 중요한 파일이면 먼저 복사본을 만들어 두세요.
작업 폴더 바깥 경로 — 왜 바깥을 건드리는지 이유가 설명되지 않았다면 거절합니다.
외부로 보내는 동작 — 메일 발송, 업로드, 외부 서비스 전송. 한번 나간 자료는 회수할 수 없습니다.
내용을 이해하지 못한 명령어 — 모르면 승인하지 않습니다. 무엇을 하는 명령인지 Claude에게 먼저 설명을 요구하세요.

거절해도 됩니다

거절은 고장이 아닙니다. 거절하면 Claude는 다른 방법을 찾거나 이유를 묻습니다. 애매하면 거절하고 물어보는 쪽이 항상 맞습니다.

방금 그 명령이 무슨 일을 하는 건지 먼저 설명해 줘. 실행은 하지 마.

권한 모드

매번 묻는 것이 번거로울 때 동작 방식을 바꿀 수 있습니다. 확인된 모드는 다음과 같습니다.

모드	동작
`manual`	매번 사람에게 묻습니다.
`acceptEdits`	파일 편집은 묻지 않고 진행합니다.
`plan`	계획만 세우고 실제로 고치지는 않습니다.
`auto`	상황에 따라 자동으로 판단합니다.
`dontAsk`	묻지 않습니다.
`bypassPermissions`	권한 확인을 모두 건너뜁니다.

회사 자료를 다룰 때 bypassPermissions와 권한 검사를 건너뛰는 옵션은 사용하지 마세요. 이름에 "위험(dangerously)"이 들어 있는 데는 이유가 있습니다. 처음에는 manual로 쓰고, 익숙해진 뒤 acceptEdits 정도까지만 권장합니다.

5하면 안 되는 것

회사 자료를 다루는 도구이므로 아래는 규칙입니다.

이미 정해져 있는 팀 규칙

CS팀 전역 규칙 파일에 아래가 명시돼 있습니다. AI를 쓸 때도 그대로 적용됩니다.

고객 데이터를 외부로 유출하지 않습니다.
공통 지식 문서에는 고객 실명·실수치를 넣지 않습니다. 익명화합니다.
값을 임의로 지어내지 않습니다. 모르면 (확인 필요)로 표기합니다.

작업 폴더를 좁게 잡으세요

3장에서 설명한 대로 Claude는 작업 폴더 안만 봅니다. 이것이 가장 실효성 있는 보호 장치입니다.

바탕화면이나 드라이브 전체를 작업 폴더로 열지 마세요.
그 일에 필요한 파일만 담긴 폴더를 만들어 여세요.
다른 고객 자료가 같은 폴더에 섞여 있지 않은지 확인하세요.

넣지 말아야 할 내용

비밀번호, API 키, 인증서, 접속 토큰
사내 서버 주소·내부 시스템 접속 정보
고객 개인정보(주민번호, 연락처, 계좌 등)
계약서 원문 등 대외비 문서 — 사내 정책 확인 전까지 올리지 않습니다.

(확인 필요) — 이 장은 미완성입니다 아래 항목은 회사 공식 보안·데이터 규정 원문을 받아서 채웁니다. 임의로 작성하지 않습니다.

AI 도구에 올려도 되는 자료 등급의 기준
고객 자료 사용 시 사전 승인 절차의 유무
위반 시 보고 경로와 담당 부서
개인 계정 사용 가능 여부

3부 · 제대로 쓰기

6세션 이어가기

"어제 하던 이야기"를 오늘 이어서 하는 방법입니다.

세션이란

세션은 대화 한 묶음입니다. 창을 새로 열면 새 세션이 시작되고, 이전 세션의 대화 내용은 기억하지 못합니다.

자주 하는 오해 "어제 알려줬잖아"는 통하지 않습니다. 새 세션의 Claude는 어제 대화를 본 적이 없습니다. 다만 파일로 남긴 것은 그대로 읽습니다. 그래서 7장이 필요합니다.

지난 대화 이어가기

터미널에서 아래 명령을 씁니다.

명령	동작
`claude --continue` (줄여서 `claude -c`)	현재 폴더의 가장 최근 대화를 이어갑니다.
`claude --resume` (줄여서 `claude -r`)	지난 대화 목록에서 골라 이어갑니다.

같은 폴더에서 실행해야 그 폴더의 대화 기록을 찾습니다.

컨텍스트가 뭔가요

컨텍스트는 Claude가 한 번에 기억할 수 있는 분량입니다. 대화가 길어지면 앞부분이 요약되어 세부 내용이 흐려질 수 있습니다.

다음과 같을 때는 새 세션으로 시작하는 편이 낫습니다.

주제가 완전히 바뀌었을 때
답이 점점 엉뚱해질 때
앞의 실패한 시도가 계속 발목을 잡을 때

중요 세션 이어가기는 같은 컴퓨터, 같은 폴더에서만 됩니다. 다른 사람이나 다른 PC와 대화를 공유하려면 7장처럼 파일로 남겨야 합니다.

7기억시키기

매번 같은 설명을 반복하지 않는 방법입니다. 핵심은 CLAUDE.md 파일 하나입니다.

CLAUDE.md란

Claude가 세션을 시작할 때마다 자동으로 읽는 규칙 파일입니다. 여기에 적어 두면 매번 설명할 필요가 없습니다.

어디에 두나요

위치	적용 범위	넣을 내용
사용자 폴더의 `.claude/CLAUDE.md`	모든 폴더	회사·팀 공통 규칙, 말투, 호칭
프로젝트 폴더의 `CLAUDE.md`	그 폴더만	그 일에만 해당하는 배경과 규칙

둘 다 있으면 둘 다 읽습니다. 내용이 충돌하면 프로젝트 쪽이 우선합니다.

찾는 요령 Windows에서 사용자 폴더는 보통 C:\Users\사용자이름입니다. .claude 폴더는 이름이 점으로 시작해서 탐색기에서 숨긴 항목 표시를 켜야 보입니다. 주소창에 %USERPROFILE%\.claude를 붙여 넣어도 열립니다.

무엇을 적나요

좋은 CLAUDE.md는 길지 않습니다. 길수록 각 규칙의 영향력이 약해집니다.

적을 것	적지 말 것
말투·언어 규칙	일반적인 좋은 말 ("잘 해라")
자주 틀리는 지점의 교정	Claude가 이미 잘 하는 것
이 일의 배경·목적	자주 바뀌는 현재 상태 — 금방 낡습니다
절대 하면 안 되는 것	파일을 보면 알 수 있는 내용

잘 쓰는 요령 세 가지

판정 가능하게 씁니다.
"좋은 문서를 써라"(판정 불가) → "한 항목에 한 동작만 적어라"(위반이 눈에 보임)
금지만 하지 말고 대신 할 일을 줍니다.
"지어내지 마라"만 있으면 멈춥니다 → "모르면 (확인 필요)로 표기해라"
실제로 틀렸던 것만 추가합니다.
미리 넣어 둔 규칙은 대부분 낭비입니다. 겪은 실패를 규칙으로 승격시키세요.

예시

# ○○기업 자료 정리

## 배경
- 매월 첫째 주에 전월 지표를 정리합니다.

## 규칙
- 문서는 한국어 존칭체로 씁니다.
- 숫자는 원본 파일에서 그대로 옮깁니다. 계산해서 채우지 않습니다.
- 값을 모르면 (확인 필요)로 적습니다. 추정치를 쓰지 않습니다.

## 하지 말 것
- 고객 실명을 파일명에 넣지 않습니다.

가장 쉬운 시작 방법 직접 쓰기 어려우면 Claude에게 시키세요. 이 폴더에서 하는 일을 정리해서 CLAUDE.md 초안을 만들어 줘 라고 한 뒤 내용을 확인하고 고치면 됩니다.

8잘 시키는 법

같은 일을 시켜도 어떻게 말하느냐에 따라 결과가 크게 달라집니다.

원칙 네 가지

대상을 지정합니다.
"요약해 줘" → "회의록_0812.txt를 읽고 결정 사항만 요약해 줘"
결과의 모양을 알려 줍니다.
"정리해 줘" → "표로 정리해 줘. 열은 항목·담당·기한 세 개로."
분량을 정해 줍니다.
"짧게" → "다섯 줄 이내로"
하지 말 것을 말합니다.
"원본에 없는 내용은 넣지 마. 모르는 값은 (확인 필요)로 남겨."

자주 실패하는 요청과 고치는 법

이렇게 하면 실패합니다	이렇게 고치세요
"알아서 잘 정리해 줘"	무엇을 기준으로 정리할지 지정합니다.
한 번에 열 가지를 시킴	하나씩 시키고 확인 후 다음으로 넘어갑니다.
파일 이름을 안 알려 줌	정확한 파일명을 적습니다.
틀린 답에 "아니야"만 함	어디가 왜 틀렸는지 알려 줍니다. "3번 날짜가 틀렸어. 원본은 8월 12일이야."
결과를 확인 안 함	반드시 파일을 열어 봅니다.

먼저 계획을 받아 보세요

큰 작업은 바로 시키지 말고 계획부터 받는 편이 안전합니다.

바로 고치지 말고, 어떻게 할 건지 순서부터 알려 줘.

계획이 마음에 들면 그때 진행시킵니다. 잘못된 방향으로 파일 열 개가 고쳐진 뒤에 발견하는 것보다 훨씬 낫습니다.

모르면 묻게 하세요

확실하지 않은 값은 채우지 말고 나한테 물어봐.

4부 · 더 나아가기

9슬래시 명령과 스킬

관심 있는 분만 보셔도 됩니다. 1~8장만으로도 충분히 일할 수 있습니다.

슬래시 명령

대화창에 /를 입력하면 쓸 수 있는 명령 목록이 나옵니다. 외울 필요 없이 /만 치면 됩니다.

(확인 필요) 자주 쓰는 기본 명령 목록은 사내 환경에서 하나씩 실행해 확인한 뒤 이 표를 채웁니다. 화면에 실제로 보이는 설명 문구를 그대로 옮겨 적습니다.

스킬

스킬은 자주 하는 작업 절차를 미리 적어 둔 것입니다. 한 번 만들어 두면 이름만 불러서 실행합니다.

CS팀에는 이미 아래 스킬이 준비돼 있습니다.

스킬	하는 일
`/new-customer-project`	신규 고객 폴더를 팀 표준 구조로 만들어 줍니다.
`/promote-knowledge` (약속어: 스킬업)	이번 작업에서 배운 것을 정리해 다음에도 쓰이도록 저장합니다.

스킬업 절차 학습 내용은 바로 저장되지 않습니다. 수확 → 사람 승인 → 미리보기 → 진행 순서를 거칩니다. 사람이 확인하지 않은 내용은 저장되지 않습니다.

10서브에이전트

일을 나눠서 시키는 기능입니다.

서브에이전트는 특정 역할을 맡은 별도의 Claude입니다. 역할과 규칙을 미리 정해 두면 그 일에 맞게 동작합니다.

CS팀 구성

이름	역할
`cs-team-lead`	팀장. 요청을 보고 누구에게 맡길지 정하고 결과를 종합합니다.
`onboarding-specialist`	신규 고객 온보딩 문서를 씁니다.
`retention-analyst`	이탈 위험을 진단하고 갱신·업셀 액션을 제안합니다.
`monitoring-agent`	지표를 모니터링하고 리포트를 만듭니다.

고객 관련 일은 cs-team-lead에게 맡기면 알맞은 담당에게 넘깁니다.

비용과 시간 서브에이전트를 여러 개 돌리면 그만큼 시간과 사용량이 늘어납니다. 간단한 일은 그냥 직접 시키는 편이 빠릅니다.

11실무 활용 예시

바로 따라 할 수 있는 요청문입니다. 파일명은 실제 파일명으로 바꿔 쓰세요.

회의록 정리

회의록_0812.txt 를 읽고 아래 형식으로 정리해 줘.
- 결정 사항
- 담당자별 할 일 (담당 / 내용 / 기한)
- 다음 회의에서 정할 것
원문에 없는 내용은 넣지 말고, 담당이나 기한이 없으면 (확인 필요)로 적어 줘.

여러 문서에서 찾기

이 폴더의 모든 문서에서 "갱신"이라는 말이 나오는 부분을 찾아서
어느 파일 어디에 있는지 목록으로 만들어 줘.

자료 형식 바꾸기

data.csv 를 읽고 부서별 합계를 표로 정리해 줘.
계산은 파일에 있는 값만 써. 없는 값은 만들지 마.

문서 초안 잡기

이 폴더의 자료를 참고해서 ○○기업 킥오프 자료 초안을 만들어 줘.
모르는 항목은 비워 두고 (확인 필요)라고 표시해 줘.

내가 쓴 글 다듬기

아래 문단을 고객에게 보낼 메일 톤으로 다듬어 줘.
내용은 바꾸지 말고 표현만 정리해 줘.

(확인 필요) 직군별(영업·개발·기획·지원) 실제 활용 사례는 사내에서 써 본 뒤 실제 사례로 채웁니다. 지어낸 사례는 넣지 않습니다.

부록

A안 될 때

터미널에서 `claude`가 실행되지 않습니다

command not found가 나오면 터미널용이 설치되지 않은 것입니다. VS Code 확장만 설치한 경우에 이렇게 됩니다. 2장 방법 B를 보세요.

파일을 못 찾는다고 합니다

그 파일이 작업 폴더 안에 있는지 확인합니다. 바깥 파일은 보지 못합니다.
파일 이름의 띄어쓰기와 확장자를 정확히 적었는지 확인합니다.

지난 대화를 기억하지 못합니다

정상입니다. 6장(세션 이어가기)과 7장(기억시키기)을 보세요.

엉뚱한 답을 계속합니다

어디가 왜 틀렸는지 구체적으로 알려 줍니다.
그래도 안 되면 새 세션에서 다시 시작합니다. 대화가 길어져 앞부분이 흐려졌을 수 있습니다.

승인 창이 계속 떠서 번거롭습니다

4장의 권한 모드를 보세요. 다만 회사 자료를 다룰 때는 bypassPermissions를 쓰지 않습니다.

설치 상태를 점검하고 싶습니다

claude doctor

(확인 필요) 사내 문의 창구(담당자·채널)를 확인해서 이 자리에 적습니다.

B용어 사전

용어	뜻
Claude	Anthropic이 만든 AI 모델. 대화의 상대입니다.
Opus 5	Claude의 버전 이름 중 하나. 성능이 가장 높은 쪽입니다.
Claude Code	Claude가 내 컴퓨터의 파일을 읽고 고칠 수 있게 해 주는 프로그램입니다.
프롬프트	AI에게 주는 지시문. 우리가 입력하는 말입니다.
세션	대화 한 묶음. 창을 새로 열면 새 세션입니다.
컨텍스트	Claude가 한 번에 기억할 수 있는 분량입니다.
작업 폴더	Claude Code가 읽고 고칠 수 있는 폴더. 이 바깥은 보지 못합니다.
CLAUDE.md	세션 시작 시 자동으로 읽히는 규칙 파일입니다.
터미널 / CLI	명령어를 입력해 프로그램을 쓰는 검은 화면입니다.
확장 (Extension)	VS Code에 기능을 추가하는 설치 항목입니다.
슬래시 명령	`/`로 시작하는 기능 호출입니다.
스킬	자주 하는 작업 절차를 미리 적어 둔 것입니다.
서브에이전트	특정 역할을 맡은 별도의 Claude입니다.
권한 모드	승인을 얼마나 자주 물을지 정하는 설정입니다.

1이게 뭔가요

이름 구분하기

웹 Claude와 무엇이 다른가요

할 수 있는 일

못 하는 일 — 먼저 알아 두세요

2설치하고 첫 실행

방법 A · VS Code 확장 설치

방법 B · 터미널에서 쓰기

설치가 잘 됐는지 확인하기

3폴더와 대화

작업 폴더란

시켜 보기

결과 확인하기 — 반드시 하세요

4승인 창 읽는 법

왜 물어보나요

승인 전에 볼 세 가지

바로 승인해도 되는 것

멈추고 확인할 것

거절해도 됩니다

권한 모드

5하면 안 되는 것

이미 정해져 있는 팀 규칙

작업 폴더를 좁게 잡으세요

넣지 말아야 할 내용

6세션 이어가기

세션이란

지난 대화 이어가기

컨텍스트가 뭔가요

7기억시키기

CLAUDE.md란

어디에 두나요

무엇을 적나요

잘 쓰는 요령 세 가지

예시

8잘 시키는 법

원칙 네 가지

자주 실패하는 요청과 고치는 법

먼저 계획을 받아 보세요

모르면 묻게 하세요

9슬래시 명령과 스킬

슬래시 명령

스킬

10서브에이전트

CS팀 구성

11실무 활용 예시

회의록 정리

여러 문서에서 찾기

자료 형식 바꾸기

문서 초안 잡기

내가 쓴 글 다듬기

A안 될 때

터미널에서 claude가 실행되지 않습니다

파일을 못 찾는다고 합니다

지난 대화를 기억하지 못합니다

엉뚱한 답을 계속합니다

승인 창이 계속 떠서 번거롭습니다

설치 상태를 점검하고 싶습니다

B용어 사전

터미널에서 `claude`가 실행되지 않습니다