앤트로픽 에이전트 가이드 8편, 업무에 바로 쓸 원칙만 정리

먼저 결론

• 단순하게 시작하고, 필요할 때만 복잡하게 만듭니다.
• 도구와 지침은 신입 직원에게 설명하듯 쓰고, 맥락(컨텍스트)은 아껴 써야 하는 자원으로 봅니다.
• 테스트, 결과 비교, 화면 캡처처럼 스스로 확인할 방법을 줍니다.
• 작은 평가 세트로 시작해 계속 고칩니다.

1. 순서가 정해진 일은 워크플로로 충분하다

앤트로픽은 AI 시스템을 두 가지로 나눕니다. 워크플로(workflow)는 미리 정한 순서에 따라 AI와 도구를 연결한 것입니다. 에이전트(agent)는 AI가 스스로 다음 단계와 쓸 도구를 정하는 것입니다.

에이전트는 유연하지만 시간과 비용이 더 들고, 실수가 쌓일 수 있습니다. 그래서 첫 조언은 가장 단순한 방법으로 시작하라는 것입니다. 결과가 확실히 좋아질 때만 복잡하게 만듭니다.

자주 쓰는 구성은 다섯 가지입니다.

에이전트를 만들 때 지킬 원칙은 세 가지입니다. 단순하게, 계획을 보이게, 도구 설명을 꼼꼼하게.

2. 도구는 많을수록 좋아지지 않는다

에이전트가 쓰는 도구는 메일 보내기, 파일 검색, DB 조회 같은 것입니다. 시스템 기능을 하나씩 다 도구로 만들기보다, 자주 하는 일을 묶은 도구 몇 개가 낫습니다. 예를 들어 "일정 목록 보기"와 "일정 만들기"를 따로 두기보다 "일정 잡기" 하나로 둡니다.

이름은 분명하게 나눕니다. 서비스·대상별로 이름 앞부분을 맞추면(예: asana_projects_search) 에이전트가 고르기 쉽습니다.

결과는 사람이 읽을 수 있게 돌려줍니다. 알아보기 어려운 내부 번호보다 이름과 핵심 값을 줍니다. "간단히 / 자세히"를 고를 수 있으면 더 좋습니다.

결과 양도 조절합니다. 페이지 나누기, 걸러 내기, 잘라 내기를 기본값으로 둡니다. 오류 메시지는 무엇을 고치면 되는지 알려 줘야 합니다.

도구 설명은 신입 직원에게 설명하듯 씁니다. 원문은 도구 설명을 조금만 다듬어도 결과가 크게 좋아질 수 있다고 강조합니다.

고치는 방법은 평가입니다. 실제와 비슷한 여러 단계짜리 과제를 돌려 보고 대화 기록을 읽습니다. 그 기록을 다시 에이전트에게 분석시켜 도구를 고칩니다.

3. 맥락은 적고 중요한 정보만 넣는다

앤트로픽은 AI가 일하는 동안 보는 정보 전체를 관리하는 일을 컨텍스트 엔지니어링이라고 부릅니다. "프롬프트를 잘 쓰는 것"보다 넓은 개념입니다.

AI가 한 번에 볼 수 있는 정보에는 한계가 있습니다. 많이 넣을수록 앞의 내용을 정확히 기억하는 능력이 떨어집니다. 목표는 원하는 결과를 낼 수 있는 가장 적은, 가장 중요한 정보입니다.

지침은 알맞은 높이로 씁니다. 너무 세세한 규칙 나열도, 너무 막연한 말도 아닌 중간입니다. 최소한으로 시작해, 실제로 틀린 부분이 보일 때 한 줄씩 더합니다.

예시는 대표적인 것 몇 개만 넣습니다. 예외 규칙을 길게 나열하는 것보다 잘 고른 예시 몇 개가 낫습니다.

자료는 필요할 때 가져옵니다. 모든 자료를 미리 넣지 않고, 파일 경로나 링크만 들고 있다가 필요할 때 읽습니다.

긴 작업은 세 가지로 버팁니다.

• 대화가 가득 차면 요약하고 이어서 하기(압축)
• 진행 상황을 바깥 파일에 메모해 두고 다시 읽기
• 조사는 하위 에이전트에게 맡기고 요약만 받기

4. 스킬은 이름과 설명만 들고 있다가 꺼내 읽는다

스킬은 지침·스크립트·자료를 묶은 폴더입니다. 최소 구성은 SKILL.md 파일 하나이고, 맨 위에 이름(name)과 설명(description)을 적습니다.

읽는 방식은 세 단계입니다. 평소에는 이름과 설명만 알고 있다가, 관련된 일이 오면 본문을 읽습니다. 더 자세한 자료는 필요할 때만 엽니다. 그래서 스킬을 많이 깔아도 맥락을 크게 차지하지 않습니다.

잘 만들려면 대표 업무를 먼저 시켜 보고, 막히는 지점에 맞춰 스킬을 조금씩 만듭니다. 본문이 길어지면 파일을 나눕니다.

이름과 설명은 특히 신경 씁니다. AI는 이것을 보고 스킬을 쓸지 정합니다. 잘 된 방법과 자주 하는 실수는 AI에게 직접 스킬로 정리하게 합니다.

한계는 보안입니다. 스킬 안의 지침이나 스크립트가 데이터를 밖으로 보내게 할 수도 있습니다. 믿을 수 있는 곳의 스킬만 설치하고, 아니면 안의 파일을 먼저 확인합니다.

5. 여러 에이전트는 성능만큼 비용도 크다

앤트로픽은 자사 리서치 기능을 "총괄 에이전트 + 여러 조사 에이전트" 구조로 만들었습니다. 총괄이 계획을 세우고, 조사 에이전트 여럿을 동시에 띄워 각자 찾게 한 뒤 결과를 합칩니다.

내부 평가에서 이 구조는 에이전트 하나보다 90.2% 더 좋은 성능을 냈습니다. 복잡한 조사 시간은 최대 90% 줄었습니다.

대신 비용이 큽니다. 에이전트는 일반 채팅보다 약 4배, 여러 에이전트 구조는 약 15배 많은 토큰을 씁니다.

맞는 일은 동시에 나눠 할 수 있고, 정보가 많고, 결과 가치가 큰 일입니다. 맞지 않는 일은 모두가 같은 맥락을 알아야 하거나 서로 주고받을 것이 많은 일입니다. 대부분의 코딩이 여기에 해당합니다.

배운 점도 정리돼 있습니다. 총괄이 일을 맡길 때 목표, 결과 형식, 쓸 도구, 일의 범위를 분명히 줘야 합니다. 막연하면 같은 일을 중복합니다.

인원은 일의 크기에 맞춥니다. 간단한 확인은 에이전트 하나, 복잡한 조사는 열 개 이상입니다.

평가는 대표 질문 20개 정도로 시작해도 큰 차이는 보입니다. 정해진 경로를 따랐는지보다 올바른 결과에 도달했는지를 봅니다.

6. 긴 작업은 교대 근무처럼 기록을 남긴다

하루 넘게 여러 번에 걸쳐 이어지는 작업에서, 에이전트는 매번 앞의 일을 기억하지 못한 채 시작합니다. 앤트로픽이 찾은 해법은 사람이 교대 근무할 때처럼 기록을 남기는 것입니다.

첫 세션은 준비만 합니다. 실행 방법, 진행 기록 파일, 해야 할 기능 목록을 만듭니다. 목록은 처음엔 모두 "미완료"입니다.

이후 세션은 한 번에 기능 하나씩만 합니다. 한꺼번에 많이 하려는 경향을 막기 위해서입니다. 끝날 때마다 무엇을 했는지 기록하고 저장(커밋)합니다. 잘못되면 되돌릴 수 있게 하려는 것입니다.

새 세션은 시작할 때 기록과 저장 이력부터 읽습니다. 가장 중요한 미완료 일을 고르고, 지금 상태가 망가지지 않았는지부터 확인합니다.

"완료" 판단은 실제 사용자처럼 화면에서 확인합니다. 간단한 점검만으로 완료라고 표시하는 경우가 많았기 때문입니다.

7. 평가는 실패 사례 20~50개로 시작한다

에이전트가 잘 하고 있는지 확인하는 방법입니다. 크게 기다리지 말고 작게 시작합니다. 원문 표현으로 "실제 실패에서 뽑은 20~50개의 간단한 과제면 훌륭한 시작"입니다. 지금 손으로 확인하던 항목과 사용자가 알려 준 오류부터 옮깁니다.

채점 방법은 세 가지입니다.

과정보다 결과를 봅니다. 정해진 순서를 지켰는지 따지면 다른 좋은 방법을 놓칩니다.

대화 기록은 직접 읽습니다. 점수가 낮은 원인이 에이전트가 아니라 채점 오류일 때도 많습니다.

평가는 두 종류로 나눕니다. 새 능력을 키우는 평가는 처음엔 통과율이 낮습니다. 되던 것이 망가지지 않았는지 보는 평가는 거의 100%를 유지합니다.

매번 되는지가 중요한 일은 연속 성공률을 봅니다. 한 번 성공률이 75%여도 세 번 연속 성공할 확률은 약 42%입니다.

8. Claude Code에서는 스스로 확인할 방법이 먼저다

Claude Code 공식 문서의 모범 사례 중 업무에 바로 쓸 만한 것만 골랐습니다.

첫째는 스스로 확인할 방법을 주는 것입니다. 테스트, 결과 비교, 화면 캡처처럼 통과·실패가 나오는 방법을 줍니다. 그러면 AI가 고치고 확인하기를 스스로 반복합니다. "됐다"는 말 대신 실행한 명령과 결과 같은 증거를 보여 달라고 합니다.

순서는 조사 → 계획 → 실행 → 저장입니다. 바로 만들게 하면 엉뚱한 문제를 풀 수 있습니다. 다만 한 문장으로 설명되는 작은 수정이면 계획은 건너뜁니다.

지시는 구체적으로 합니다. 어느 파일, 어떤 상황, 무엇이 "해결"인지까지 적습니다.

CLAUDE.md(작업 지침 파일)는 짧게 둡니다. 줄마다 "이 줄을 지우면 AI가 실수할까?"를 묻고 아니면 지웁니다. 길면 중요한 규칙이 묻힙니다. 가끔 필요한 업무 지식은 스킬로 뺍니다.

반드시 매번 해야 하는 일은 훅(hook)으로 만듭니다. 지침은 권고지만 훅은 자동으로 실행됩니다.

두 번 고쳐도 안 되면 새로 시작합니다. 실패한 시도가 대화에 쌓이면 더 나빠집니다. 대화를 비우고(/clear) 배운 것을 담아 다시 지시하는 편이 낫습니다.

만든 쪽과 검토하는 쪽은 나눕니다. 새 세션이나 하위 에이전트에게 검토를 맡기면 방금 만든 결과에 치우치지 않습니다. 단, 검토자에게는 "정확성과 요구사항에 영향을 주는 문제만" 보고하게 해야 과한 수정이 줄어듭니다.

가이드의 원칙은 제가 시행착오로 정한 규칙과 겹쳤다

자동 배포가 실패하는 줄 모르고 지낸 적이 있습니다. 그 뒤로 저는 "실제 주소에서 바뀐 내용이 보인다"를 작업의 끝으로 봅니다. 가이드의 "스스로 확인할 방법을 준다"와 같은 규칙입니다.

프로젝트 소개 여섯 개를 조사할 때는 조사 에이전트 여섯에게 나눠 맡겼습니다. 목표·결과 형식·범위를 정해 줬습니다. 가이드의 "총괄과 담당" 구성입니다.

블로그 글 쓰는 에이전트는 금지 규칙이 적힌 스킬을 읽고 일합니다.

큰 작업이 진행 중일 때는 별도 작업 폴더(worktree)로 나눠 같은 폴더를 동시에 고치지 않았습니다. Claude Code 문서도 여러 세션을 동시에 돌릴 때 같은 방법을 권합니다.

처음부터 다 갖출 필요는 없습니다. 하나만 고르라면 저는 "스스로 확인할 방법을 준다"부터 권합니다. 결과를 믿을 수 있어야 맡기는 일을 늘릴 수 있었습니다.

원문

• Building effective agents (2024-12-19)
• Writing effective tools for agents — with agents (2025-09-11)
• Effective context engineering for AI agents (2025-09-29)
• Equipping agents for the real world with Agent Skills (2025-10-16)
• How we built our multi-agent research system (2025-06-13)
• Effective harnesses for long-running agents (2025-11-26)
• Demystifying evals for AI agents (2026-01-09)
• Best practices for Claude Code