Claude 에이전트 입문 1: AI는 어떻게 일을 끝낼까

Claude 에이전트 입문 · 1/5 · 공식 문서 확인: 2026년 9월 20일

AI 에이전트는 자료를 읽고 도구를 실행하며, 그 결과를 보고 다음 행동을 고르는 시스템입니다. 이해하려면 ‘어떤 모델인가’와 함께 입력 자료, 사용할 도구, 완료 조건을 봐야 합니다. 이 글에서는 실제 파일 하나를 주고 초안을 만드는 과정을 따라갑니다.

실습 환경은 Claude Code입니다. Claude 모델을 이용해 작업 폴더의 파일을 읽거나 수정하는 프로그램입니다. 일반 채팅창에 답변이 나타나는 것과 내 컴퓨터에 파일이 저장되는 것은 서로 다른 결과입니다. 아래 행사 정보는 연습용으로 만든 가상 자료입니다.

모델의 판단과 도구의 실행은 어떻게 연결될까

자료 확인 → 실행 → 검사. 부족한 부분이 있으면 다음 행동을 고르고, 완료 기준을 충족하면 마칩니다.

사용자가 목표를 주면 Claude는 현재 가진 정보로 답할지, 파일을 더 읽을지, 도구를 호출할지 판단합니다. 도구 호출이 허용되면 실행 환경이 처리하고 결과를 돌려줍니다. 파일을 못 찾았다는 오류도 다음 판단의 입력이 됩니다. 이 과정을 반복하다가 응답하거나, 확인을 요청하거나, 작업을 마칩니다. 공식 문서: Claude Code의 작동 과정

구성 요소	실제 역할	확인할 증거
모델	필요한 정보와 다음 행동을 선택	왜 그 파일이나 작업이 필요한지
도구	파일 읽기·저장 같은 행동 실행	읽은 내용, 저장 경로, 오류
실행 환경	도구 호출과 권한을 처리	실행 성공·거절·승인 요청
검사 기준	결과가 요청을 충족했는지 판단	원본과 최종 파일의 대조

‘작성했습니다’라는 문장만으로 저장 여부를 알 수는 없습니다. 파일 생성 도구를 호출했는지, 저장에 성공했는지, 최종 파일에 요청한 내용이 있는지까지 이어서 봐야 합니다.

파일 하나로 직접 확인하는 첫 작업

목표·자료·도구·완료 기준을 함께 정하면, 무엇을 만들어 어디까지 확인할지 분명해집니다.

Claude Code에서 작업할 폴더에 event.txt라는 텍스트 파일을 만들고 다음 내용을 넣습니다. 신청 방법은 일부러 확정하지 않았습니다.

행사명: 작은 책방 북토크
일시: 2026-10-03 19:00
장소: 작은 책방 2층
정원: 20명
신청 방법: 미정

그 폴더에서 Claude Code에 아래처럼 요청합니다. 첫 요청은 읽기·초안 저장·검사의 범위가 모두 드러나야 합니다.

event.txt를 읽고 announcement.md에 안내문 초안을 작성해줘.
행사명, 일시, 장소, 정원은 원본과 같아야 해.
신청 방법은 추측하지 말고 '확인 필요'로 표시해.
작성이 끝나면 저장된 파일을 다시 읽고 원본과 대조해줘.
외부로 발송하지 말고, 저장 경로와 미확정 항목을 보고해줘.

기대하는 결과는 announcement.md 파일, 원본과 같은 일시·장소·정원, ‘신청 방법 확인 필요’ 표시입니다. AI가 임의의 신청 링크를 넣었다면 초안은 만들어졌어도 요구사항 검사에는 실패한 것입니다.

이 요청은 목표만 전달하는 방식보다 실패 지점을 찾기 쉽습니다. 자료를 잘못 읽었는지, 파일을 못 썼는지, 없는 정보를 만들어냈는지를 각각 확인할 수 있습니다.

계획 모드와 일반 자동화는 언제 쓸까

미리 정한 자동화도 조건에 따라 분기할 수 있습니다. 에이전트는 결과를 읽고 AI가 다음 행동을 선택합니다.

수정 범위를 먼저 검토하고 싶다면 Plan mode를 사용합니다. Claude Code는 자료를 읽고 계획을 제안하며, 승인 전에는 파일 편집을 진행하지 않습니다. 터미널에서는 claude --permission-mode plan으로 시작할 수 있습니다. 위 실습을 계획 모드에서 시작했다면 계획을 검토하고 실행을 승인하는 단계가 필요합니다. 공식 문서: 편집 전 계획

에이전트가 필요한지도 별도로 판단하세요. ‘날짜가 비었으면 알림 보내기’처럼 조건과 처리 순서를 미리 정할 수 있는 일은 일반 자동화로 구현할 수 있습니다. 자료를 해석한 뒤 무엇을 더 조사할지 모델이 선택하게 할 때 에이전트 구성이 유용합니다. 두 방식은 한 작업 안에서 함께 쓸 수도 있습니다. 공식 설계 원리·2024년 글

실패했을 때 먼저 확인할 것

증상	확인할 대상
파일을 못 찾음	실행한 폴더, 파일 이름과 경로
답변은 있지만 저장 파일이 없음	계획 모드 여부, 저장 도구의 실행·권한 결과
없는 신청 링크를 생성함	미확정 정보의 처리 지시와 결과 검사
같은 작업을 계속 반복함	완료 조건, 반복되는 오류, 중단 기준

첫 실습에서는 최종 파일을 직접 열어 원본과 비교해보세요. ‘AI가 그럴듯하게 설명했는가’보다 내가 준 자료가 실제 결과에 정확히 반영됐는가를 확인하는 습관이 다음 단계의 출발점입니다.

시리즈 이어 읽기

다음 편 →