시스템 프롬프트·도구·예시 설계

확인 날짜 안내

확인 날짜가 섞인 페이지다. 기본은 효과적인 컨텍스트 엔지니어링(2025-09-29) 기준이고, "도구를 프롬프트처럼 다듬기(ACI)" 절은 효과적인 에이전트 만들기(2024년 글)에서 왔다. 두 글 부분은 설계 원칙·권고라 특정 도구 버전에 묶이지 않아 날짜 계산에서 뺀다. 변하는 사실은 "Claude Code에서는 외부 도구가 MCP 서버로 들어온다" 한 문장(Claude Code 확장 기능 개요, 공식 문서, 수집 2026-10-18)뿐이므로 페이지 확인 날짜는 2026-10-18이다.

컨텍스트 엔지니어링의 지침 원칙("원하는 결과의 가능성을 최대로 높이는 가장 작은 고신호 토큰 집합")을 컨텍스트 구성 요소별로 적용하는 방법이다. 효과적인 컨텍스트 엔지니어링

1. 시스템 프롬프트: 적정 고도로 쓴다#

시스템 프롬프트(용어 사전)는 아주 분명하고 단순하고 직접적인 언어로, 에이전트에게 맞는 "고도(altitude)"에서 써야 한다. 적정 고도는 흔한 두 실패 사이의 골디락스 구간이다. 효과적인 컨텍스트 엔지니어링

적정 고도는 행동을 효과적으로 이끌 만큼 구체적이면서, 모델에게 강한 휴리스틱을 줄 만큼 유연하다. 효과적인 컨텍스트 엔지니어링

단계#

1. 쓸 수 있는 가장 좋은 모델로 최소한의 프롬프트를 먼저 시험한다. 효과적인 컨텍스트 엔지니어링
2. 첫 시험에서 드러난 실패 유형을 보고, 분명한 지시와 예시를 더해 성능을 올린다. 효과적인 컨텍스트 엔지니어링
3. 프롬프트를 구분된 섹션으로 나눈다. 원본이 든 섹션 이름 예: <background_information>, <instructions>, ## Tool guidance, ## Output description. XML 태그나 마크다운 제목으로 구분한다. 다만 원본은 모델이 좋아질수록 정확한 형식은 덜 중요해지고 있을 가능성이 높다고 덧붙인다. 효과적인 컨텍스트 엔지니어링
4. 기대하는 행동을 온전히 설명하는 최소한의 정보를 목표로 한다. 최소가 꼭 짧다는 뜻은 아니다. 원하는 행동을 지키게 할 만큼 충분한 정보는 처음부터 줘야 한다. 효과적인 컨텍스트 엔지니어링

2. 도구: 겹치지 않는 최소 세트로#

도구는 에이전트와 정보·행동 공간 사이의 계약이다. 그래서 토큰 효율적인 정보를 돌려주고, 효율적인 에이전트 행동을 유도해야 한다. 효과적인 컨텍스트 엔지니어링

• 잘 설계된 코드베이스의 함수처럼 스스로 완결되고, 오류에 강하고, 용도가 아주 분명해야 한다. 효과적인 컨텍스트 엔지니어링
• 입력 파라미터도 설명적이고 모호하지 않으며 모델의 강점을 살려야 한다. 효과적인 컨텍스트 엔지니어링
• 가장 흔한 실패는 비대한 도구 세트다. 기능을 너무 많이 덮거나, 어떤 도구를 쓸지 모호한 결정 지점을 만든다. 원본의 판단 기준: 사람 엔지니어가 어떤 상황에 어떤 도구를 써야 할지 확실히 말하지 못하면, AI 에이전트가 더 잘하길 기대할 수 없다. 효과적인 컨텍스트 엔지니어링
• 최소한의 실용 도구 세트를 고르면 긴 상호작용에서 컨텍스트를 유지·정리하기도 더 쉬워질 수 있다. 효과적인 컨텍스트 엔지니어링

도구를 프롬프트처럼 다듬기: 에이전트-컴퓨터 인터페이스(ACI) (2024년 글)#

Anthropic의 에이전트 설계 글은 도구 정의와 명세에도 전체 프롬프트만큼의 프롬프트 엔지니어링 주의를 기울이라고 한다. 어떤 에이전트형 시스템을 만들든 도구는 에이전트의 중요한 부분이 될 가능성이 높기 때문이다. 효과적인 에이전트 만들기 → 워크플로와 에이전트

형식 고르기. 같은 동작을 표현하는 방법은 여럿이다(파일 편집을 diff로 쓰기 vs 파일 전체를 다시 쓰기, 구조화된 출력을 마크다운 안에 vs JSON 안에). 소프트웨어 공학에서는 손실 없이 바꿀 수 있는 겉모양 차이지만, LLM에게는 어떤 형식이 훨씬 쓰기 어렵다. diff는 새 코드를 쓰기 전에 청크 헤더에 바뀌는 줄 수를 알아야 하고, JSON 안의 코드는 줄바꿈과 따옴표를 추가로 이스케이프해야 한다. 원본의 제안: 효과적인 에이전트 만들기

• 모델이 스스로 궁지에 몰리기 전에 "생각"할 토큰을 충분히 준다.
• 형식을 모델이 인터넷 텍스트에서 자연스럽게 본 것에 가깝게 둔다.
• 수천 줄 코드의 줄 수를 정확히 세거나, 쓰는 코드를 모두 문자열 이스케이프해야 하는 형식상 "부담"을 없앤다.

ACI에 HCI만큼 공들이기. 원본의 경험칙: 사람-컴퓨터 인터페이스(HCI)에 들이는 노력만큼 에이전트-컴퓨터 인터페이스(ACI)에도 투자할 계획을 세운다. 방법: 효과적인 에이전트 만들기

1. 모델 입장이 되어 본다. 설명과 파라미터만 보고 도구 쓰는 법이 분명한가, 아니면 곰곰이 생각해야 하는가? 후자라면 모델에게도 그럴 것이다. 좋은 도구 정의에는 흔히 사용 예시, 엣지 케이스, 입력 형식 요건, 다른 도구와의 분명한 경계가 들어간다.
2. 파라미터 이름이나 설명을 어떻게 바꾸면 더 분명해질지 생각한다. 팀의 주니어 개발자에게 줄 훌륭한 docstring을 쓴다고 생각한다. 비슷한 도구를 많이 쓸 때 특히 중요하다.
3. 모델이 도구를 어떻게 쓰는지 시험한다. 워크벤치에서 예시 입력을 많이 돌려 모델이 어떤 실수를 하는지 보고 반복한다.
4. 도구를 포카요케(Poka-yoke)한다. 실수하기 더 어렵게 인자를 바꾼다.

원본 사례: SWE-bench용 에이전트를 만들 때 Anthropic은 전체 프롬프트보다 도구 최적화에 더 많은 시간을 썼다. 에이전트가 루트 디렉터리 밖으로 옮겨 간 뒤 상대 경로를 쓰는 도구에서 모델이 실수하자, 도구가 항상 절대 경로를 요구하도록 바꿨고 모델은 이 방식을 흠 없이 썼다. 효과적인 에이전트 만들기

편집자 해석: 위 1번의 "다른 도구와의 분명한 경계"는 같은 절 위쪽의 컨텍스트 엔지니어링 글이 말한 "사람 엔지니어도 어떤 도구를 쓸지 확실히 말하지 못하면 에이전트도 못 한다"는 기준과 같은 방향으로 볼 수 있다. 근거는 두 원본의 해당 문장이다. 효과적인 컨텍스트 엔지니어링, 효과적인 에이전트 만들기

Claude Code에서는 외부 도구가 MCP 서버로 들어온다(Claude Code 확장 기능 개요). 도구가 컨텍스트를 얼마나 차지하는지는 컨텍스트 비용을 본다.

3. 예시: 엣지 케이스 목록 대신 대표 예시#

• few-shot 프롬프팅(예시 주기)은 원본이 계속 강하게 권하는 모범 사례다. 효과적인 컨텍스트 엔지니어링
• 권하지 않는 것: LLM이 따라야 할 모든 규칙을 말하려고 엣지 케이스를 줄줄이 프롬프트에 채워 넣기. 효과적인 컨텍스트 엔지니어링
• 권하는 것: 에이전트의 기대 행동을 효과적으로 보여 주는 다양하고 대표적인(canonical) 예시를 골라 담기. 원본 표현으로 LLM에게 예시는 천 마디 말만 한 "그림"이다. 효과적인 컨텍스트 엔지니어링

언제 쓰고 언제 쓰지 않는가#

• 쓴다: 에이전트의 시스템 프롬프트, 도구, 예시를 새로 짜거나 손볼 때. 어떤 패턴(워크플로·에이전트)으로 만들지부터 정해야 하면 에이전트 시스템 패턴 고르기를 먼저 본다. Claude Code 사용자라면 메모리(CLAUDE.md)나 스킬을 쓸 때 참고할 수 있다(편집자 연결. 원본은 CLAUDE.md를 시스템 프롬프트로 부르지 않는다).
• 쓰지 않는다: 원본은 이 원칙을 쓰지 말아야 할 경우를 들지 않는다. 대신 정확한 프롬프트 형식은 모델이 좋아질수록 덜 중요해지고 있을 가능성이 높다고 본다. 효과적인 컨텍스트 엔지니어링