도입

냉장고를 열고 재료를 꺼내고, 레시피를 보면서 케이크를 굽는 장면을 떠올려 봅니다. 레시피가 있습니다. 요리사가 있습니다. 밀가루, 달걀, 설탕 같은 재료가 있습니다. 이 세 가지를 잘 분리해 두면 누구라도 같은 케이크를 만들 수 있습니다.

레시피를 바꾸면 다른 케이크가 나오고, 재료를 바꾸면 맛이 달라지고, 요리사가 바뀌어도 레시피만 따르면 비슷한 결과물을 낼 수 있습니다. 클로드 코드에서 에이전트 작업 흐름을 구축하는 구조가 정확히 이 원리를 따릅니다.

케이크 비유: 레시피(워크플로우)와 재료(도구)와 셰프(에이전트)

WAT 프레임워크는 세 글자의 약어입니다. W는 워크플로우(Workflow), A는 에이전트(Agent), T는 도구(Tool)입니다.

워크플로우는 레시피입니다. "이 케이크를 만들려면, 먼저 달걀 두 개를 깨뜨리고, 밀가루 한 컵을 넣고, 180도에서 30분간 굽는다"처럼, 작업의 목표·순서·조건을 자연어로 기술한 문서입니다. 파일 형식은 마크다운(Markdown, .md)이며, 프로그래밍 언어가 아닌 일상적인 문장으로 작성됩니다.

도구는 재료이자 주방 기구입니다. 달걀을 깨뜨리는 행위, 오븐을 예열하는 행위, 반죽을 젓는 행위 — 각각이 하나의 도구입니다. 기술적으로는 파이썬(Python) 스크립트 파일(.py)로 작성되며, API 호출, 데이터 변환, 파일 생성 같은 실제 실행 동작을 담당합니다.

에이전트는 셰프입니다. 클로드 코드 그 자체입니다. 레시피(워크플로우)를 읽고, 필요한 재료(도구)를 골라서, 올바른 순서로 사용합니다. 실행 도중 문제가 생기면 판단을 내립니다. 오븐 온도가 너무 높으면 낮추고, 밀가루가 부족하면 대체 재료를 찾습니다.

핵심은 이 셋이 분리되어 있다는 것입니다. 레시피를 바꾸면 다른 결과물을 만들 수 있고, 도구를 교체하면 같은 레시피로도 다른 서비스에 연결할 수 있으며, 셰프(에이전트)는 어떤 레시피와 도구 조합이든 다룰 수 있습니다.

워크플로우는 마크다운, 도구는 파이썬: 왜 분리하는가

워크플로우 파일 하나를 열어 보면 이런 구조입니다.

# 경쟁사 분석 워크플로우



## 목표

경쟁사 데이터를 수집하고 분석하여 브랜드가 적용된 PDF 보고서를 생성한다.



## 필요 입력

- 회사 정보 (business_profile.json)

- 브랜드 자산 (logo, brand guidelines)



## 사용할 도구

1. discover_competitors.py

2. research_competitors.py

3. analyze_competitors.py

4. generate_report.py



## 예상 출력

- 경쟁사별 프로필 파일

- 분석 결과 요약

- 브랜드 적용 PDF 보고서



## 예외 처리

- 경쟁사 웹사이트 접근 차단 시: 대체 소스 검색

- API 호출 한도 초과 시: 배치 요청으로 전환

일상어로 쓰여 있습니다. 프로그래밍을 모르는 사람도 읽을 수 있습니다. 워크플로우 파일은 에이전트에게 주는 업무 지시서이자, 사람이 검토할 수 있는 문서이기도 합니다.

반면 도구 파일은 파이썬 코드입니다. discover_competitors.py를 열면 API 호출 로직, 데이터 파싱 코드, 오류 처리 루틴이 담겨 있습니다. 이 코드를 직접 읽거나 수정할 필요는 거의 없습니다. 에이전트가 생성하고, 에이전트가 수정합니다. 사용자가 신경 쓸 것은 워크플로우 파일의 내용, 즉 "무엇을 하고 싶은가"입니다.

분리의 이유는 역할 분담에 있습니다. 워크플로우는 "무엇을" 지시하고, 도구는 "어떻게" 실행합니다. 이 둘을 섞어 놓으면, 작업 지시를 바꾸고 싶을 때 코드를 건드려야 하고, 코드를 수정하고 싶을 때 지시 문서가 꼬입니다. 분리되어 있기 때문에, 워크플로우만 수정하여 분석 범위를 바꾸거나, 도구만 교체하여 다른 API를 연결하는 것이 가능합니다.

확률적 추론과 결정적 실행의 분리가 만드는 신뢰성

WAT 프레임워크가 워크플로우와 도구를 나누는 데는 기술적으로 더 깊은 이유가 있습니다. AI 에이전트의 추론은 매번 조금씩 달라질 수 있는 방식입니다. 같은 질문에 대해 매번 약간 다른 답을 내놓을 수 있습니다. 반면 코드의 실행은 같은 입력이면 같은 결과가 나오는 방식입니다. 같은 입력을 주면 항상 같은 출력을 냅니다.

에이전트가 모든 단계를 직접 처리하게 하면, 확률적 추론이 누적되면서 정확도가 급격히 떨어집니다. 한 단계의 정확도가 90%라고 가정해 보겠습니다. 두 단계를 거치면 81%(0.9 × 0.9)입니다. 다섯 단계를 거치면 59%(0.9⁵)로 곤두박질칩니다. 열 단계라면 35%에 불과합니다.

WAT 프레임워크는 이 문제를 해결합니다. 에이전트는 "어떤 도구를 어떤 순서로 사용할 것인가"를 판단하는 역할만 맡습니다. 실제 데이터 처리, API 호출, 파일 생성 같은 실행은 결정적 코드(도구)가 담당합니다. 에이전트의 확률적 판단은 소수의 핵심 결정 지점에만 집중되고, 나머지 실행 과정은 코드가 일관되게 수행합니다. 그 결과, 전체 워크플로우의 신뢰성이 올라갑니다.

5단계 연속 작업의 정확도 함정: 90%가 59%로 떨어지는 이유

이 수학을 좀 더 구체적으로 들여다보겠습니다.

AI 모델에게 이메일을 읽고, 핵심을 요약하고, 카테고리를 분류하고, 우선순위를 매기고, 응답 초안을 작성하게 한다고 합시다. 다섯 단계입니다. 각 단계에서 모델이 올바른 판단을 내릴 확률이 90%라면, 다섯 단계를 모두 올바르게 통과할 확률은 약 59%입니다. 열 번 중 네 번은 어딘가에서 틀린다는 뜻입니다.

이 문제의 해결책이 바로 "관심사의 분리(Separation of Concerns)"입니다. 이메일을 읽는 행위, 텍스트에서 키워드를 추출하는 행위, 카테고리 태그를 붙이는 행위를 각각 독립된 도구로 만듭니다. 각 도구는 결정적으로 동작합니다. 에이전트는 "이 이메일에 대해 분류 도구를 실행하고, 그 결과를 바탕으로 우선순위 도구를 실행해"라는 판단만 내립니다.

판단의 복잡도가 낮아지면서, 전체 정확도가 올라갑니다.

이것이 WAT 프레임워크를 사용하는 실무적 이유입니다. 에이전트에게 "알아서 다 해줘"라고 던지는 것보다, 각 단계를 독립된 도구로 쪼개고 에이전트가 그 도구들을 조합하게 하는 것이 훨씬 안정적인 결과를 냅니다.

자기 개선 루프: 오류에서 배우고 워크플로우를 갱신하는 구조

WAT 프레임워크에는 자기 개선 루프(Self-Improvement Loop)가 내장되어 있습니다. 에이전트가 도구를 실행하다가 오류를 만나면, 오류 메시지를 읽고 원인을 분석합니다. 도구의 코드를 수정합니다. 수정된 도구가 정상 동작하는지 확인합니다. 그런 다음 워크플로우 파일에 "이 상황에서는 이렇게 처리한다"는 예외 처리 항목을 추가합니다.

예를 들어, 경쟁사 웹사이트를 웹 정보 수집하는 도구가 API 호출 한도를 초과했다고 합시다. 에이전트는 오류 메시지에서 "Rate Limit Exceeded"를 읽습니다. API 문서를 검색하여 배치 엔드포인트(Batch Endpoint)가 있는지 확인합니다. 배치 엔드포인트를 발견하면, 도구 코드를 수정하여 배치 요청 방식으로 전환합니다. 수정된 도구를 검증합니다.

정상 동작을 확인한 뒤, 워크플로우 파일에 "API 한도 초과 시 배치 엔드포인트 사용"이라는 항목을 추가합니다.

다음에 같은 워크플로우를 실행하면, 에이전트는 업데이트된 워크플로우를 읽고 처음부터 배치 방식을 사용합니다. 같은 오류를 두 번 겪지 않습니다. 워크플로우를 반복 실행할수록, 예외 처리가 축적되고, 도구의 코드가 다듬어지며, 전체 시스템이 견고해집니다.

파일 구조 설계: workflows, tools, temp 폴더의 역할

에이전트가 만드는 파일이 늘어날수록 정리 체계가 필요합니다. WAT 프레임워크는 세 개의 핵심 폴더를 사용합니다.

workflows/ 폴더에는 워크플로우 파일이 들어갑니다. 경쟁사 분석 워크플로우, 뉴스레터 생성 워크플로우, 리드 웹 정보 수집 워크플로우 — 각각 하나의 마크다운 파일입니다.

tools/ 폴더에는 도구 파일이 들어갑니다. 웹 웹 정보 수집 도구, PDF 생성 도구, 이메일 발송 도구 — 각각 하나의 파이썬 파일입니다.

temp/ 폴더는 임시 파일을 위한 공간입니다. 작업 도중 생성되는 중간 데이터, 디버깅용 로그, 일회성 출력물이 여기에 저장됩니다. 작업이 끝나면 정리해도 되는 파일들입니다.

이 폴더 구조를 에이전트에게 알려주는 것이 claude.md 파일의 역할 중 하나입니다. claude.md에 "워크플로우는 workflows/ 폴더에, 도구는 tools/ 폴더에, 임시 파일은 temp/ 폴더에 저장하라"고 적어 두면, 에이전트는 이 규칙을 따릅니다.

이 파일 없이 작업하면, 에이전트가 모든 파일을 프로젝트 최상위에 무질서하게 쌓아 놓을 수 있습니다. 파일이 늘어날수록 혼란이 커지고, 에이전트도 어떤 도구가 어디 있는지 찾는 데 시간을 낭비합니다.

claude.md 파일을 프로젝트에 넣고 "이 파일을 읽고 프로젝트를 초기화해줘"라고 에이전트에게 말하면, 에이전트가 폴더 구조를 자동으로 생성합니다. 왼쪽 탐색기에 workflows, tools, temp 폴더가 나타나고, 각 폴더 안에 안내 파일(README)이 배치됩니다. 이 초기화 과정은 새로운 프로젝트를 시작할 때마다 한 번만 수행하면 됩니다.

[도표 05-01: WAT 프레임워크 구조도. 에이전트(A)가 워크플로우(W)를 읽고, 도구(T)를 실행하는 삼각 관계. 워크플로우 폴더, 도구 폴더, 임시 폴더의 배치가 표시된다.]

케이크 비유로 돌아가 보겠습니다. 레시피를 잘 정리해 두면 같은 케이크를 언제든 다시 만들 수 있고, 재료만 바꾸면 변형된 케이크를 시도할 수 있습니다. 셰프가 새로운 사람으로 바뀌어도, 레시피를 따르면 비슷한 결과를 낼 수 있습니다. 워크플로우와 도구를 분리해 두는 것이 바로 이 효과를 만듭니다.

그런데 셰프에게 레시피를 건네기 전에, 셰프가 일하는 방식 자체를 설정해 주어야 합니다. 그것이 claude.md의 역할이며, 에이전트의 작업 기억이 어떻게 작동하는지 이해해야 그 설정을 잘 쓸 수 있습니다.