AI 에이전트 프롬프트 설계 7가지 원칙: CLAUDE.md·검증 강제·컨텍스트 관리 정리

핵심 메시지

• 코딩 에이전트는 챗봇이 아니라 도구 실행 루프다. 한 번에 큰 질문을 던지는 대신 조사·계획·실행·검증으로 단계를 쪼개 시켜야 한다.
• 지시를 쓸 때 '해야 할 것'과 '하지 말아야 할 것'을 나란히 적고 기준에 숫자를 넣으면 AI가 멈출 지점이 생긴다.
• AI는 모른다고 말하기보다 했다고 말하는 쪽으로 기울기 때문에, '검증할 수 없으면 검증할 수 없다고 말하라'는 허가를 명시적으로 줘야 한다.
• 정말 중요한 규칙은 문서 맨 앞·본문·맨 끝 세 군데에 나눠 적는 편이 강한 문장 하나보다 준수율이 높다.
• 컨텍스트 관리는 곧 비용 관리다. 컨텍스트에 올린 파일은 쓰지 않아도 매 호출마다 다시 전송되며 과금된다.

쉽게 이해하기

이 영상은 코딩 에이전트를 다루는 방식 자체를 다시 짚는다. 발표자는 클로드 코드가 챗봇이 아니라 에이전트 런타임이라는 점을 먼저 강조한다. 사용자 입력을 받아 어떤 도구를 쓸지 판단하고, 권한을 확인하고, 실행하고, 결과를 다시 모델에게 돌려주는 루프가 핵심이며, 더 쓸 도구가 없을 때까지 이 과정이 반복된다는 것이다. 챗봇이 전화 상담원이라면 에이전트는 현장에 와서 장비를 직접 만지는 엔지니어라는 비유가 이어진다. 그래서 질문을 던지는 방식과 일을 시키는 방식이 달라져야 한다는 것이 7가지 기법 전체를 관통하는 전제다. 참고로 영상은 유출됐다는 클로드 코드 소스코드를 직접 분석한 결과를 근거로 제시하며, 원본 저장소는 DMCA 요청으로 이미 내려갔다고 밝히고 있다.

앞의 세 가지는 '어떻게 말하느냐'에 해당한다. 첫째는 대조 패턴이다. "간결하게 써줘" 같은 지시는 기준이 사람마다 달라 작동하지 않으므로, 선호하는 방식과 금지하는 방식을 한 줄에 나란히 두고 숫자를 넣으라는 것이다. 파일 검색에는 특정 도구를 쓰고 다른 명령은 쓰지 말라고 못 박거나, 도구 호출 사이의 텍스트를 25단어 이내로, 최종 응답을 100단어 이내로 제한한 예가 제시된다. 둘째는 검증 강제다. 작업 완료를 보고하기 전에 실제로 돌려보게 하고, 검증이 불가능하면 그렇다고 말하도록 허용한다. 금지 지시는 '테스트 통과를 거짓 주장하지 말라'처럼 나쁜 행동이 나타날 형태까지 나열하고, 금지에는 반드시 대안을 함께 붙인다.

셋째는 반복 배치다. 대화가 20~30턴을 넘기면 앞서 적은 규칙이 흐려지는 경험은 흔하다. 영상은 자동 압축 프롬프트에서 같은 금지 지시가 맨 앞의 경고, 본문, 맨 끝의 리마인더로 세 번 등장한 구조를 근거로 든다. 모델에 최근성 편향이 있으니 앞에서 주의를 잡고 실행 직전에 한 번 더 상기시키는 배치가 유효하다는 설명이다. 데이터베이스를 직접 삭제하지 말라는 식의 치명적 규칙이라면 세 번 적어도 과하지 않다.

뒤의 네 가지는 시스템의 작동 방식에 맞춰 행동하는 영역이다. 넷째 턴 예산은 읽기와 쓰기를 여러 턴에 섞지 말고 한 턴에서 읽기를 병렬로 몰아 처리한 뒤 다음 턴에서 수정하라는 원칙이다. 안전한 조회형 도구는 동시에 실행되지만 파일 수정이나 명령 실행처럼 위험한 도구는 하나씩 순서대로 처리된다. 여기에 비용 문제가 겹친다. 컨텍스트에 올라간 파일은 열어보고 쓰지 않아도 매 호출마다 전송되어 과금되므로, 긴 대화는 주기적으로 압축하고 작업 순서를 프롬프트에 명시하는 것만으로 토큰과 시간이 함께 절약된다.

다섯째는 사고 과정의 분리다. 분석 내용을 특정 태그 안에 쓰게 한 뒤 출력 단계에서 그 태그를 통째로 제거하는 구조가 발견됐다는 것으로, 시험에서 연습장에 풀이를 하게 하고 답만 옮겨 적게 한 뒤 연습장을 수거하는 방식에 비유된다. 생각을 시키는 것과 생각을 관리하는 것은 다른 층의 기술이라는 지적이다. 여섯째는 Skills 설명 예산이다. Skills 목록에 배정되는 토큰이 전체 컨텍스트 윈도우의 1%로 고정돼 있고 개별 설명은 250자로 제한되며, 예산을 넘기면 사용자가 만든 Skill의 설명부터 축소되고 그래도 부족하면 이름만 남는다. 설명이 잘리면 언제 써야 할지 판단할 근거가 사라져 트리거 자체가 죽는다. 일곱째는 컨텍스트 경계다. 별도 작업을 분리해 맡겼다면 진행 중에 그 작업 로그를 끌어와 읽지 말라는 규칙으로, 도구 실행 과정의 소음이 본 대화로 흘러들어 분리한 목적 자체가 무너지기 때문이다.

주요 인사이트

• 금지 지시가 잘 듣지 않는 이유는 빠져나갈 구멍이 남기 때문이다. "과자 먹지 마"가 아니라 "과자, 초콜릿, 젤리, 아이스크림 전부 먹지 마"처럼 형태를 열거해야 한다는 비유가 그대로 프롬프트 작성 규칙이 된다.
• '하지 마라'만 적으면 AI는 무엇을 해야 할지 모른다. 금지와 대안을 쌍으로 적는 습관이 결과물의 안정성을 크게 바꾼다.
• Skills를 많이 만들어 두는 것이 오히려 손해가 될 수 있다. 예산을 넘기면 뒤로 밀린 Skill의 설명이 잘려 호출되지 않으므로, 개수를 늘리기보다 자주 쓰는 것만 남기고 설명을 압축하는 관리가 필요하다.
• 턴 예산이 작업의 '순서'를 설계하는 일이라면 컨텍스트 오염 방지는 작업의 '경계'를 설계하는 일이다. 복잡한 프로젝트에서는 두 가지를 함께 관리해야 결과가 흔들리지 않는다.
• 영상은 유출된 코드 자체보다 방향이 중요하다고 정리한다. 스펙과 테스트를 사람이 쓰고 구현을 AI에 맡기는 방식이 이미 도입되는 흐름에서는 코드를 잘 짜는 능력보다 무엇을 만들지 정의하고 작업을 쪼개는 능력이 더 값어치를 갖는다는 것이다.

자주 묻는 질문

관련 AI 소식