Claude Code로 첫 AI 에이전트를 만들며 저지른 9가지 실수와 교훈

커뮤니티 반응

작성자의 상세한 경험 공유에 대해 긍정적인 반응이며, 특히 모델 라우팅과 보안 문제에 대한 관심이 높다.

주요 논점

01찬성다수

모델 라우팅이 비용 절감과 사용량 제한 해결에 필수적이다.

02찬성다수

AI 생성 설정 파일은 반드시 수동 검토가 필요하다.

합의점 vs 논쟁점

합의점

AI 에이전트 구축은 거대한 목표보다 작은 단계부터 점진적으로 진행해야 한다.
Git을 통한 버전 관리는 개발 초기부터 필수적으로 수행해야 한다.

논쟁점

에이전트의 자가 개선 기능을 어느 수준까지 허용할 것인가에 대한 안전성 문제.

실용적 조언

모든 파이프라인 단계에 LLM을 넣지 말고, 마지막 언어 생성 단계에서만 호출하여 효율성을 높여라.
외부 마켓플레이스 스킬을 사용할 때는 반드시 코드를 감사하고 보안 스캐너를 활용하라.

섹션별 상세

Claude Code의 /init 명령어로 생성된 CLAUDE.md 파일을 맹신하여 발생한 초기 설정 오류를 지적했다. 자동 생성된 지침 중 상단에 위치한 단 한 문장의 오해로 인해 며칠 동안 원인 불명의 버그가 발생했다. AI가 생성한 설정이라도 개발자가 직접 한 줄씩 읽고 검증하지 않으면 시스템 전체의 논리가 꼬일 수 있음을 확인했다.

모든 작업에 고성능 모델인 Opus를 사용하여 API 사용량 제한에 빠르게 도달하는 비효율을 경험했다. 단순 작업은 로컬 모델, 일반 작업은 Sonnet, 복잡한 추론은 Opus로 분기하는 모델 라우팅 시스템을 도입하여 문제를 해결했다. 이 방식을 통해 비용을 절감하면서도 에이전트의 응답 품질을 최적으로 유지하는 실무적 합의에 도달했다.

에이전트가 스스로 CLAUDE.md를 수정하게 허용했을 때 가드레일 부재로 인해 핵심 로직이 파괴되는 현상을 목격했다. 이를 방지하기 위해 프로젝트별로 지침을 분산하고 에이전트는 말단 파일만 수정할 수 있게 하는 계층적 구조를 설계했다. 시스템의 근간이 되는 'Trunk'는 보호하고 세부 실행 단위인 'Leaves'만 자가 개선을 허용하는 것이 안정적이다.

외부 마켓플레이스에서 제공하는 스킬을 검증 없이 설치했을 때 발생할 수 있는 보안 위협을 경고했다. 에이전트의 권한으로 실행되는 스킬 내부에 악성코드가 숨겨진 사례를 발견하고 이를 탐지하기 위한 스캐너를 직접 구축했다. 또한 Git을 사용하지 않아 발생할 수 있는 작업 손실을 방지하기 위해 초기 단계부터 버전 관리를 철저히 할 것을 권장했다.

언급된 도구

Claude Code추천

에이전트 빌드 도구 및 런타임

Opus추천

복잡한 추론 작업 처리

Sonnet추천

일반적인 작업 처리

언급된 리소스

튜토리얼How to build your first AI agent: A beginner’s guide (2026)