Anthropic 공식에서 배우는 AI 에이전트 설계 20가지 원칙

Anthropic은 에이전트 개발, 컨텍스트 설계, 툴 설계에 관한 지견을 엔지니어링 블로그와 Claude Code의 공식 문서에서 다수 공개하고 있습니다.

이 기사는 그중 설계 판단에 유용한 원칙 20개를 추출하여 짧게 정리한 것입니다. 각 항목은 '주장 + 근거'로만 압축하였으며, 끝부분에 출처를 정리했습니다. 1차 정보를 확인할 때 색인(index)으로 사용해 주세요. 출처는 Anthropic의 엔지니어링 블로그 5개와 Claude Code / 프롬프트 공식 문서 3개입니다.

컨텍스트 엔지니어링 (Context Engineering)

1. 컨텍스트는 유한한 주의 예산(Attention Budget)이다 ─ 추가할수록 정밀도는 저하된다

LLM에는 '주의 예산(attention budget)'이 있어, 토큰을 하나 추가할 때마다 예산이 깎이며 정밀도가 떨어집니다(context rot). 따라서 넣어야 할 정보는 '많을수록 좋다'가 아니라, 최소한의 충분한 양으로 압축해야 합니다. 정보를 넣기 전에 '이 토큰이 정밀도에 기여하는가'를 자문해야 합니다. 단, 필요한 문맥까지 깎아내면 과소 컨텍스트(under-context)라는 반대의 실패를 초래할 수 있습니다.

담보: 내재화됨 (모델의 성질. 원리로서 알고 있으면 됨) -
출처: Effective context engineering for AI agents

2. 문맥은 저스트 인 타임(Just-in-Time)으로 가져온다 ─ 식별자를 유지하고 실행 시점에 로드한다

모든 데이터를 사전에 로드하지 않고, 파일 경로, 저장 쿼리, 링크와 같은 경량 식별자만 유지하다가 툴을 통해 실행 시점에 필요한 만큼만 로드합니다. 사람이 북마크가 필요할 때 페이지를 여는 것과 같은 발상입니다. 사전 로드는 빠르고 예측 가능하지만 사용하지 않는 데이터까지 예산을 소모하며, 저스트 인 타임 방식은 컨텍스트를 절약하지만 실행 시점의 툴 비용과 지연(latency)이 발생합니다.

담보: 내재화됨 (Claude Code는 필요할 때 파일을 읽음. 자체 제작 에이전트라면 구현 측면) -
출처: Effective context engineering for AI agents

3. 코드 실행을 끼워 넣으면 중간 데이터를 모델에 통하지 않고 처리할 수 있다

MCP를 직접적인 툴 호출이 아닌 코드 API로 전달하면, 에이전트는 스스로 코드를 작성하여 실행 환경 내에서 필터링 및 집계(aggregation)를 수행하므로, 중간 결과를 모델의 컨텍스트에 통과시키지 않아도 됩니다. 툴 정의의 온디맨드 로드와 결합하여, 150,000 토큰을 2,000 토큰(98.7% 절감)으로 줄인 사례도 있습니다. 1만 행의 표를 실행 환경에서 압축하면, 모델은 1만 행이 아닌 5행만 보게 됩니다. 중간 데이터가 클수록 효과적입니다.

담보: 정본에 기록 (MCP / 툴의 구현 측면) -
출처: Code execution with MCP

4. 서브 에이전트(Sub-agent)의 가치는 병렬화가 아니라 컨텍스트 오염 방지다

서브 에이전트를 사용하는 첫 번째 이유는 속도(병렬 실행)가 아니라, 메인 대화를 '다시 참조할 필요가 없는 탐색 노이즈'로 채우지 않기 위해서입니다. 별도의 컨텍스트 윈도우(context window)에서 작업하고 요약본만 반환함으로써 유한한 컨텍스트를 보호합니다. 병렬화는 부차적인 효과에 불과합니다. 검색 결과, 로그, 대량의 파일 내용으로 메인 대화가 넘칠 것 같은 부수 작업에 적합합니다.

담보: 내재화됨 (서브 에이전트 메커니즘 존재. 사용 여부 판단은 운영 측면) -
출처: Claude Code best practices

5. 장기 태스크는 컴팩션(Compaction), 메모장, 서브 에이전트를 구분해서 사용한다

컨텍스트 상한을 초과하는 장기 태스크의 지속 전략은 3가지가 있으며, 태스크 특성에 따라 선택합니다. 왕복이 많은 대화에는 컴팩션(이력 요약 압축), 마일스톤이 명확한 반복 개발에는 메모장(외부 메모로 쓰기), 병렬 탐색이 효과적인 조사·분석에는 멀티 에이전트를 사용합니다. 배타적인 것이 아니라, 하나의 장기 태스크 내에서도 국면에 따라 조합하여 사용할 수 있습니다.

담보: 내재화됨 (컴팩션 등을 내장. 구분 사용은 운영 판단) -
출처: Effective context engineering for AI agents

6. 긴 프롬프트는 문서를 앞부분에, 쿼리를 뒷부분에 배치한다

긴 문서나 데이터는 프롬프트 상단에, 지시·쿼리·예시는 그 아래(말미)에 나열합니다. 여러 문서가 포함된 복잡한 입력의 경우, 쿼리를 말미에 두는 것만으로 테스트상 **최대 30%**의 품질 개선이 관찰되었습니다. 말미의 지시를 읽는 시점에 참조해야 할 문서가 이미 문맥에 전개되어 있으므로, 주의(attention)가 '무엇을 해야 하는가'에 집중하기 쉬워집니다.

보증: 원문에 기록(해당 긴 프롬프트의 구성 방식) -
출처: Claude prompting best practices

도구 설계 (ACI)

7. 도구 설계는 프롬프트와 동등한 수준의 일차적 작업이다

에이전트의 정밀도를 결정짓는 병목 지점은 프롬프트 이상으로 도구 정의와 문서, 즉 ACI (agent-computer interface)의 품질이다. Anthropic은 인간용 UI에 투입하는 것만큼의 공수를 ACI에도 투입하라고 설파하며, SWE-bench 에이전트의 경우 "프롬프트 전체보다 도구 최적화에 더 많은 시간을 소비했다"라고 밝힌다. 상대 경로(relative path)로 인해 실수를 반복하던 도구를 절대 경로(absolute path) 필수 방식으로 바꾼 것만으로 완벽하게 작동하게 된 사례도 제시된다. 지침은 "모델의 입장에 서는 것"이다.

보증: 원문에 기록(도구의 구현·정의) -
출처: Building Effective Agents

8. 도구는 API의 1대1 래퍼(wrapper)가 아니라 태스크의 자연스러운 단위로 만든다

기존 API를 '1 도구 = 1 엔드포인트'로 기계적으로 복제하는 것이 아니라, 빈번하게 연쇄되는 여러 조작을 하나의 도구로 묶어 태스크의 자연스러운 단위로 설계한다. list_users, list_events, create_event를 개별적으로 갖추기보다, 빈 시간을 찾아 일정을 잡는 schedule_event를 하나 만드는 식이다. 얇은 래퍼들의 집합은 에이전트에게 불필요한 오케스트레이션(orchestration)과 라운드트립(round-trip)을 강요한다.

보증: 원문에 기록(도구의 구현) -
출처: Writing effective tools for AI agents

9. 도구는 인간이 사용법을 즉시 대답할 수 있는 입도(granularity)로 좁힌다

기능을 너무 많이 집어넣었거나 사용법이 모호한 도구군은 에이전트 실패의 전형적인 원인이다. "어떤 상황에서 어떤 도구를 사용해야 할지 인간 엔지니어가 단정할 수 없다면, AI 에이전트에게 그 이상의 것을 기대할 수 없다". 이 "인간이 즉시 대답할 수 있는가"를 설계 테스트로 삼아, 중복되거나 과도한 도구는 삭제하거나 통합한다.

보증: 원문에 기록(도구의 선정·구현) -
출처: Effective context engineering for AI agents

10. 도구 응답의 식별자는 UUID보다 자연어 이름을 사용한다

도구가 반환하는 ID나 참조는 불투명한 영숫자 조합인 UUID보다 의미 있는 자연어 이름(또는 0부터 시작하는 일련번호)으로 만든다. 가독성 있는 이름으로 해결하면 환각(hallucination)이 줄어들고 검색 태스크의 정밀도가 크게 향상된다. 후속 호출에서 ID를 참조할 때, 인간이 읽을 수 있는 이름이 모델이 혼동할 가능성을 낮추고 존재하지 않는 ID를 날조할 확률을 줄여주기 때문이다.

보증: 원문에 기록(도구의 구현) -
출처: Writing effective tools for AI agents

11. 도구의 에러 응답은 다음 단계를 제시하는 개선 지시로 반환한다

도구가 에러를 반환할 때, 가공되지 않은 에러 코드나 트레이스백(traceback)을 그대로 반환하지 말고, 에이전트가 다음에 취할 수 있는 구체적이고 실행 가능한 수정 사항을 전달한다. 에러 응답 또한 프롬프트의 일부로서 설계 대상이다. "경로는 절대 경로로 지정해 주세요"와 같이 무엇을 어떻게 바꿔야 성공할 수 있는지를 명문으로 반환한다. 디버깅을 위한 상세 스택 트레이스(stack trace)는 인간에게는 유용할지 몰라도 에이전트의 문맥(context)을 오염시킨다.

보증: 원문에 기록(도구의 구현) -
출처: Writing effective tools for AI agents

12. 도구 평가는 수십 번의 호출을 요하는 현실적인 복잡도로 설계한다

도구의 우수성은 너무 단순한 샌드박스가 아니라, 실제 데이터와 서비스에 기반하여 수십 번의 도구 호출을 요하는 복잡한 태스크로 측정해야 한다. 너무 쉬운 평가는 도구를 개선하거나 악화시켜도 결과가 변하지 않아 변경의 효과를 확인할 수 없게 만든다. 평가 태스크의 현실성과 복잡도가 곧 측정의 신뢰도를 결정한다.

보증: 원문에 기록(평가 태스크·테스트) -
출처: Writing effective tools for AI agents

에이전트와 워크플로우의 선택

13. 워크플로우와 에이전트는 서브 태스크를 사전에 특정할 수 있는지에 따라 선택한다

LLM을 포함한 시스템은 처리 경로를 인간이 코드로 사전 정의하는 "워크플로우 (Workflow)"와, LLM이 자신의 프로세스와 도구 사용을 동적으로 결정하는 "에이전트 (Agent)"로 나뉜다. 필요한 서브 태스크를 사전에 예측할 수 있다면 워크플로우를, 할 수 없다면 에이전트를 선택한다. 워크플로우는 예측 가능하고 비용이 낮으며 디버깅하기 쉽지만, 에이전트는 유연한 대신 비용, 레이턴시 (Latency), 불확실성이 증가한다.

담보: 정본에 기록 (아키텍처 설계 판단) -
출처: Building Effective Agents

14. 멀티 에이전트는 병렬 가치가 비용을 상회하는 태스크에만 사용한다

멀티 에이전트는 단일 에이전트보다 몇 배에서 십수 배의 토큰을 소비한다 (자사 데이터 기준, 에이전트는 통상 채팅의 약 4배, 멀티 에이전트는 약 15배). "똑똑하니까 항상 사용한다"가 아니라, 병렬화를 통해 얻는 가치가 비용 증가를 상회하는 태스크에만 할당한다. 독립된 방향을 동시에 탐색하는 너비 우선 (Breadth-first) 조사는 적합하지만, 의존성이 많고 실시간 협업이 필요한 코딩은 적합하지 않다.

담보: CLAUDE.md에 기록 (기동 전 적용하고 싶은 운영 판단) -
출처: How we built our multi-agent research system

프롬프트·지시 방법

15. 규칙 나열보다 다양하고 전형적인 3~5개의 예시로 가르친다

발생 가능한 에지 케이스 (Edge case) 규칙을 끝없이 나열하기보다, 기대하는 동작을 나타내는 다양하고 전형적인 예시를 3~5개 엄선하여 보여주는 것이 더 효과적이다. "예시는 천 마디 말보다 값진 그림"이며, 에지 케이스의 나열을 프롬프트에 채워 넣는 것은 권장되지 않는다. 예시는 전형성 (해당 동작의 대표성을 띠는지)과 다양성 (커버 범위를 넓게 분산시키는지)을 기준으로 선택한다.

담보: CLAUDE.md에 기록 (영구 규칙 / 지시 작성법)
출처: Effective context engineering for AI agents

16. 지시에는 이유를 덧붙이면 규칙 외의 케이스도 일반화한다

금지나 지시에 "왜 그렇게 하는지"를 덧붙이면, Claude가 의도를 이해하여 명시되지 않은 케이스에도 올바르게 일반화 (Generalization)한다. "생략 기호를 사용하지 마라"보다 "TTS 엔진이 읽어주므로 생략 기호를 사용하지 마라 (발음할 수 없기 때문)」가 더 효과적이다. 단순한 규칙은 작성된 사례만 커버하지만, 이유가 포함된 규칙은 기재되지 않은 사례도 포착한다. 단, 이유가 틀렸다면 잘못된 방향으로 일반화한다.

담보: CLAUDE.md에 기록 (영구 규칙 / 지시 작성법)
출처: Claude prompting best practices

Claude Code 운영

17. CLAUDE.md는 문맥(Context)이지 강제 사항이 아니다 ─ 강제는 후크(Hook)로 부여한다

CLAUDE.md의 기술 내용은 Claude가 문맥으로 취급하는 것이지, 강제 설정이 아니다. 판단에 따라 무시될 수 있다. 확실성이 필요한 경계 (삭제, 운영 반영, 비밀 정보 출력 등)는 PreToolUse 후크나 권한을 통해 기계적으로 차단하고, 느슨한 방침 설정 (스타일, 톤, 우선순위)은 CLAUDE.md로 충분하다.

담보: 정본에 기록 (후크·settings 권한) ※ "CLAUDE.md로는 담보할 수 없다"가 요점 -
출처: Claude Code memory

18. CLAUDE.md는 비대해지면 순종도가 떨어진다 ─ 추가보다 삭제

CLAUDE.md는 항상 로드되기 때문에, 길어질수록 컨텍스트를 점유하여 실제 명령에 대한 순종도가 오히려 떨어진다. 각 행에 대해 "이것을 지우면 Claude가 틀리는가"를 자문하고, 아니라면 삭제한다. 목표는 200행 미만이다. 운영의 기본 원칙은 '추가'가 아니라 '삭제'이며, 새로운 요구사항이 들어와도 먼저 삭제할 수 있는 행부터 찾는다.

담보: CLAUDE.md에 기록 (CLAUDE.md 자체의 유지보수 규칙) -
출처: Claude Code best practices

19. 에이전트의 완료 조건은 검증 커맨드의 통과(Pass)로 정의한다

에이전트는 "완료된 것처럼 보이는" 시점에서 멈춘다. 실행 가능한 합불 판정 체크가 없으면 "완료된 것처럼 보임(looks done)이 유일한 시그널이 되어, 당신 자신이 검증 루프가 된다". 테스트나 Stop 후크와 같이 기계적 판정이 가능한 pass/fail로 완료를 외부화하면, 자율 루프가 스스로 돌아간다. 검증이 없는 태스크에는 인간이 매번 성과를 확인해야 하는 숨겨진 검증 비용이 남는다.

담보: 원문에 기록 (테스트·Stop 후크) -
출처: Claude Code best practices

20. 동일한 수정이 2회 반복되면 컨텍스트 (Context)를 리셋하라

1개 세션 내에서 동일한 문제를 2회 초과하여 수정해야 한다면, 문맥 (Context)은 이미 실패한 접근 방식으로 오염된 상태이다. /clear를 실행하여, 학습한 내용(시도했으나 실패한 방침·판명된 제약 사항)을 반영한 더 구체적인 프롬프트 (Prompt)로 재개하라. 좋은 프롬프트로 시작하는 깨끗한 세션은, 수정을 거듭하며 길어진 세션보다 거의 항상 더 나은 결과를 보여준다.

담보: 내재화됨 (인간의 운영 판단. 시스템화는 불필요) -
출처: Claude Code best practices

출처 목록

엔지니어링 블로그 (Engineering Blog)

• Building Effective Agents — https://www.anthropic.com/engineering/building-effective-agents
• Effective context engineering for AI agents — https://www.anthropic.com/engineering/effective-context-engineering-for-ai-agents
• Writing effective tools for AI agents — https://www.anthropic.com/engineering/writing-tools-for-agents
• Code execution with MCP — https://www.anthropic.com/engineering/code-execution-with-mcp
• How we built our multi-agent research system — https://www.anthropic.com/engineering/multi-agent-research-system

공식 문서 (Official Documentation)

• Claude Code best practices — https://docs.anthropic.com/en/docs/claude-code/best-practices
• Claude Code memory — https://docs.anthropic.com/en/docs/claude-code/memory
• Claude prompting best practices — https://docs.anthropic.com/en/docs/build-with-claude/prompt-engineering/claude-prompting-best-practices

Discussion