한 문장을 쓰고 Enter를 눌렀더니 터미널에 줄이 줄줄이 올라오기 시작합니다. 파일을 열었다. 명령을 실행했다. 같은 파일을 또 열었다. 밖에서 보면 괜히 분주해 보입니다. 간단한 일 하나를 부탁했을 뿐인데, 뭔가 길고 알 수 없는 일이 벌어지고 있는 것처럼요.
하지만 괜히 분주한 게 아닙니다. 에이전트는 세 부분으로 된 루프를 반복해서 돌고 있고, 화면에 보이는 것은 거의 전부 같은 루프를 한 바퀴, 또 한 바퀴 도는 모습일 뿐입니다.
에이전트가 채팅보다 많은 일을 하는 이유
채팅은 답을 출력하고 끝이고, 나머지는 전부 손으로 해야 합니다. 복사하고, 붙여넣고, 저장하고, 실행하고. 에이전트는 여러분의 프로젝트 안에서 직접 움직입니다. 파일을 열고, 수정하고, 명령을 실행하고, 결과를 확인합니다. 그리고 변경 사항은 실제로 디스크에 남습니다.
여기서 이 글의 핵심이 나옵니다. 에이전트는 조언만 하는 게 아니라 직접 손을 움직이기 때문에, 한 번의 동작으로는 끝나지 않습니다. 여러분이 쓴 한 문장과 완성된 결과 사이에는 여러 단계가 있고, 그 단계가 모두 화면에 표시됩니다.
한 단계는 무엇으로 이루어지나
요청을 받으면 에이전트는 이 루프에 들어가서 필요한 만큼 몇 바퀴든 돕니다. 한 바퀴는 세 부분으로 이루어져 있습니다.
컨텍스트 수집. 에이전트는 모르는 부분을 읽어서 채웁니다. 필요한 파일을 열고, 프로젝트 구조를 살펴보고, 직전 명령의 출력을 읽습니다. 가장 많이들 놀라는 부분은 이것입니다. 에이전트는 여러분의 프로젝트를 외우고 있는 게 아니라, 읽고 있습니다. 세부 정보가 필요할 때마다 직접 가서 확인합니다.
액션 실행. 구체적인 액션 하나입니다. 파일을 수정하거나 명령을 실행하거나. 구상 전체를 한꺼번에 하는 게 아니라, 바로 다음 한 걸음입니다.
결과 확인. 무엇이 나왔는지 보고, 여러분이 요청한 내용과 비교합니다.
여기서 갈림길이 나옵니다. 목표를 달성했다면 에이전트는 멈추고 다음 요청을 기다립니다. 달성하지 못했다면 컨텍스트 수집으로 돌아가 한 바퀴 더 돕니다.
게다가 이 루프는 정해진 순서를 기계적으로 밟는 게 아니라, 요청에 맞춰 모양이 바뀝니다. 코드에 대한 간단한 질문이라면 컨텍스트 수집에서 끝날 수도 있습니다. 읽고, 답하고, 아무것도 바꾸지 않는 거죠. 반대로 버그를 고칠 때는 세 부분을 전부 여러 번 돌게 됩니다. 그리고 부분 사이의 경계가 항상 뚜렷한 것도 아닙니다. 에이전트는 루프 내내 도구를 사용합니다.
이상해 보였던 일은 전부 여기서 설명됩니다. 에이전트가 같은 파일을 두 번 연 건, 수정한 뒤에 다시 확인해야 했기 때문입니다. 요청부터 응답까지 몇 분이 걸린 건, 한 바퀴가 아니라 네 바퀴를 돌았기 때문이고요. 처음으로 돌아가는 건 오류가 아니라 루프가 원래 그렇게 동작하는 것입니다.
추론과 도구 호출
에이전트가 하는 일이 전부 프로젝트의 파일을 바꾸는 것은 아닙니다. 그 경계선은 작업의 딱 한가운데를 지나가고, 이걸 구분할 수 있으면 도움이 됩니다.
추론 - 에이전트가 다음에 무엇을 할지, 어느 파일을 볼지, 오류의 원인이 무엇일지 따져 보는 단계입니다. 이때 디스크에는 아무 변화도 없습니다. 아무리 설득력 있게 추론하더라도 아직은 의도일 뿐입니다.
도구 호출 - 여기서 실제로 무언가가 일어납니다. 파일을 읽거나 쓰기, 프로젝트 안에서 검색하기, 명령 실행하기, 인터넷에서 문서 찾아보기. 이런 액션은 하나하나 터미널에 별도의 줄로 표시되고, 프로젝트에 일어난 일은 바로 이 줄들이 쌓여서 만들어집니다.
호출 결과는 에이전트에게 돌아가서, 다음 바퀴에서 에이전트가 아는 내용의 일부가 됩니다. 파일을 읽었다면 이제 그 내용을 압니다. 테스트를 실행했다면 이제 통과했는지 아닌지를 압니다.
명령이 실패했다, 파일을 찾지 못했다, 테스트가 통과하지 않았다. 에이전트는 이걸 보고 다음 단계에서 반영합니다. 출력에 오류 메시지가 떴다고 해서 모든 게 망가졌으니 포기해야 한다는 뜻은 아닙니다. 오히려 에이전트에게 부족했던 바로 그 정보인 경우가 많고, 다음 바퀴는 이전 바퀴보다 더 정확해집니다.
실무적인 결론은 간단합니다. 도구 호출 줄은 안 보고 스크롤해도 되는 부수적인 잡음이 아닙니다. 지금 이 순간 여러분의 파일에 무슨 일이 일어나고 있는지 보이는 곳입니다.
에이전트가 질문하는 이유
작업 도중에 에이전트가 멈추고 질문할 수 있습니다. 이건 루프에서 정상적으로 일어나는 일이지, 에이전트가 제대로 해내지 못했다는 신호가 아닙니다.
질문에는 서로 다른 두 종류가 있고, 구분해 두면 도움이 됩니다.
- 작업에 대한 정보가 부족하다 - 정확히 무엇을 바꿀지, 비슷한 두 파일 중 어느 쪽을 말한 건지, 무엇을 완성으로 볼지. 에이전트가 모호한 부분에 부딪혔고, 짐작으로 진행하고 싶지 않은 겁니다.
- 액션에 대한 허가가 필요하다 - 에이전트가 영향이 큰 작업을 하려다가 해도 되는지 묻기 위해 멈춘 겁니다. 에이전트가 어디까지 스스로 판단하는지는 설정에 달려 있습니다.
첫 번째 종류의 질문은 좋은 신호입니다. 루프를 세 바퀴나 엉뚱한 방향으로 돈 다음에 다시 하는 것보다, 지금 확인하는 편이 낫습니다.
질문을 기다릴 필요 없이 먼저 끌어낼 수도 있습니다. 맨 처음, 첫 수정이 시작되기 전에 에이전트에게 작업을 자기 말로 설명하고 불분명한 점은 모두 물어보라고 요청해 보세요.
작업을 어떻게 이해했는지, 어떻게 해결할 생각인지 적어 주세요.
작업과 목표를 더 잘 이해하는 데 도움이 된다면 질문해 주세요.이렇게 하면 모호한 점이 작업이 절반쯤 진행된 뒤가 아니라 첫 수정 전에 드러납니다. 진행 중에 끼어드는 것도 언제든 가능합니다. 컨텍스트를 추가하거나, 방향을 바로잡거나, 에이전트를 멈추고 작업을 다시 설명하면 됩니다.
완료를 결정하는 사람은 누구인가
에이전트가 말하는 "완료"의 의미는 딱 하나입니다. 에이전트의 루프가 끝났다는 것. 액션을 실행했고, 자기 기준으로 결과를 확인했고, 목표를 달성했다고 판단한 거죠. 하지만 작업 자체는 아직 끝나지 않았습니다.
변경 사항이 승인되는 시점은 에이전트가 그 변경을 했을 때가 아니라, 사람이 실제로 무엇이 바뀌었는지 확인하고 그 결과를 책임지기로 했을 때입니다. 그다음 갈 길은 두 가지입니다. 승인이면 작업은 끝납니다. 수정 요청이면 무엇이 잘못됐는지 여러분이 정리해 새로 요청하고, 루프는 그 요청에서 다시 시작됩니다.
이때 봐야 할 것은 보고가 아니라 변경 사항 그 자체입니다. 에이전트는 어떤 줄을 지웠고 어떤 줄을 추가했는지 보여 줍니다. "무엇이 바뀌었나"에 대한 정확한 답은 바로 거기에 있고, 에이전트가 쓴 설명 안에는 없습니다.
에이전트는 한 일을 트집 잡을 데가 없을 만큼 그럴듯하게 설명할 줄 압니다. "메서드 세 개에 오류 처리를 추가하고 확인했습니다. 모두 정상 동작합니다". 사실처럼 들립니다. 하지만 응답 텍스트와 파일 내용은 서로 다른 것이고, 둘이 항상 일치하지는 않습니다. 진짜 무슨 일이 있었는지 알 수 있는 유일한 방법은 변경 목록을 보는 것입니다.
Claude Code와 함께 쓸 때 달라지는 점
루프를 이해하면 실제로 이런 점이 달라집니다.
- 요청이 정확할수록 바퀴 수가 줄어듭니다. 에이전트는 요청한 내용과 맞아떨어질 때까지 루프를 돌기 때문에, 모호하게 쓰면 그만큼 바퀴를 더 돌게 됩니다.
- 여러분이 직접 파일을 고친 내용도 에이전트는 다음에 그 파일을 열 때 알게 됩니다. 프로젝트를 기억하는 게 아니라 읽으니까요. 손으로 뭔가 고쳤다면 에이전트에게 알려 주세요.
- 에이전트의 루프는 "완료"라는 말로 끝납니다. 작업은 여러분의 확인으로 끝나고, 이 둘은 서로 다른 시점입니다.
전체 그림은 이렇습니다. 에이전트의 루프가 안쪽, 여러분의 확인이 바깥쪽.
GO TO FULL VERSION