The best Claude Code agents are defined by what they refuse to do

개요

Claude Code 에이전트의 효과는 에이전트가 무엇을 거부해야 하는지에 대한 명확한 목록으로 정의되며, 이는 에이전트가 너무 많은 작업을 수행하여 유용성을 잃는 것을 방지한다.

주요 내용

* 효과적인 에이전트의 핵심은 '거부 목록': 에이전트가 무엇을 해야 하는지에 대한 지시사항보다, 무엇을 하지 말아야 하는지에 대한 명확한 목록이 에이전트의 성능에 더 중요하다. LLM은 본질적으로 도움을 주려 하기 때문에, 제약이 없다면 모든 에이전트는 너무 포괄적이고 일반적인 작업만 수행하게 된다.
* '거부 목록'을 통한 행동 제어: 거부 목록은 에이전트가 예상치 못한 방향으로 행동하는 것을 막고, 특정 작업에 집중하도록 만든다. 예를 들어, "자동 수정 금지", "이름, 디자인, 아키텍처에 대한 주석 금지", "보고서 내용 과장 금지", "파괴적인 작업 금지" 등의 규칙은 에이전트의 범위를 좁히는 역할을 한다.
* 실제 적용 사례: 'shipping-coach' 에이전트: 이 에이전트는 PR(Pull Request) 검토 전에 코드를 검증하는 단일 작업에 집중한다. console.log 잔재, 비밀 키 유출, .skip 파일, .DS_Store 파일 등을 탐지하며, 이러한 내용을 추가된 부분만 보고하고, 항상 "Blockers" 섹션을 포함하여 보고서의 형태를 일정하게 유지한다.
* 신뢰 구축을 위한 설계: 'shipping-coach'는 "Report only matches ADDED by this diff"와 같이 범위(scope)를 명확히 하고, "Blockers" 섹션을 항상 포함하는 고정된 출력 형식을 사용하여 사용자가 보고서를 빠르게 이해하고 신뢰할 수 있도록 설계되었다.
* 도구 스코핑의 중요성: 에이전트에게 필요한 도구만 제공함으로써, 에이전트가 파일을 수정하는 등의 원치 않는 작업을 수행하는 것을 원천적으로 방지한다. Bash, Read, Grep, Glob와 같은 보고 및 탐색 도구만 사용하고 Write나 Edit와 같은 수정 도구는 제외한다.
* 일반화된 패턴: 이러한 패턴은 PR 설명 작성, 종속성 감사 등 다양한 작업에 적용될 수 있으며, 핵심은 '하나의 작업', '명확한 설명(트리거 구문)', '제한된 도구', '고정된 출력 형식', '거부 목록'이다.

시사점

Claude Code 에이전트 개발 시 '무엇을 하지 말아야 하는지'를 명확히 정의하는 거부 목록은 에이전트의 집중도를 높이고 실질적인 유용성을 보장하는 핵심 요소이며, 이는 LLM 기반 도구의 효과적인 활용을 위한 중요한 설계 원칙으로 작용한다.