Forge Fate
한국어
AI

에이전트의 동작 방식은 어디까지 이해해야 할까?

약 7분

지난 글에서는 Codex로 이미 개발 문제를 해결하고 있을 때 무엇을 더 배워야 하는지 물었다. 이번에는 그 질문을 한 장면으로 좁혀 보자. 에이전트가 API 코드를 수정했는데 결과가 예상과 다르다. 이때 동작 원리를 얼마나 알아야 다음 행동을 고를 수 있을까?

첫 질문은 “프롬프트를 어떻게 다시 쓸까?”보다 “이번 작업에서 실제로 무엇을 읽고 실행했을까?”에 가깝다. 결과가 어긋난 이유는 참고한 자료, 실행 조건, 코드 동작 중 어디에 있는지 아직 알 수 없기 때문이다. 그 구분을 시작하는 데 필요한 만큼만 에이전트의 동작을 살펴보자.

모델이 행동을 고르고, 주변 시스템이 실행한다

Codex의 동작을 이해할 때는 모델과 그 주변의 실행 시스템인 하네스를 나누어 보는 것이 유용하다. 모델은 주어진 요청과 맥락을 바탕으로 다음 응답이나 도구 사용을 선택한다. 하네스는 모델이 사용할 맥락과 도구, 작업 상태를 다루고 설정된 실행·승인 경계를 적용한다.[S2]

작업의 흐름을 간단히 적으면 이렇다.

요청·현재 맥락 → 모델의 다음 행동 또는 도구 선택 → 허용된 도구·환경에서 실행 → 출력 참고 → 다음 행동 또는 종료[S1][S2]

예를 들어 모델이 파일을 읽거나 테스트 명령을 실행하기로 하면, 도구가 반환한 내용을 참고해 수정을 이어갈 수 있다. OpenAI도 코드 수정, 도구 실행, 결과 관찰과 실패 수정이 이어지는 흐름을 설명한다.[S1] 다만 위 화살표는 이해를 돕는 도식이다. 어떤 작업에서는 단계가 생략되거나 반복되고, 사람의 입력을 기다릴 수도 있다.[S1][S2]

이 구분이 실용적인 이유는 모델에 요청한 행동과 실제로 실행된 행동이 같다고 미리 가정하지 않게 해 주기 때문이다. “테스트해 줘”라는 요청이 있어도 테스트 명령이 실행됐는지, 실행됐다면 어디까지 진행됐는지는 결과 기록에서 확인해야 한다.[S2][S5]

저장소에 있는 파일이 곧 읽은 파일은 아니다

에이전트가 참고할 수 있는 정보도 성격이 서로 다르다. 사용자의 요청이 있고, AGENTS.md처럼 정해진 탐색 규칙에 따라 불러오는 작업 지침이 있다. 작업 중 도구로 찾아 읽는 일반 파일도 있으며, 명령을 실행한 뒤 반환된 출력도 있다.[S3][S5] 지침은 작업을 어떻게 할지 알려주고, API 계약 파일 같은 참고 자료는 무엇에 맞춰 수정할지 알려준다. 도구 출력은 실제로 읽거나 실행한 뒤 얻은 결과다.

여기서 중요한 차이는 파일의 존재와 이번 작업에서 그 내용을 읽은 사실이다. Codex 문서는 AGENTS.md 계열 지침의 탐색 규칙을 설명하지만, 저장소의 일반 파일을 모두 자동으로 읽는다고 설명하지는 않는다.[S3] OpenAI 역시 작업에 필요한 문서를 맥락에 맞게 지정하는 방식을 제안한다.[S6] 따라서 저장소에 최신 API 계약이 있어도, 그 파일이 이번 수정에 반영됐는지는 실제 열람 기록과 변경 내용을 살펴야 한다.

이후의 예시는 모두 설명용 가정이다. 어떤 API 응답의 status 필드를 새 계약에 맞춰 달라고 요청했다고 해 보자. 수정된 코드를 보니 낡은 계약을 따른 듯하다. 이 인상만으로 “에이전트가 최신 계약을 무시했다”고 결론 내릴 수는 없다. 어느 계약 파일을 읽었는지, 파일의 버전과 적용 범위는 무엇인지, 변경 diff가 어느 정의와 일치하는지부터 확인해야 한다.[S3][S5]

기록은 다음 확인을 고르는 증거다

작업 기록에 실행 명령과 출력, 파일 변경과 diff가 표시될 수 있으며, 확인 가능한 범위는 환경과 화면에 따라 다르다.[S5] 이 기록은 “무엇을 시도했고 어떤 결과가 나왔는가”를 묻는 데 도움이 된다. 다만 화면에 보이는 항목이 모델의 내부 사고 과정 전체는 아니다. Codex app-server 문서에서도 작업 항목과 추론 관련 표시를 별도로 다루며, 원문 추론 표시에는 모델 지원 조건이 붙는다.

그러므로 기록을 읽는 목적은 보이지 않는 생각을 완전히 복원하는 데 있지 않다. 다음에 확인할 대상을 좁히는 데 있다. 같은 API 수정 작업에서도 계약을 잘못 참고한 정황, 테스트를 실행하지 못한 기록, 실행된 테스트의 실패 출력은 서로 다른 행동을 요구한다.

같은 수정 작업에서 갈라지는 네 가지 경로

다음 표는 앞서 가정한 status 필드 수정을 계속 따라간다. 실제 장애나 수행한 실험의 결과가 아니며, 각 증상은 확인 전까지 원인을 확정해 주지 않는다.

가정한 상황확인할 증거다음 조치
수정은 했지만 낡은 계약을 따른 듯하다실제로 읽은 계약 파일과 버전, 현재 적용할 계약, 변경 diff.[S3][S5]최신 계약의 위치와 적용 범위를 확인하고 해당 변경을 다시 검토한다. 저장소에 파일이 있었다는 사실만으로 읽었다고 판단하지 않는다.
테스트 명령을 시도했지만 DB에 연결하지 못했다명령의 실행 여부와 종료 상태, 오류 출력, 접속 대상, DB 준비 상태.[S5]DB 상태와 접속 설정을 확인하고 실행 조건을 마련한 뒤 테스트한다. 연결 실패만으로 코드 결함을 확정하지 않는다.
필요한 실행이나 접근이 권한 경계에서 막혔다승인·거부 기록, 적용된 환경과 권한 설정, 실행되지 않은 명령의 범위.[S2][S4][S5]작업에 필요한 범위의 접근과 승인 조건을 확인한다. 요청 문장을 강하게 바꾸는 것으로 실행 경계가 달라진다고 가정하지 않는다.[S4]
테스트가 실제로 실행되어 assertion이 실패했다실패한 assertion, 기대값과 실제값, 사용한 fixture, 관련 코드와 diff.[S5]계약·테스트·구현 중 무엇이 어긋났는지 조사한다. 수정한 뒤 영향을 받는 테스트를 다시 확인하되, 실패 문구 하나로 원인을 확정하지 않는다.

같은 “테스트 실패”라는 표현이라도 명령이 실행됐는지에 따라 다음 질문이 달라진다. 기록은 원인을 확정하기보다 조사할 범위를 좁혀 준다.

권한 문제라면 프롬프트의 어조보다 실행 환경과 승인 설정을 확인해야 한다. 샌드박스와 승인 정책은 명령이 접근할 수 있는 범위와 실행 전 승인이 필요한 조건을 다룬다.[S4] 필요한 작업의 범위를 확인하는 것이 먼저다.

어디까지 공부할지는 남은 문제로 정한다

앞의 API 수정 사례에서는 확인된 증거에 따라 공부할 깊이를 정할 수 있다. 다음 순서는 효과가 입증된 보편적 방법이 아니라, 이 글에서 제안하는 판단 기준이다.

누락된 자료를 찾아 작업 맥락을 바로잡는 것으로 문제가 풀린다면, 그 문제를 이해하는 데는 거기까지로 충분하다. 환경과 권한을 구분해 테스트가 실제로 실행되도록 했다면, 필요한 실행 조건을 이해한 것이다.

읽은 자료와 실행 조건을 확인한 뒤에도 같은 문제가 반복되거나 특정 구현 결정을 내려야 한다면 더 깊이 살펴볼 이유가 생긴다. 그때도 원리를 두루 공부하기보다 남은 문제나 결정에 관계된 구현·하네스·모델 메커니즘으로 학습 범위를 좁힌다.

최근 Codex에 맡긴 개발 작업 하나를 골라 다음 네 가지를 찾아보면 어떨까. 실제로 읽은 파일은 무엇인가? 실행한 명령과 실제 결과는 무엇인가? 실행하지 못했거나 아직 확인하지 못한 부분은 무엇인가? 그렇다면 다음에 확인할 한 가지는 무엇인가? 작업 기록만으로 답할 수 없는 질문이 남는다면, 그 빈칸 자체가 다음 조사의 출발점이다.

이번 편의 질문은 결과를 해석하려면 동작 방식을 어디까지 알아야 하는가였다. 다음 편에서는 시선을 작업을 맡기기 전으로 옮긴다. 더 많이 맡길 수 있게 되면 개발자는 무엇을 결정해야 할까?

Sources

오류 제보·의견 보내기

글 제목과 주소가 포함된 메일 초안을 엽니다. 내용과 받는 사람을 확인한 뒤 보내주세요.

받는 사람: [email protected]

메일 앱에서 작성

메일 앱이 열리지 않으면 아래 내용을 복사해 평소 쓰는 이메일에 붙여 넣으세요.

문의 안내

관련 글