Claude Code AI 에이전트 만들기 — 에이전틱 워크플로와 claude.md 활용법

핵심 메시지

• AI 활용은 '채팅(질문·답변)', '빌딩(지시대로 제작)', '에이전틱(목표만 주면 스스로 수행)'의 세 단계로 나뉜다.
• 에이전틱 워크플로는 과정을 따르고, 스스로 판단하며, 가정하기 전에 먼저 질문한다는 세 가지 특징을 가진다.
• claude.md 파일은 프로젝트 맥락·사용자 정보·규칙·구조를 담아, Claude Code가 시작할 때마다 자동으로 읽는다.
• '계획 모드(plan mode)'는 파일을 바꾸지 않고 먼저 계획을 세우게 해, 만들기 전에 방향을 다듬을 수 있다.
• 워크플로는 코드가 아닌 평문 영어로 작성한 '레시피'이며, 좋은 워크플로가 화려한 도구보다 중요하다.

쉽게 이해하기

Teacher's Tech의 Jamie는 지난 영상에서 Claude Code로 평범한 말만으로 북마크 대시보드 앱을 만들었다. 이번에는 한 걸음 더 나아가 'AI 에이전트'를 만든다. 문장 하나를 입력하자 Claude Code가 스스로 작업을 단계로 쪼개고, 후속 질문을 던지고, 정보를 모아 정리한 뒤 보고서를 만들어 냈다. 지난번이 '시키는 대로 하는' 것이었다면, 이번에는 '스스로 알아서 하도록' 가르치는 것이다. 작업은 터미널보다 편한 VS Code 안에서 진행한다.

에이전틱 워크플로를 이해하려면 세 단계를 비교하면 된다. 1단계 '채팅'은 질문하고 답을 받는 가장 기본적인 사용이다. 2단계 '빌딩'은 만들 것을 구체적으로 지시하면 AI가 코드를 써 주는 단계로, 사용자가 모든 결정을 내린다. 3단계 '에이전틱'은 단계가 아니라 목표를 설명하면 AI가 스스로 계획을 세우고 도구를 고르며, 예상과 다르면 방향을 바꾸고, 확실치 않으면 질문까지 한다. 발표자는 이를 신입을 일일이 관리하는 것과 숙련된 직원을 믿고 맡기는 것의 차이에 비유한다.

무엇이 '에이전틱'을 만드는가는 세 가지로 요약된다. 첫째, 하나의 질문에 답하는 게 아니라 일련의 단계를 거치는 '과정'을 따른다. 둘째, 도중에 발견한 것에 따라 무엇을 할지 '판단'하고, 안 되면 방향을 튼다. 셋째, 마음대로 가정하지 않고 시작 전에 '명확히 하는 질문'을 던진다. 이 질문 단계 하나만으로도 결과물의 질이 크게 좋아진다. 활용처는 여러 출처를 조사해 보고서로 정리하기, 폴더의 파일을 분류하기, 연락처별 맞춤 이메일 작성, 경쟁사 비교표 만들기 등 무궁무진하다.

도구 준비는 간단하다. VS Code를 설치하고 확장 탭에서 Claude Code를 검색해 설치하면 된다. 왼쪽 파일 탐색기에서 에이전트가 만드는 파일이 실시간으로 나타나고, 오른쪽 패널에서 에이전트와 대화한다. 가장 중요한 설정은 claude.md 파일이다. 프로젝트 폴더에 두는 마크다운 문서로, Claude Code가 시작할 때마다 자동으로 읽는다. 프로젝트 맥락, 자기소개(어떤 독자를 위한 콘텐츠인지 등), 규칙(복잡한 작업 전 질문하기, 계획 먼저 보여 주기, 결과는 output 폴더에 저장, 출처 표기 등), 프로젝트 구조를 적는다. 같은 프롬프트라도 claude.md가 있을 때 훨씬 체계적이고 정확한 결과가 나온다.

에이전트를 만들 때는 먼저 'shift+tab'을 두 번 눌러 계획 모드로 들어간다. 이 모드에서는 파일을 바꾸지 않고 계획만 세운다. 목표(예: '주제를 주면 조사해 깔끔한 보고서를 만들고, 시작 전에 범위·독자·원하는 내용을 질문하라')를 설명하면, Claude Code가 스스로 질문 단계·조사 단계·종합 단계·출력 단계로 쪼갠다. 만족스러우면 실행해 워크플로 파일과 보고서를 만든다. 워크플로 파일은 전부 평문 영어라 단계를 추가·삭제하려면 텍스트만 고치면 된다. 발표자는 claude.md 건너뛰기, 모호한 지시, 계획 모드 미사용, 질문 단계 생략, 한 번에 다 만들려 하기를 흔한 실수로 꼽으며, 한 주에 워크플로 하나만 만들어 보라고 제안한다.

주요 인사이트

• AI 활용의 도약은 '무엇을 만들지 지시'하는 단계에서 '목표만 주고 방법은 맡기는' 에이전틱 단계로 넘어갈 때 일어난다.
• 에이전틱의 핵심은 '가정하기 전에 질문하기'이며, 이 질문 단계 하나만으로도 결과물 품질이 크게 올라간다.
• claude.md는 새 직원에게 주는 온보딩 문서 같아서, 2분의 설정이 이후 수많은 반복 설명을 줄여 준다.
• 계획 모드(plan mode)로 만들기 전에 방향을 다듬으면, 잘못된 길로 가서 시간을 낭비할 위험을 줄일 수 있다.
• 화려한 플러그인보다 잘 쓴 워크플로가 더 강력하며, 웹 검색·파일 읽기/쓰기 같은 기본 도구만으로도 충분하다.

자주 묻는 질문

관련 AI 소식