Claude Code와 에이전트 프롬프팅
https://youtu.be/XSZP9GhhuAc?si=ZgUK-S-I0wFw2xmH
https://youtu.be/gv0WHhKelSE?si=r6HLoJ5EdYg8ANfm
위 두 개의 영상을 보고 나서 내용을 정리한 포스팅입니다.
1. Claude Code의 등장과 그 의미
[ Claude Code란 무엇인가 ]
Claude Code는 Anthropic이 개발한 터미널 기반 코딩 에이전트로, 개발자의 코딩 방식을 근본적으로 변화시키는 도구이다. Anthropic의 Applied AI 팀 소속 Cal은 Claude Code를 통해 개인 프로젝트를 진행하면서 주말 동안 엄청난 진척을 경험했고, 평소라면 불가능했을 만큼 강력한 애플리케이션을 구축할 수 있었다고 한다.
Claude Code의 핵심은 "터미널에서 모든 것을 하는 동료"라는 개념이다. 이는 마치 주니어 엔지니어 시절의 시니어 멘토처럼, 터미널 명령과 도구를 능숙하게 다루며 문제를 해결하는 전문가와 함께 일하는 것과 같다고 볼 수 있다.
[ 순수 에이전트 방식의 작동 원리 ]
Anthropic은 "단순하지만 작동하는 것"이라는 철학에 따라 Claude Code를 설계했다. 복잡한 RAG 시스템이나 임베딩 방식은 쓰지 않는다. 대신 새로운 팀원이 코드베이스를 탐색하는 방식과 유사한 "에이전트적 검색"을 사용한다.
glob, grep, find 같은 전통적인 검색 도구로 코드베이스를 뒤지는 것이다. 검색 결과를 분석한 뒤 필요하면 추가로 검색을 던져서 점진적으로 코드베이스를 이해한다.
작동 방식은 간단하다. 강력한 도구와 명확한 지침을 모델에 주고, 작업을 완료했다고 판단할 때까지 루프에서 돌린다. 다만 위험한 작업은 사람이 승인해야 한다. 읽기는 자동으로 허용하지만 파일 쓰기나 Bash 명령 실행 같은 변경 작업에는 물어본다.
2. Claude Code의 실전 활용 사례
[ 코드베이스 탐색 및 이해 ]
새로운 코드베이스에 투입될 때 Claude Code는 특정 기능의 구현 위치를 찾거나 Git 기록을 분석하여 코드 변경 이력을 파악하는 데 탁월한 성능을 보인다. 이는 마치 숙련된 선배 개발자가 코드베이스를 가이드해주는 것과 같다고 볼 수 있다.
[ 사고 파트너로서의 활용 ]
기능 구현이나 코드 변경 전에 Claude를 "사고 파트너"로 활용하면, 다양한 구현 옵션을 탐색하고 계획을 세울 수 있다. 이는 단순히 코드를 작성하는 것을 넘어, 설계 단계에서부터 협업할 수 있다는 것을 의미한다.
[ 코드 작성 및 테스트 자동화 ]
Claude Code는 빈 디렉토리에서 새로운 앱이나 게임을 구축하는 제로 베이스 작업에 매우 효과적이다. 특히 기존 코드베이스에 유닛 테스트를 추가하거나 커밋 메시지, PR 메시지를 작성하는 작업에서 탁월한 성능을 보인다. Anthropic 팀은 Claude Code 덕분에 높은 유닛 테스트 커버리지와 좋은 커밋 메시지를 유지하고 있다고 언급한다.
[ 디버깅 및 마이그레이션 ]
오류를 빠르게 디버깅하고, 오래된 버전의 Java를 최신 버전으로 마이그레이션하거나 PHP를 React 또는 Angular로 전환하는 등 대규모 코드베이스 마이그레이션 프로젝트를 관리하는 데에도 활용할 수 있다. Git, Docker, Big Query 등 다양한 CLI 도구를 능숙하게 다루므로, 복잡한 Git 리베이스 문제 등 터미널 관련 작업을 해결하는 데 유용하다.
3. Claude Code 모범 사례
[ claude.md 파일을 통한 컨텍스트 공유 ]
Claude Code는 기억력이 없다. 따라서 claude.md 파일로 세션 간 또는 팀원 간에 중요한 정보나 지침을 공유해야 한다. 이 파일은 작업 디렉토리에 있으면 Claude가 실행될 때 프롬프트에 자동으로 포함된다.
claude.md 파일에는 다음과 같은 정보를 넣을 수 있다.
- 유닛 테스트 실행 방법
- 프로젝트 레이아웃 및 디렉토리 구조
- 테스트 위치 및 모듈 정보
- 코딩 스타일 가이드
- 내부 도구 사용 방법
이 파일은 프로젝트에 포함하여 팀원들과 공유하거나, 홈 디렉토리에 넣어 항상 Claude가 참조하도록 할 수 있다. 단, 하위 디렉토리의 claude.md 파일은 기본적으로 안 읽어오니, @ 기호로 명시적으로 참조해야 한다.
[ 권한 관리 및 워크플로우 최적화 ]
autoaccept mode(Shift+Tab)를 쓰면 Claude가 작업을 계속하도록 할 수 있다. 특정 Bash 명령(npm run test 등)은 설정에서 항상 승인하도록 구성하면 워크플로우가 빨라진다.
Claude Code는 터미널을 잘 다루므로, GitHub의 GH CLI 도구처럼 CLI로 접근 가능한 애플리케이션과 연동하면 더 강력해진다. CLI 도구를 더 설치하거나 MCP 서버를 연결하면 기능을 확장할 수 있다.
[ 컨텍스트 관리 전략 ]
Claude는 에이전트라서 도구 호출이 반복되면서 컨텍스트가 쌓인다. Anthropic 모델은 20만 토큰의 컨텍스트 창이 있지만, 이것도 가득 찰 수 있다.
컨텍스트 창이 가득 차면 두 가지 방법이 있다.
- /cle 명령어: claude.md 빼고 컨텍스트를 다 지우고 새로 시작
- /compact 명령어: 이전 세션 내용을 요약해서 다음 세션의 시드로 활용
[ 효율적인 워크플로우 구축 ]
버그 수정이나 기능 구현할 때 Claude에게 바로 작업 시키지 말고, 먼저 문제 원인을 파악하고 해결 계획을 세우도록 시키는 게 좋다. 그래야 계획을 검토하고 검증할 시간이 생긴다.
Claude가 큰 작업을 수행할 때 할 일 목록을 만드는데, 이걸 보다가 이상한 게 보이면 Escape 키를 눌러 개입하면 된다. TDD를 쓰고, Claude가 작은 변경을 만들고 테스트를 돌려서 항상 통과하도록 하는 게 좋다. TypeScript 및 린팅 검사도 하고, 자주 커밋해서 문제 생기면 롤백할 수 있게 해야 한다.
Claude는 멀티모달 모델이라 스크린샷이나 이미지 파일로 웹사이트 구축 같은 시각적 작업을 시킬 수 있다.
4. 에이전트란 무엇이며 언제 사용해야 하는가
[ 에이전트의 정의와 핵심 구성 요소 ]
Anthropic에서는 에이전트를 "도구를 루프에서 사용하는 모델"이라고 정의한다. 작업을 주면 적합한 도구를 계속 쓰면서 결정을 업데이트하고 독립적으로 작업을 끝낸다.
에이전트는 환경, 도구, 시스템 프롬프트로 구성된다. 시스템 프롬프트는 단순하게 유지하는 게 좋다.
[ 에이전트 사용이 적합한 시나리오 ]
에이전트가 항상 필요한 건 아니다. 다음과 같은 경우에 쓰면 된다.
- 복잡하고 가치 있는 작업
- 단계별 과정이 불분명할 때: 목표는 알지만 정확히 어떻게 도달해야 할지, 어떤 도구와 정보가 필요한지 모를 때
- 높은 가치 창출: 수익 창출이나 시간 절약 같은 높은 가치를 얻을 수 있을 때
- 작업의 구성 가능성: 에이전트가 필요한 도구와 정보에 접근할 수 있어야 함
- 오류 복구 용이성: 오류 복구 비용이 낮거나 오류 탐지가 쉬운 경우
[ 주요 활용 사례 ]
코딩 작업은 디자인 문서에서 PR까지 가는 과정을 에이전트가 처리함으로써 고도로 숙련된 엔지니어의 시간을 절약할 수 있는 매우 가치 있는 사용 사례다. 검색 오류는 인용이나 교차 확인을 통해 복구할 수 있으므로, 오류 비용이 낮다. 컴퓨터 사용에서 클릭 오류 등은 다시 시도하여 복구할 수 있다.
데이터 분석에서는 원하는 결과(통찰력, 시각화)는 알지만, 데이터의 형식, 오류, 세분화 문제 등으로 인해 정확한 분석 과정을 모를 때 에이전트가 유용하다.
5. 에이전트 프롬프팅 모범 사례
[ 에이전트처럼 생각하기 ]
프롬프트 엔지니어링은 자연어로 프로그래밍하는 거랑 비슷하다. 에이전트의 목표와 행동을 명확하게 전달하고 필요하면 예시와 가이드라인을 주면 된다. 에이전트의 환경(도구, 도구 응답)을 이해하고 에이전트 입장에서 시뮬레이션해서 헷갈릴 부분을 찾아야 한다. 사람이 못 알아듣는 지시는 AI도 못 알아듣는다.
[ 합리적인 휴리스틱 제공 ]
프롬프트 엔지니어링은 모델이 가져야 할 개념과 따라야 할 행동을 정하는 "개념 엔지니어링"이다.
불가역성 개념: Claude Code는 사용자나 환경에 해를 끼칠 수 있는 불가역적인 행동을 피하도록 지시받는다. 모델이 너무 열심히 하다가 예상 못한 행동을 하지 않게 개념을 명확하고 정확하게 정의해야 한다.
구체적인 예시는 다음과 같다.
- 검색 중지 시점 명시: 이미 답을 찾았는데도 계속 검색하지 않게 "답을 찾으면 멈춰라"고 명확히 지시
- 도구 호출 예산: 간단한 쿼리는 5개 미만, 복잡한 쿼리는 10~15개 정도로 예산을 정해서 리소스 낭비를 막음
신입 인턴에게 첫 직장에서 생길 수 있는 모든 문제와 해결 방법을 설명하는 것처럼 에이전트에게 휴리스틱을 제공해야 한다.
[ 도구 선택의 중요성 ]
Claude 4 모델은 수백 개 도구를 처리할 수 있지만, 어떤 작업에 어떤 도구를 써야 하는지 명확한 원칙을 알려줘야 한다. 회사에서 Slack을 많이 쓴다면 회사 관련 정보 검색할 때 Slack을 기본으로 쓰게 명시하는 식이다.
도구 이름은 간단하고 정확해야 하고, 설명은 잘 짜여서 사람이 이해하고 쓸 수 있어야 한다. 비슷한 도구 6개가 있으면 모델이 헷갈리니까, 도구를 명확히 구별하거나 유사한 건 하나로 합쳐야 한다.
[ 사고 과정 유도 ]
extended thinking 기능을 켜는 것만으로도 성능이 좋아지지만, 에이전트가 사고 과정을 잘 쓰게 프롬프팅하면 성능을 더 끌어올릴 수 있다.
검색 작업이면 검색 프로세스를 미리 계획하게 지시하는 게 좋다. 쿼리의 복잡성, 필요한 도구 호출 수, 찾아야 할 소스, 성공 기준 같은 걸 사전에 계획하게 하는 것이다.
Claude 4의 새 기능인 도구 호출 간 연계된 사고를 쓰면, 도구 호출 후에 검색 결과의 품질을 생각하고 필요하면 추가 정보를 확인하거나 면책 조항을 붙이게 할 수 있다. 그래야 웹 검색 결과를 맹목적으로 믿지 않는다.
[ 에이전트의 예측 불가능성 인지 ]
에이전트는 워크플로우나 분류 프롬프트보다 예측이 안 되고, 작은 변경에도 예상 못한 부작용이 생길 수 있다.
"정확한 답을 찾을 때까지 계속 검색하라"는 지시는 완벽한 출처를 못 찾으면 컨텍스트 창이 가득 찰 때까지 계속 검색하는 부작용을 낳는다. 따라서 "완벽한 출처를 못 찾아도 몇 번 도구 호출 후에는 멈춰도 된다" 같은 지시를 넣어야 한다.
[ 컨텍스트 창 관리 전략 ]
Claude 4 모델은 20만 토큰 컨텍스트 창이 있지만, 자율로 돌아가는 에이전트는 이걸 다 채울 수 있다.
압축(Compaction): Claude Code에서 쓰는 기능으로, 컨텍스트 창이 거의 가득 찼을 때(약 19만 토큰) 자동으로 내용을 요약하고 압축해서 새 Claude 인스턴스에 전달한다. 이 덕분에 Claude Code는 사실상 무한 컨텍스트로 돌릴 수 있다. 특정 릴리즈 패치 이후로 자동에서 수동으로 전환된 듯 하다.
외부 파일에 쓰기: 모델이 외부 파일에 메모리를 기록하고 참조해서 컨텍스트 창을 확장한다.
하위 에이전트(Sub-agents): 주 에이전트가 하위 에이전트한테 특정 작업을 위임한다. 하위 에이전트가 검색해서 결과를 압축해서 보고하면, 주 에이전트는 이걸로 최종 보고서를 작성해서 컨텍스트를 아낀다.
[ Claude가 Claude가 되도록 두기 ]
Claude는 이미 에이전트로 훌륭하니까 처음부터 다 자세히 프롬프팅할 필요는 없다. 간단한 프롬프트와 최소한의 도구로 시작해서 시스템이 어떻게 돌아가는지 보고, 문제 생기는 지점을 찾아서 점진적으로 개선하면 된다.
6. 평가(Evals)의 중요성
[ 에이전트 평가의 어려움과 전략 ]
평가는 프롬프트 개선 및 시스템 진행 상황을 체계적으로 측정하는 데 필수적이다. 에이전트는 실행 시간이 길고 예측 못할 과정이 많아서 분류 작업보다 평가하기 어렵다.
평가를 쉽게 하는 팁은 다음과 같다.
- 작은 표본 크기로 시작: 효과 크기가 크면(변화의 영향이 명확하면) 적은 수의 테스트 케이스로도 충분한 신호를 얻는다. 초기엔 수백 개 자동 평가보다는 작고 수동적인 평가로 시작하는 게 좋다.
- 현실적인 작업 사용: 실제 시스템이 할 작업과 관련된 현실적인 태스크로 평가해야 한다. 코딩 에이전트한테 경쟁 프로그래밍 문제 대신 실제 코딩 작업을 주는 식이다.
- LLM을 심판으로 사용: 에이전트의 다양한 출력 형식에 대해 LLM이 평가 기준(루브릭)을 바탕으로 정확성을 판단하게 한다. 출력의 미묘한 변형에도 강건하다.
- 인간 평가의 중요성: 결국 시스템 진행 상황을 파악하려면 전사 기록을 검토하고 모델 행동을 이해하는 등 수동적인 인간 평가가 필수다.
[ 평가 방법의 예시 ]
에이전트 평가에는 다양한 방법을 쓸 수 있다.
- 답변 정확성: LLM을 써서 에이전트가 올바른 답변을 줬는지 평가
- 도구 사용 정확성: 에이전트가 올바른 도구를 적절한 횟수만큼 썼는지 프로그래밍 방식으로 확인. 웹 검색 도구가 5번 호출됐는지 확인하는 식
- 최종 상태 달성: 에이전트가 프로세스 끝에 올바른 최종 상태에 도달했는지 평가. 고객 서비스 에이전트가 항공편 변경 요청을 성공적으로 처리해서 데이터베이스에 반영됐는지 확인하는 식
7. 최신 업데이트 및 실전 팁
[ Claude Code의 최신 기능 ]
모델 선택: /model 명령어로 실행 중인 모델(Sonnet이나 Opus)을 확인하고 /config 명령어로 전환할 수 있다.
도구 호출 간 생각(Think Hard): Claude 4부터는 모델이 도구 호출 사이에 "생각"할 수 있게 됐다. 이전 모델은 도구 호출 사이엔 생각이 안 됐다. "think hard" 지시를 쓰면 Claude가 더 깊이 생각하고 파일 내용 읽는 등의 도구 호출 사이에 회색 텍스트로 사고 과정을 보여준다.
IDE 통합: VS Code 및 JetBrains 같은 IDE와의 통합이 개선돼서, Claude가 현재 작업 중인 파일을 인식하고 더 효율적으로 일한다.
[ 고급 활용 팁 ]
여러 Claude 동시 사용: 숙련된 사용자는 T-Mox나 여러 탭에서 Claude Code 인스턴스를 4개까지 동시에 돌려서 작업을 조율할 수 있다.
Escape 키 활용: Claude가 일하는 동안 Escape 키를 눌러 중지하고 개입해서 잘못된 방향으로 간다 싶으면 지시를 바꿀 수 있다. Escape 키를 두 번 누르면 대화 기록을 되돌리는 숨은 기능도 있다.
MCP를 통한 도구 확장: Bash와 기본 도구로 안 되는 작업이 있으면 MCP 서버로 도구를 추가할 수 있다.
헤드리스 자동화: GitHub Actions 같은 CI/CD 환경에 Claude를 통합해서 프로그래밍 방식으로 쓰는 방법에 대한 연구와 개발이 활발히 진행 중이다.
[ 프롬프팅 실전 조언 ]
프롬프트를 만들 때는 처음에 짧고 간단한 프롬프트로 시작해서 Claude가 작업을 얼마나 잘하는지 보는 게 좋다. 그 다음 더 많은 케이스로 테스트하면서 발견되는 문제점이나 엣지 케이스를 바탕으로 프롬프트에 지침이나 예시를 추가하며 점진적으로 개선하면 된다.
전통적인 프롬프팅에서 효과적인 퓨샷(few-shot) 예시는 최신 모델이나 에이전트에는 별로 안 먹힌다. 모델이 이미 충분히 똑똑해서 명확한 지시 없이도 "생각하는 과정"을 스스로 하도록 훈련됐기 때문에, 너무 많은 예시로 모델 행동을 제한하면 오히려 역효과다. 대신 모델에게 "생각하는 과정"을 어떻게 쓸지(검색 계획 수립, 코딩 시 특정 사항 기억 같은) 지시하는 게 더 효과적이다.
마무리
Claude Code와 에이전트 프롬프팅은 개발자의 생산성을 크게 올려줄 수 있는 강력한 도구다. 하지만 효과적으로 쓰려면 에이전트가 어떻게 돌아가는지 이해하고, 적절한 프롬프팅 기법을 적용하고, 지속적으로 평가하고 개선해야 한다.
도구를 그냥 쓰는 게 아니라 에이전트의 사고 방식을 이해하고 협업하는 법을 익히는 게 중요하다. 그래야 개발자가 더 복잡하고 가치 있는 문제 해결에 집중할 수 있게 된다.
참고 자료
Anthropic의 공개 GitHub 프로젝트 "Claude Code"에서 이슈를 보고하고 변경 로그를 확인하여 최신 업데이트를 파악할 수 있다.
Claude 관련 공식 문서: https://docs.claude.com
