에이전트 안티패턴 다섯 가지 — Anthropic 인증 시험이 고른 정답은 전부 덜 주는 쪽이다

Claude Certified Architect가 무엇인가

먼저 시험 자체를 짚습니다. Claude Certified Architect는 Anthropic이 내놓은 첫 공식 기술 인증입니다. Foundations 등급의 코드가 CCAR-F이고, 시험은 Pearson VUE가 온라인 감독 또는 시험장에서 치릅니다. 문항은 60개, 시간은 120분, 점수 척도는 100점에서 1,000점이며 합격선은 720점입니다. 자격은 12개월간 유효합니다.

책도 AI 도구도 못 쓰는 폐쇄형 시험이고, 다루는 영역은 에이전트 아키텍처, MCP 연동, Claude Code 워크플로, 프롬프트 엔지니어링, 컨텍스트 관리입니다.

그런데 이 글에서 하려는 이야기는 자격증이 아닙니다. 시험을 볼 생각이 없어도 문제 목록 자체가 쓸모 있다는 쪽입니다. 발표자가 든 이유가 단순합니다. Anthropic은 사람들이 자기 시스템을 실제로 어떻게 쓰는지, 어디서 망가뜨리는지 가장 많이 보고 있는 회사입니다. 그런 회사가 문제를 낸다면 그 문제 목록이 곧 현장에서 터지는 문제 목록입니다.

발표자 본인이 컴퓨터 과학을 30년 넘게 가르쳐 온 사람인데, 학생들에게 「컴퓨터 과학 학위가 취업을 보장해 주지 않는다」고 말해야 하는 처지에서 무엇을 쥐여 줄지 찾다가 이 시험을 만났다고 합니다.

왜 정답이 아니라 오답부터 보나 — 안티패턴 카탈로그

이 발표에는 방법론이 하나 깔려 있습니다. 무엇을 해야 하는지가 아니라 무엇을 하면 안 되는지부터 본다는 것입니다.

근거로 든 것이 1990년대 초 소프트웨어 설계 패턴 운동입니다. 객체지향 프로그래밍이 자리를 잡으면서 「이렇게 하면 된다」는 패턴 카탈로그가 나왔는데, 거의 같은 시기에 「이렇게 하면 안 된다」는 안티패턴 카탈로그가 함께 나왔습니다. 잘하는 법보다 망하는 법의 목록이 실무에서 더 빨리 먹혔기 때문입니다.

지금 필요한 것이 그것이라는 이야기입니다. 에이전트용 안티패턴 카탈로그. 에이전트를 어떻게 잘 만드느냐는 조언은 넘치는데, 무엇을 하면 조용히 망가지는지에 대한 목록은 드뭅니다.

발표자가 인용한 에디슨의 문장이 어울립니다. 「나는 실패한 것이 아니라 안 되는 방법 1만 가지를 찾았을 뿐이다.」 아래 다섯 개가 그 1만 가지 중 자주 밟는 다섯입니다.

배점이 먼저 말해 준다 — 설계가 가장 큰 조각이다

시험 청사진의 다섯 영역과 비중입니다. 아래 숫자는 발표 슬라이드에 적힌 값입니다.

루프가 채워진 시점 — 1966년의 증명

안티패턴으로 들어가기 전에 발표가 1966년으로 한 번 돌아갑니다. 왜 지금 와서 에이전트가 갑자기 다르게 느껴지는지에 대한 설명입니다.

초기 컴퓨팅 시절에는 프로그래밍 언어가 폭발하듯 늘어나며 「내 언어가 네 언어보다 더 많은 걸 할 수 있다」는 싸움이 있었습니다. 1966년 코라도 뵘과 주세페 야코피니가 이 논쟁을 정리했습니다. 어떤 계산이든 세 가지만 있으면 다 할 수 있다는 증명입니다. 순서대로 실행하는 것, 조건에 따라 갈라지는 것, 그리고 반복하는 것.

여기에 지금 AI를 대입해 보면 그림이 선명해집니다. 프롬프트를 한 번 던지고 답을 받는 건 순서입니다. 조건을 걸어 갈라지게 만드는 것까지는 많이들 해 왔습니다. 그런데 루프가 없었습니다. 답을 받아 다시 넣고, 또 받아 다시 넣는 구조 말입니다.

에이전트가 다르게 느껴지기 시작한 데는 모델이 좋아진 몫도 있지만, 구조적으로는 이 세 번째가 채워진 시점입니다. 그래서 첫 번째 안티패턴이 루프에 관한 것입니다.

안티패턴 하나 — 응답을 바로 쓰지 말고 왜 멈췄는지부터 본다

가장 흔한 실수부터 봅니다. 모델을 부르고, 답이 오면, 그 답을 그대로 쓰는 것입니다.

여기서 먼저 풀어야 할 오해가 있습니다. LLM은 툴을 실행하지 못합니다. 확률적으로 다음 단어를 예측하는 것 말고는 아무것도 못 합니다. 툴을 쥐여 줘도 실행은 못 하고, 대신 「이 툴을 이런 값으로 부르면 된다」고 알려 줄 뿐입니다. 실제로 부르는 건 내 코드입니다.

그래서 응답이 오면 답을 바로 쓰는 게 아니라 stop_reason, 즉 모델이 왜 멈췄는지를 먼저 봅니다. tool_use면 툴을 실행해 결과를 다시 넣고 한 바퀴 더 돕니다. end_turn이면 루프를 빠져나옵니다.

그리고 하나 더 있습니다. 토큰이 떨어져서 멈춘 경우에도 응답은 옵니다. 문장도 그럴듯하게 옵니다. 그런데 그건 중간에 잘린 답입니다. stop_reason을 안 보면 완성된 답이라고 생각하고 그대로 씁니다. 조용히 틀리는 자리가 여기입니다.

루프를 빠져나온 뒤가 사람이 개입할 자리이기도 합니다. 확신도를 확인해 괜찮으면 쓰고, 아니면 사람에게 넘깁니다.

while True:
    resp = client.messages.create(
        model="claude-opus-5",
        messages=messages,
        tools=tools,
    )

    # 답을 쓰기 전에 왜 멈췄는지부터 본다
    if resp.stop_reason == "tool_use":
        result = run_tool(resp)          # 툴을 부르는 건 내 코드다
        messages.append(result)          # 결과를 다시 넣고 한 바퀴 더
        continue

    if resp.stop_reason == "max_tokens":
        raise RuntimeError("잘린 답이다 — 완성된 답으로 쓰지 말 것")

    break                                # end_turn 이면 빠져나온다

안티패턴 둘 — 규칙을 한 파일에 몰지 말고 적용되는 자리에 둔다

두 번째는 Claude Code로 코드를 생성할 때의 이야기입니다. CLAUDE.md라는 마크다운 파일에 「알아 두었으면 하는 것」을 적어 두는데, 여기서 흔한 안티패턴이 규칙을 한 파일에 다 몰아넣는 것입니다.

Anthropic이 권하는 것은 계층으로 나눠 두는 쪽입니다. 홈 디렉터리의 CLAUDE.md는 모든 프로젝트에 적용되고, 프로젝트 루트의 CLAUDE.md는 그 저장소에만, 디렉터리별 CLAUDE.md는 그 폴더에서 작업할 때만 적용됩니다. 셋 다 로드돼서 병합되고, 충돌하면 가장 구체적인 파일이 이깁니다.

한 파일에 다 넣으면 특정 폴더에서만 필요한 지침이 상관없는 작업까지 따라옵니다. 그러면 조용히 부딪힙니다. 실패로 드러나는 게 아니라 결과가 미묘하게 어긋나는 형태로 나타나고, 어디서 충돌했는지도 안 보입니다.

이 이야기는 이 사이트에서 한 번 다룬 「Claude가 실제로 따르는 CLAUDE.md는 어떻게 쓰는가」와 이어집니다. 그쪽이 파일 하나를 어떻게 쓰느냐였다면, 여기서는 파일을 어디에 두느냐입니다.

안티패턴 셋 — 툴을 다 붙이지 말고 에이전트를 쪼갠다

세 번째가 에이전트를 여러 개 쓸 때의 이야기입니다. 발표에서 나온 비유가 정확합니다. 집에 목수를 부르는데 배관 공구, 목공 공구, 전기 공구를 전부 들고 나타나서는 「나는 뭐든 할 수 있다」고 합니다. 그 사람을 부르고 싶지는 않을 겁니다. 제대로 된 목수를 원하는 것이지요.

기준선은 슬라이드에 툴 네다섯 개로 적혀 있고, 발표자는 구두로 한두 개라고 말했습니다. 어느 쪽으로 잡든 방향은 같습니다. 그 선을 넘어가면 추론 품질이 떨어지고 툴 선택이 불안정해집니다. 그래서 툴 벨트를 키우는 대신 에이전트를 쪼갭니다. 하나가 한 가지 일만 하게 만드는 것입니다. 함수는 한 가지 일만 해야 한다는 함수형 프로그래밍의 오래된 규칙이 그대로 옮겨 온 셈입니다.

여기에 덧붙는 것이 서브에이전트의 컨텍스트가 메인으로 새어 나오지 않게 하는 일입니다. 컨텍스트는 토큰이고 토큰은 돈인데, 그보다 중요한 건 컨텍스트가 많을수록 모델이 헷갈려서 답이 부정확해진다는 점입니다.

발표에서 가장 인상적인 코드가 크리틱 에이전트였습니다. 앞선 작업 결과를 검증하라고 만든 에이전트인데, 넘기는 것이 주장과 근거 딱 두 개입니다. 그 판단이 나오기까지의 사고 과정은 일부러 뺍니다.

검증하라고 만든 에이전트에게 정보를 덜 주는 것인데, 이유가 그룹싱크였습니다. 여러 에이전트가 모여 서로 이야기하다 보면 하나의 결론으로 수렴해 버립니다. 파티에서 다들 피자를 먹자고 하는데 나만 아닐 때, 분위기를 깨기 싫어 따라가는 것과 같다는 비유였습니다. 에이전트도 그렇게 움직입니다. 그래서 각 에이전트에게 자기 몫의 조각만 줍니다.

안티패턴 넷 — 긴 출력은 떼어내고, 커지면 압축한다

네 번째는 컨텍스트를 무한정 자라게 두는 것입니다.

처방은 둘입니다. 하나는 서브태스크 출력을 격리하는 것입니다. 로그를 전부 뒤져 오류를 찾는 것처럼 출력이 많은 작업은 별도 컨텍스트로 떼어냅니다. 발표에서는 포크(fork)라고 불렀습니다. 장황한 출력은 그 안에만 남고, 메인 대화로는 요약만 돌아옵니다.

다른 하나는 긴 대화를 압축하는 것입니다. 토큰 수를 세다가 기준선을 넘으면 압축을 겁니다. 발표 코드에 적힌 기준선이 15만 토큰이었습니다.

컨텍스트를 아껴야 하는 이유가 두 가지입니다. 컨텍스트는 토큰이고 토큰은 돈이라는 게 하나. 다른 하나는 컨텍스트가 많을수록 모델이 헷갈려서 답이 부정확해진다는 것입니다.

100만 토큰 창이 열렸으니 다 넣어도 되겠다고 생각하기 쉬운데, 반대입니다. 넣을 것을 제한해야 정확해집니다.

안티패턴 다섯 — CI에서는 대화형으로 부르지 않는다

마지막은 파이프라인 안에서 돌릴 때입니다. 안티패턴이 좀 웃깁니다. 에이전트를 대화용으로 부르면 「이걸 해도 될까요?」 하고 권한을 묻는 자리에서 멈춰 서서, 아무도 대답하지 않을 답을 기다립니다. 사람이 없는 자리에서 사람을 기다리는 것입니다.

비대화식 옵션으로 돌리고 출력을 JSON으로 받아야 파이프라인이 읽을 수 있습니다.

여기에 하나 덧붙은 것이 Batch API입니다. 프롬프트와 작업을 배치로 묶어 넘기면 토큰 비용이 절반이고, 결과는 24시간 안에 옵니다. 지금 당장 답이 필요하지 않은 일이라면 그쪽이 맞습니다.

오늘 해 볼 것 하나

다섯 개를 관통하는 것이 하나입니다. 전부 덜 주는 쪽입니다. 툴도, 컨텍스트도, 정보도요.

에이전트를 잘 다룬다는 게 더 많이 붙이는 능력처럼 이야기되는데, 이 시험이 정답으로 고른 건 반대쪽이었습니다. 무엇을 안 줄지 아는 쪽입니다.

오늘 당장 확인할 수 있는 것 하나를 고르라면 세 번째입니다. 지금 쓰고 있는 에이전트나 커스텀 GPT, MCP 설정을 열어 붙어 있는 툴 개수를 세어 보십시오. 네다섯 개를 넘어가면 그중 절반이 한 번도 안 쓰이는 것일 가능성이 큽니다. 그 절반을 떼어내고 같은 일을 시켜 보면 답이 달라집니다.

그다음이 CLAUDE.md입니다. 파일 하나에 스무 줄 넘게 쌓여 있다면, 그중 특정 폴더에서만 필요한 줄을 골라 그 폴더의 CLAUDE.md로 옮깁니다. 지우는 게 아니라 자리를 옮기는 것입니다.