AI 코딩 에이전트를 궤도에 유지하는 방법: 탐색하고, 계획하고, 그 다음 빌드하라

사람들이 Claude Code나 Cursor 같은 에이전트 코딩 도구를 처음 쓸 때, 한 줄짜리 요청을 입력하고 잘되기를 바라는 경향이 있습니다. 가끔은 됩니다. 하지만 종종 에이전트는 자신만만하게 잘못된 것을 만듭니다 — 묻지도 않은 문제를 풀거나, 예상치 못한 파일을 건드리거나, 실제로 중요했던 엣지 케이스를 건너뛰면서요.

해결책은 더 똑똑한 모델이 아닙니다. 워크플로입니다: 먼저 탐색하고, 그 다음 계획하고, 그 다음 빌드하라. 이것은 Anthropic이 공식 Claude Code 모범 사례 가이드에서 권장하는 패턴이며, 같은 아이디어가 편집 전에 저장소를 읽을 수 있는 모든 에이전트에 적용됩니다.

곧바로 코드로 뛰어드는 것이 실패하는 이유

AI 에이전트는 제한된 컨텍스트 윈도우 안에서 작동합니다 — 대화의 진행 기록에 더해, 읽는 모든 파일과 실행하는 모든 명령입니다. 계획을 건너뛰면 두 가지가 잘못됩니다:

1. 에이전트가 의도를 추측합니다. 당신의 마음을 읽을 수 없으므로, 모호한 프롬프트는 그럴듯하지만 잘못된 구현을 낳습니다.
2. 실수가 조용히 누적됩니다. 에이전트가 일단 편집을 시작하면, 1단계의 잘못된 가정이 당신이 알아차리기 전에 열 개의 추가 변경 아래 묻힙니다.

사고와 실행을 분리하면, 잘못된 가정이 아직 고치기 저렴할 때 잡아냅니다 — 12개 파일을 되돌리는 대신 한 문장의 교정으로요.

1단계: 읽기 전용 모드로 탐색하세요

진지한 에이전트 대부분은 이제 읽고 분석할 수 있지만 아무것도 바꿀 수 없는 모드를 가지고 있습니다. Claude Code에서는 plan mode라고 부릅니다: 에이전트가 파일을 읽고 질문에 답하되, 편집하거나, 상태를 변경하는 명령을 실행하거나, 커밋하지 않는 읽기 전용 상태입니다.

코드를 바꾸는 것이 아니라 이해하도록 에이전트에게 요청하는 것으로 시작하세요:

/src/auth를 읽고 우리가 세션과 로그인을 어떻게 처리하는지 설명해 주세요.
또 비밀 정보를 위한 환경 변수를 어떻게 관리하는지도 살펴봐 주세요.

당신은 공유 컨텍스트를 구축하고, 에이전트가 코드베이스를 수정하도록 신뢰하기 전에 실제로 이해하는지 확인하는 것입니다.

2단계: 계획을 요청하고, 그것을 밀어붙이세요

에이전트가 탐색을 마쳤으면, 어떤 코드보다 먼저 구체적인 계획을 요청하세요:

Google OAuth 로그인을 추가하고 싶습니다. 어떤 파일이 바뀌어야 하나요?
세션 흐름은 어떻게 되나요? 단계별 계획을 작성해 주세요 — 아직 코드는 쓰지 마세요.

에이전트는 번호가 매겨진 계획을 반환합니다: 어떤 파일을 건드릴지, 새 세션 흐름, 토큰을 어디에 저장할지. 이제 첫 초안을 수락하지 마세요. 이것이 궤도를 수정할 가장 저렴한 순간입니다. 빈틈을 밀어붙이세요:

• "OAuth 콜백이 중간에 실패하면 어떻게 되나요?"
• "우리는 이미 src/auth/tokens.ts에 refreshToken 헬퍼가 있습니다 — 새로 작성하지 말고 그걸 재사용하세요."
• "이것을 로그인 흐름에만 한정하세요. 기존 비밀번호 재설정 코드는 건드리지 마세요."

여기서 계획을 다듬는 몇 분이 나중에 잘못된 구현을 풀어내는 한 시간을 절약합니다.

3단계: 검증 방법을 곁들여 빌드하세요

이제서야 에이전트가 코드를 작성하게 합니다 — 그리고 스스로 작업을 검사할 방법을 줍니다. 어떤 프롬프트에든 추가할 수 있는 가장 강력한 단 하나는, 에이전트가 직접 실행할 수 있는 검증 단계입니다:

당신의 계획대로 OAuth 흐름을 구현하세요. 실패 케이스를 다루는
콜백 핸들러 테스트를 작성하고, 테스트 스위트를 실행하고, 실패를 모두 고치세요.

실행할 수 있는 검사 — 테스트, 빌드, 비교용 스크린샷 — 가 없으면 "다 된 것 같다"가 에이전트가 가진 유일한 신호이고, 모든 실수의 오류 탐지기는 당신이 됩니다. 검사가 있으면 루프가 스스로 닫힙니다: 에이전트가 작성하고, 테스트를 실행하고, 결과를 읽고, 통과할 때까지 반복합니다. 성공을 주장만 하는 대신 실제 테스트 출력을 보여 달라고 요청하세요.

4단계: 언제 계획을 건너뛸지 아세요

계획에는 오버헤드가 있고, 항상 그만한 가치가 있는 것은 아닙니다. 변경이 작고 범위가 명백하다면 — 오타 수정, 로그 한 줄 추가, 변수 이름 변경 — 그냥 에이전트에게 직접 하라고 요청하세요. Anthropic 가이드의 좋은 경험칙: diff를 한 문장으로 설명할 수 있다면, 계획을 건너뛰세요. 탐색-계획-빌드 주기는 여러 파일에 걸치거나, 확신이 없는 접근법을 쓰거나, 잘 모르는 코드를 건드리는 작업에 아껴두세요.

안전망: 일찍 궤도를 수정하고 체크포인트를 사용하세요

좋은 계획이 있어도 에이전트는 표류합니다. 두 가지 습관이 당신을 통제 상태로 유지합니다:

• 궤도를 벗어나는 순간 중단하세요. 에이전트가 잘못된 접근을 끝낼 때까지 기다리지 마세요. Claude Code에서는 Esc가 컨텍스트를 보존한 채로 동작 중간에 멈추므로, 방향을 다시 잡을 수 있습니다.
• 체크포인트를 사용해 자유롭게 실험하세요. Claude Code는 각 변경 전에 파일을 스냅샷하므로, 에이전트에게 위험한 것을 시도하라고 말하고, 잘 안 되면 되감기(Esc Esc 또는 /rewind)해서 다른 접근을 시도할 수 있습니다. (체크포인트는 외부 프로세스가 아니라 에이전트 자신의 편집을 추적합니다 — 편의 기능이지 git의 대체물이 아닙니다.)

그리고 같은 실수를 두 번 넘게 교정하고 있다면, 컨텍스트가 실패한 시도로 오염되었을 가능성이 높습니다. 그것을 비우고, 방금 배운 것을 녹여 넣은 더 날카로운 프롬프트로 다시 시작하세요 — 더 나은 프롬프트의 깨끗한 세션은 막다른 길로 가득한 긴 세션을 거의 항상 이깁니다.

핵심 정리

탐색하고, 계획하고, 빌드하고, 검증하라. 첫 작업에서는 더 느리게 느껴지고, 두 번째 작업에서 본전을 뽑습니다. 자신만만하지만 잘못된 코드를 그만 받게 되고, 당신이 실제로 의도한 것을 만드는 에이전트를 얻기 시작합니다.