Claude Code의 기초

입문 코스의 첫 글입니다. Claude Code가 무엇이고, 이미 쓰고 계신 채팅형 AI와 무엇이 다른지, 설치해서 첫 지시를 내리기까지를 다룹니다. 읽고 나면 터미널에서 claude를 켜고 내 폴더의 파일을 가지고 첫 업무 지시를 내릴 수 있습니다. 다음 글 「기본 조작과 명령어」에서 세션과 슬래시 명령을 이어서 배웁니다.

핵심 요약

• Claude Code는 Anthropic이 만든 터미널 기반 코딩 에이전트입니다. 질문에 답하는 데서 끝나지 않고 파일을 읽고, 고치고, 명령을 실행해 결과를 확인합니다.
• 채팅형 AI는 "대답하는 AI", Claude Code는 "일하는 AI"입니다. 우리 교육에서는 첫 시간부터 대화가 아니라 업무 지시를 연습합니다.
• 핵심 능력은 다섯 가지입니다. 코드 생성, 파일 조작, Git 연동, 외부 도구 연동(MCP), Bash 실행.
• 설치는 명령 한 줄이고, 처음 실행하면 브라우저에서 로그인합니다.
• 파일을 고치거나 명령을 실행하기 전에 승인을 묻는 것이 기본 동작입니다. 이 질문이 곧 안전장치입니다.

기존 AI 채팅과 무엇이 다른가

원구연 강사의 8주 교재 1주차는 이 한 줄로 시작합니다. "많은 분들이 AI를 질문하면 대답해 주는 챗봇으로 알고 계십니다. 그것도 맞지만, 지금의 AI는 한 단계 더 나아갔습니다." 채팅형 AI에게 "지원사업 공고 요약해 줘"라고 하면 요약문을 화면에 보여 줍니다. 결과를 내 문서로 옮기는 일은 사람 몫입니다. Claude Code에게 "이 폴더의 공고 30개를 읽고 내 고객사에 맞는 것만 골라 표로 정리해서 파일로 저장해 줘"라고 하면 실제로 파일을 읽고, 표를 만들고, 파일로 저장한 뒤 결과를 보고합니다.

지원형 도구와 에이전트형 도구

지원형 도구는 사람이 주도하고 AI가 거듭니다. 코드 한 줄을 자동 완성하거나, 붙여넣은 코드를 설명하거나, 초안을 써 주는 방식입니다. 실행은 사람이 합니다. 에이전트형 도구는 목표를 받으면 여러 단계를 스스로 계획하고 실행합니다. 어떤 파일을 읽을지, 무엇을 고칠지, 고친 뒤 테스트를 돌릴지까지 판단합니다. 공식 문서의 표현을 빌리면 Claude Code는 "코드베이스를 읽고, 파일을 편집하고, 명령을 실행하고, 개발 도구와 통합하는 에이전트 코딩 도구"입니다. 사람이 하던 "복사해서 옮기기"가 사라지는 대신, 사람은 지시와 검증을 맡게 됩니다.

두 방식을 한 표로 두면 차이가 분명해집니다.

에이전트 루프는 어떻게 도나

작업을 주면 Claude Code는 세 단계를 반복합니다. 공식 문서는 이를 컨텍스트 수집, 작업 수행, 결과 검증이라고 부릅니다. 예를 들어 "실패하는 테스트를 고쳐 줘"라고 하면 대략 이런 순서로 움직입니다.

1. 테스트를 실행해서 무엇이 실패하는지 확인합니다.
2. 오류 출력을 읽습니다.
3. 관련 소스 파일을 검색하고 읽어서 코드를 이해합니다.
4. 파일을 편집해 문제를 고칩니다.
5. 테스트를 다시 실행해 고쳐졌는지 검증합니다.

각 단계의 결과가 다음 판단의 재료가 됩니다. 이 루프에 사람도 참여합니다. 도중에 Esc를 눌러 멈추고 방향을 바꾸거나, 추가 정보를 주거나, 다른 접근을 시도하게 할 수 있습니다. 우리가 수업에서 "정지 규칙은 증거"라고 강조하는 이유가 여기 있습니다. 루프의 마지막 단계인 검증에서 실행 화면이나 테스트 출력 같은 증거가 나와야 작업이 끝난 것입니다.

핵심이 되는 5가지 능력

1. 코드 생성

원하는 것을 우리말로 설명하면 여러 파일에 걸쳐 코드를 작성합니다. 교재 3주차의 실습이 좋은 예입니다. "내 폴더의 녹음 파일(m4a)을 텍스트로 변환하고, 회의록 형식(참석자/논의 내용/결정 사항/할 일)으로 정리하는 도구를 만들어 줘. 무료로 쓸 수 있는 방법으로, 한 단계씩 확인받으면서 진행해 줘." 이 한 문단이 지시의 전부이고, 나머지는 Claude Code가 파일을 만들고 실행해서 보여 줍니다. 자세한 지시문 작성법은 코스 뒤쪽 「AI를 활용한 코드 생성」에서 다룹니다.

2. 파일 조작

현재 폴더와 하위 폴더의 파일을 읽고, 새로 만들고, 수정하고, 이름을 바꾸거나 정리합니다. 교재 1주차 실습 2가 바로 이것입니다. 뒤죽박죽인 다운로드 폴더를 두고 "이 폴더의 파일들을 종류별로 분류해서 하위 폴더로 정리해 줘. 옮기기 전에 어떻게 정리할지 계획을 먼저 보여 주고, 내가 승인하면 실행해."라고 지시합니다. 마지막 문장이 중요합니다. 파일을 실제로 옮기는 작업은 되돌리기 어려우므로 계획을 먼저 받아 보는 습관을 첫 시간부터 들입니다.

3. Git 연동

Claude Code는 git과 직접 작동합니다. 변경 사항을 스테이징하고, 커밋 메시지를 쓰고, 브랜치를 만들고, 풀 리퀘스트를 엽니다. 명령어를 외울 필요는 없습니다. "지금까지 작업 커밋하고 푸시해 줘" 한마디면 됩니다. 교재 3주차에서는 깃허브 계정만 있는 초보 상태에서 "계정 연결부터 첫 저장까지 한 단계씩 안내해 줘. 저장소는 반드시 비공개로 만들어 줘"라고 시켜 첫 푸시를 완료합니다. 자세한 흐름은 「Git 조작 자동화」 글에서 7단계로 다룹니다.

4. 외부 도구 연동

MCP(Model Context Protocol)라는 개방형 표준으로 외부 서비스와 연결됩니다. 공식 문서가 드는 예는 Google Drive의 설계 문서 읽기, Jira 티켓 업데이트, Slack 데이터 가져오기입니다. 우리 교육에서는 노션 업로드와 카카오 알림 같은 실제 업무 연결에 씁니다. 단, 처음부터 이것저것 붙이지는 않습니다. 교재 2주차에는 MCP를 "아직 설치 금지"로 두고, 6주차에 필요한 도구만 골라 연결하는 판단력을 따로 배웁니다. 컨텍스트를 아끼는 것도 그 이유 중 하나입니다.

5. Bash 실행

터미널에서 사람이 칠 수 있는 명령은 Claude Code도 실행할 수 있습니다. 빌드, 테스트, 패키지 설치, 스크립트 실행, 서버 기동이 여기 들어갑니다. 공식 문서의 표현대로 "명령줄에서 할 수 있는 것이면 Claude도 할 수 있습니다." 그래서 이 능력에는 승인 절차가 붙습니다. 파일을 지우거나 밖으로 데이터를 보내는 명령도 같은 통로로 나가기 때문입니다. 원구연 강사가 매일 돌리는 자동화 10종도 결국 이 능력 위에 올라가 있습니다.

설치와 첫 실행은 어떻게 하나

공식 문서가 권장하는 방법은 네이티브 설치이며 명령 한 줄입니다. 아래 명령을 직접 타이핑하지 말고 그대로 복사해서 붙여넣습니다.

macOS와 Linux, WSL은 터미널에서 실행합니다.

curl -fsSL https://claude.ai/install.sh | bash

Windows는 시작 메뉴에서 PowerShell을 검색해 실행한 뒤 붙여넣습니다.

irm https://claude.ai/install.ps1 | iex

Windows에서는 Git for Windows 설치를 권장합니다. 공식 문서에 따르면 Git for Windows가 없으면 Claude Code가 Bash 대신 PowerShell을 셸 도구로 씁니다. 나중에 Git 연동도 필요하므로 처음부터 설치해 두는 편이 편합니다. Homebrew를 쓰는 분은 brew install --cask claude-code, WinGet은 winget install Anthropic.ClaudeCode도 가능합니다. 네이티브 설치는 백그라운드에서 자동 업데이트되지만 Homebrew와 WinGet 설치는 자동 업데이트되지 않는다는 점을 기억해 두세요.

설치가 끝나면 확인하고 실행합니다.

claude --version
cd 작업폴더
claude

처음 실행하면 브라우저가 열리며 로그인을 요청합니다. Claude Pro, Max, Team, Enterprise 구독 또는 Anthropic Console 계정으로 로그인할 수 있습니다. 한 번 로그인하면 자격 증명이 저장되어 다시 묻지 않습니다. 교재 1주차의 설치 완료 체크리스트는 두 줄입니다. claude --version에 버전 번호가 나온다, claude 실행 후 로그인이 끝나 프롬프트가 뜬다.

첫 대화는 무엇부터 하나

첫 대화는 "고쳐 달라"가 아니라 "읽어 달라"로 시작하는 것이 좋습니다. Claude Code는 필요한 파일을 알아서 읽으므로 내용을 붙여넣을 필요가 없습니다. 작업 폴더에서 claude를 켠 뒤 이렇게 물어봅니다.

이 폴더에 뭐가 있는지 정리해서 알려 줘
이 프로젝트는 무엇을 하나요? 폴더 구조를 설명해 주세요

교재 1주차 실습 1은 여기서 바로 업무로 들어갑니다. 공고문 파일을 작업 폴더에 넣고 "이 폴더의 공고문을 읽고 지원 대상, 지원 금액, 신청 기간, 제출 서류, 감점·제외 조건을 표로 정리해 줘. 내 고객사(제조업, 매출 10억 미만)가 신청 가능한지도 판단해 줘"라고 지시합니다. 원칙은 하나입니다. 목적과 상황을 먼저 설명하고, 원하는 형태를 구체적으로 지시합니다.

데모: TODO 앱을 한마디로 만들기

빈 폴더를 하나 만들고 claude를 켠 뒤 한 문단을 입력합니다.

브라우저에서 열리는 할 일(TODO) 앱을 만들어 줘.
파일은 index.html 하나로, 할 일 추가·완료 표시·삭제가 되고
새로고침해도 목록이 남아야 해. 만든 뒤 어떻게 여는지 알려 줘.

Claude Code는 파일을 만들기 전에 "index.html을 생성해도 될까요?"와 같은 승인을 요청합니다. 승인하면 파일이 생기고, 마지막에 여는 방법을 알려 줍니다. 브라우저에서 열어 항목을 추가하고 새로고침해 보세요. 목록이 남아 있으면 첫 데모는 성공입니다. 수업에서는 이 실행 화면을 캡처해 두는 것까지 한 세트로 봅니다. "됐다"는 말이 아니라 화면이 증거입니다.

Claude Code가 질문해 오는 이유

Pro·Max·Team 계정의 세션은 auto 모드로 시작합니다. 별도 분류기가 위험한 작업만 골라 "허용할까요?"라고 묻고 나머지는 멈추지 않고 진행합니다. 승인을 하나하나 직접 하고 싶으면 Manual(설정값 default) 모드로 바꾸면 되는데, 이때는 파일을 고치거나 명령을 실행할 때마다 승인을 묻고 요청 없이 실행되는 것은 읽기 작업뿐입니다. Enterprise 계정, API 키 로그인, claude -p 비대화형 실행은 여전히 default로 시작합니다. 이 질문은 버그가 아니라 설계입니다. 에이전트가 사람 대신 실행까지 하기 때문에, 되돌리기 어려운 행동 앞에서 한 번 멈추는 관문을 둔 것입니다.

두 번째 종류의 질문도 있습니다. 지시가 모호하면 "A 방식과 B 방식 중 어느 쪽을 원하시나요?"처럼 되묻습니다. 이때 귀찮다고 "알아서 해"라고 답하면 과하게 추측해서 시키지 않은 기능까지 만들거나 멀쩡한 기능을 건드립니다. 교재 5주차에서 다루듯 결과를 좌우하는 것은 AI가 아니라 지시 방식입니다. 질문이 오면 성실하게 답하는 것이 가장 빠른 길입니다.

알아두면 좋은 안전장치

• 권한 모드: Shift+Tab으로 순환합니다. Manual(default)은 편집과 명령마다 묻고, acceptEdits는 작업 폴더 안의 파일 편집을 자동 승인하며, plan은 파일을 읽고 계획만 세우고 편집하지 않습니다. 승인을 직접 챙기고 싶으면 Manual(default)로 바꾸고, 큰 작업 전에는 plan으로 계획부터 받아 보세요.
• 체크포인트와 되돌리기: Claude Code는 프롬프트마다 파일 상태를 스냅샷합니다. 입력창이 빈 상태에서 Esc를 두 번 누르거나 /rewind를 실행하면 코드와 대화를 이전 지점으로 되돌릴 수 있습니다. 단, rm이나 mv 같은 Bash 명령으로 바뀐 파일은 추적되지 않습니다. 그래서 파일 정리 작업은 계획을 먼저 받는 것입니다.
• Git 백업: 체크포인트는 세션용 실행 취소이고 영구 기록은 Git입니다. 교재 5주차의 원칙을 옮기면 "AI가 잘못 수정한 게 문제가 아니라, 되돌릴 기준점을 안 만든 게 문제입니다." 작업 전 커밋, 작업, QA 통과, 커밋 순서를 습관으로 만듭니다.
• 지침 파일: 프로젝트 루트의 CLAUDE.md는 매 세션 시작 때 읽히는 규칙 파일입니다. 교재 2주차에서 "고객 실명 가리기" 같은 규칙을 첫 장에 적습니다. 도구가 아니라 지침 파일과 검증 게이트로 이루어진 시스템이 우리가 가르치는 것입니다.

연습 문제

1. 내 업무 폴더 하나에서 claude를 켜고 "이 폴더에 뭐가 있는지 정리해서 알려 줘"를 실행해 보세요. 결과에서 틀린 부분이 있는지 확인합니다.
2. 위의 TODO 앱 데모를 그대로 따라 하고, 실행 화면을 캡처해 보관하세요.
3. 내가 매주 반복하는 업무 하나를 골라 교재 1주차의 골격으로 지시해 보세요. "나는 [직무]야. 매주 [반복 업무]를 하는데, 이 폴더의 [재료]를 가지고 그 일을 해 줘. 결과물 형식은 [형식]으로."
4. 작업 중 승인 요청이 몇 번 왔는지, 각각 어떤 행동에 대한 것이었는지 적어 보세요.

정리

• Claude Code는 대답이 아니라 실행까지 맡는 에이전트형 도구이며, 컨텍스트 수집·작업 수행·결과 검증 루프를 돕니다.
• 다섯 가지 능력(코드 생성, 파일 조작, Git, 외부 도구, Bash)은 모두 "내 폴더에서 실제로 일한다"는 한 가지 성격으로 묶입니다.
• 설치는 한 줄, 로그인은 브라우저 한 번입니다. Windows는 Git for Windows를 함께 설치합니다.
• 승인 요청은 안전장치입니다. 계획을 먼저 받고, 되돌릴 기준점(커밋)을 만들고, 증거로 완료를 판정하는 습관이 도구보다 중요합니다.

자주 묻는 질문