Claude Code로 첫 번째 AI 에이전트를 직접 구축하는 방법 (완전 초보자용 강좌)

Claude Code 를 설치하고, 처음부터 첫 번째 에이전트를 작성하고, 실제로 동작하는 무언가를 만드는 방법을 배우세요: 코딩 경험 없이도 폴더를 읽고, 문제를 찾고, 보고서를 작성하는 작동하는 에이전트입니다.

챗봇은 사용자가 질문하기를 기다렸다가 답변합니다. AI 에이전트는 다릅니다: 목표를 주면 스스로 단계를 파악하고, 파일을 읽고, 명령을 실행하고, 작업이 완료될 때까지 스스로 행동합니다. 모든 움직임을 직접 주도하는 것이 아닙니다. 목적지를 설정하는 것입니다.

이 차이는 자동화할 수 있는 대상을 바꾸기 때문에 중요합니다. 한 번에 하나씩 프롬프트를 입력하는 것이 아닙니다. 다른 곳에 집중하는 동안 작업을 수행하는 무언가를 구축하는 것입니다.

시작하기 전에 필요한 것

명령어를 하나도 입력하기 전에 필요한 모든 것은 다음과 같습니다:

• 유료 플랜 (Pro 최소 $20/월, Claude Code 포함) 이 있는 Claude 계정

• macOS 13 이상을 실행하는 Mac, Windows PC, 또는 Linux 머신

• 인터넷 연결

• 전체 설정 및 첫 번째 빌드에 약 30 ~45 분

코딩 경험이 필요하지 않습니다. 이 가이드의 모든 명령어는 전체가 작성되어 있습니다. 복사하고, 붙여넣고, Enter 키를 누르기만 하면 됩니다.

이 가이드를 따르는 비용: 구독 외에 $0. Claude Code 는 모든 유료 Claude 플랜에 포함되어 있습니다.

Claude Code 설치 (데스크톱 앱 방식, 터미널 불필요)

초보자에게 가장 쉬운 방법은 데스크톱 앱입니다. 터미널 명령어를 먼저 배울 필요 없이 Claude Code 의 모든 기능을 제공합니다.

claude.ai 로 이동하여 플랫폼에 맞는 데스크톱 앱을 다운로드하세요. macOS 에서는 .dmg 파일을 열고 Claude 를 응용 프로그램 폴더로 드래그하세요. Windows 에서는 설치 프로그램을 실행하세요. 앱을 실행하고 Claude 계정으로 로그인한 후 화면 상단 중앙의 Code 탭을 클릭하세요.

Code 탭에서 플랜 업그레이드를 요청하면 현재 플랜에 Claude Code 가 포함되지 않은 것입니다. 온라인 로그인을 요청하면 로그인을 완료하고 앱을 다시 시작하세요. 어느 경우든, 일단 들어가면 깔끔한 작업 공간이 나타납니다.

성공적인 모습: 오류 메시지 없이 Code 탭이 활성화된 빈 프롬프트 상자가 보입니다. 이것이 에이전트 작업 공간입니다. 구축하는 모든 것이 여기에 있습니다.

구축할 내용

하나의 특정 에이전트를 구축하고, 이 가이드 내내 사용할 것입니다.

에이전트의 임무: 텍스트 파일 폴더를 읽고, 상단에 제목 줄이 누락된 파일을 찾은 다음, 수정이 필요한 모든 파일을 나열한 missing-titles.txt 라는 보고서를 작성합니다.

이것은 실제로 유용한 작업입니다. 모든 핵심 에이전트 동작 (파일 읽기, 결정 내리기, 출력 작성) 을 보여줍니다. 그리고 작동할 때 눈으로 확인할 수 있을 정도로 간단합니다.

1 단계: 작업 폴더 생성

바탕 화면에 my-agent 라는 새 폴더를 만듭니다. 이것은 에이전트가 작업할 곳입니다. 이 폴더 안의 파일만 보고 조작할 수 있어 모든 것이 안전하게 유지됩니다.

my-agent 안에 articles 라는 두 번째 폴더를 만듭니다. 에이전트가 확인할 파일을 찾는 곳입니다.

이제 articles 안에 4 개의 일반 텍스트 파일을 만듭니다. 이름을 post-one.txt, post-two.txt, post-three.txt, post-four.txt 로 지정합니다. 그중 2 개를 열고 맨 첫 줄에 다음을 추가합니다:

1Title: My Article

나머지 2 개의 파일은 완전히 비워 둡니다. 에이전트의 임무는 빈 파일을 찾는 것입니다.

성공적인 모습: 폴더 구조가 my-agent/articles/ 이고, 4 개의 .txt 파일이 있으며, 2 개는 제목 줄이 있고 2 개는 없습니다.

2 단계: CLAUDE.md 지시 파일 작성

CLAUDE.md 는 Claude Code 가 모든 세션 시작 시 읽는 일반 텍스트 파일입니다. 에이전트의 상시 지시사항이며, 절대 잊지 않는 직무 설명서와 같습니다.

my-agent 폴더 (articles 안이 아님) 안에 CLAUDE.md 라는 새 파일을 만듭니다. Windows 의 메모장이나 Mac 의 TextEdit 등 텍스트 편집기에서 열고 다음을 정확히 붙여넣습니다:

1# 내 파일 검사기 에이전트
2
3## 당신의 임무
4
5/articles 폴더 안의 모든 .txt 파일을 확인합니다.
6
7## 확인할 사항
8
9유효한 파일은 정확히 다음 줄로 시작합니다: Title:
10
11첫 번째 줄이 "Title:"로 시작하지 않으면 해당 파일에 제목이 없는 것입니다.
12
13## 수행할 작업
14
151. /articles 폴더의 모든 .txt 파일을 하나씩 읽습니다.
16
171. Title 줄이 누락된 파일을 기록합니다.
18
191. 기본 폴더에 missing-titles.txt라는 파일을 작성합니다.
20
211. 해당 파일에 검사에 실패한 모든 파일 이름을 한 줄에 하나씩 나열합니다.
22
231. 모든 파일이 통과하면 missing-titles.txt에 "All files have titles." 대신 작성합니다.
24
25## 하지 말아야 할 것
26
27기사 파일을 편집하지 마십시오. 읽기만 합니다. missing-titles.txt에만 작성합니다.

파일을 저장합니다. 이것이 에이전트의 전체 두뇌입니다. Claude Code 는 아무 작업을 하기 전에 이 파일을 읽습니다.

성공적인 모습: my-agent/CLAUDE.md 에 파일이 있고 위의 지시사항이 포함되어 있습니다.

3 단계: Claude Code 를 폴더에 연결

Claude Code 데스크톱 앱을 열고 폴더 아이콘 또는 "Open folder" 옵션을 클릭하여 my-agent 폴더로 이동합니다. 선택하고 확인합니다.

Claude Code 가 자동으로 CLAUDE.md 파일을 읽습니다. 이에 대한 확인 메시지는 표시되지 않으며, 폴더를 열 때마다 백그라운드에서 자동으로 수행됩니다.

데스크톱 앱 대신 터미널을 사용하는 경우 터미널을 열고 다음을 실행하세요:

1cd ~/Desktop/my-agent
2claude

cd 명령어는 "change directory" 를 의미합니다. my-agent 폴더로 이동합니다. claude 를 입력하면 해당 폴더 내에서 에이전트 세션이 시작됩니다.

4 단계: 에이전트 실행

Claude Code 인터페이스 하단의 프롬프트 상자에 다음을 정확히 입력합니다:

1articles 폴더의 모든 .txt 파일을 읽습니다. 상단에 Title 줄이 누락된 파일을 찾습니다. CLAUDE.md에 지시된 대로 결과를 missing-titles.txt에 작성합니다.

Enter 키를 누릅니다. 어떤 일이 일어나는지 지켜보세요.

Claude Code 가 실행되는 동안 작업 내용을 표시합니다: 읽고 있는 파일, 각 파일에서 발견한 내용, 작성하는 내용을 보여줍니다. 이러한 투명성은 의도적입니다. 모든 작업을 실행 전에 확인하고 잘못된 것이 있으면 중지할 수 있습니다.

성공적인 모습: Claude 가 4 개의 파일을 읽고, 제목이 없는 2 개를 식별하고, my-agent 폴더에 missing-titles.txt 를 생성합니다. 해당 파일을 열면 2 개의 파일 이름이 한 줄에 하나씩 나열되어 있어야 합니다.

초보자 흔한 실수: 에이전트가 완료되었다고 하지만 파일이 비어 있음

에이전트가 missing-titles.txt 를 작성했지만 실제로 아무 내용도 넣지 않을 때 발생합니다. 원인은 거의 항상 지나치게 모호한 CLAUDE.md 지시사항입니다.

해결 방법: CLAUDE.md 를 열고 출력 지시사항을 더 명확하게 만듭니다. "파일을 나열하세요" 대신 "각 파일 이름을 자체 줄에 작성하세요 (예: post-two.txt)." 지시사항에 구체적인 예를 포함하면 매번 구체적인 출력이 생성됩니다.

에이전트가 잘못된 파일 이름을 작성하거나 하나를 놓친 경우, 기사 파일에 실제로 .txt 확장자가 있고 .txt.txt 가 아닌지 확인하세요. Windows 에서 파일 확장자가 숨겨져 있을 때 이런 일이 발생할 수 있습니다. 파일 탐색기 설정에서 "파일 확장명 표시" 를 켜서 확인하세요.

5 단계: 확인 및 확장

missing-titles.txt 를 열고 비워 둔 정확히 2 개의 파일이 나열되어 있는지 확인합니다. 그렇다면 에이전트가 처음부터 끝까지 올바르게 작동한 것입니다.

이제 작동하는 에이전트가 생겼습니다. my-agent 에 있으며, CLAUDE.md 에서 지시를 읽고, articles 폴더에 새 파일을 넣고 동일한 프롬프트를 실행할 때마다 실행할 수 있습니다.

명확한 다음 단계: CLAUDE.md 를 업데이트하여 각 파일이 5 줄보다 긴지도 확인하도록 합니다. "확인할 사항" 아래에 다음을 추가합니다:

1유효한 파일은 또한 5줄 이상의 내용을 가져야 합니다.
2
3파일이 5줄 이하인 경우 제목 확인과 함께 "너무 짧음"으로 표시합니다.

동일한 프롬프트로 에이전트를 다시 실행합니다. 이제 프롬프트는 변경하지 않고 지시 파일만 변경하여 한 가지 대신 두 가지를 확인합니다.

방금 구축한 내용과 그 중요성

각 단계를 감독하지 않고도 파일을 읽고, 결정을 내리고, 출력을 작성하는 에이전트를 구축했습니다. 이것은 앞으로 구축할 모든 고급 에이전트의 핵심 패턴입니다.

CLAUDE.md 파일이 확장되는 부분입니다. 새로운 규칙, 새로운 검사, 새로운 출력 형식을 추가하면 실행 방식을 변경하지 않고도 에이전트의 동작이 변경됩니다. 프롬프트는 동일하게 유지되고 지시사항이 발전합니다.

여기서 자연스러운 확장은: 더 많은 파일 형식 확인, CSV 와 같은 다른 형식으로 보고서 작성, 또는 Claude Code 의 내장 Routines 기능을 사용하여 정기적으로 검사 실행입니다.

단계에 대해 질문이 있습니까? 아래에 남겨주세요.