AI 코딩 도구가 완료했다고 해도 확인해야 할 5가지
AI 코딩 도구에 기능을 맡긴 뒤 “수정 완료”라는 답을 받았습니다. 그런데 실제 화면에서는 기능이 작동하지 않거나, 오류를 잡는 과정에서 테스트가 빠져 있을 수 있습니다. 작업 기록이 길다는 사실과 결과가 검증됐다는 사실은 다릅니다. 혼자 앱을 만들거나 작은 팀에서 AI 도구를 쓰는 사람이라면, 작업을 맡기기 전에 무엇을 확인할지 정해 두는 편이 유용합니다.
해외 개발자 Adrian Studio는 실제 저장소에서 겪은 AI 코딩 에이전트의 문제를 15가지로 정리했습니다. 이 글은 그 사례를 출발점으로 삼되, 국내 개인 개발자도 바로 적용할 수 있는 점검 순서로 다시 구성했습니다. 특정 도구를 직접 비교 시험하거나 아래 방법의 효과를 측정한 사용기는 아닙니다.
“완료”의 기준을 결과로 적어 두기
“로그인 오류를 고쳐 줘”처럼 넓게 요청하면 AI는 코드를 수정한 것만으로 일을 마쳤다고 판단하기 쉽습니다. 요청할 때 기대하는 동작과 확인 방법을 함께 적어 보세요. 예를 들어 “비밀번호가 틀리면 오류 안내가 보이고, 올바르면 대시보드로 이동한다. 관련 테스트와 기존 테스트를 실행한 결과를 알려 달라”는 식입니다.
답변에도 바뀐 파일, 실제 실행한 검사, 통과·실패 결과, 직접 확인하지 못한 부분을 구분해 달라고 요청합니다. “테스트 통과”라는 한 줄보다 어떤 검사를 실행했고 어떤 결과가 나왔는지 알 수 있어야 사람이 다시 확인할 수 있습니다. 화면이나 결제·로그인처럼 실제 이용 과정이 중요한 기능은 코드 검사 외에 브라우저에서 한 번 더 살펴야 합니다.
문제를 해결하는 과정에서 검사 기준이 사라지지 않았는지 보기
AI가 실패하는 테스트를 수정하거나 삭제하면 결과가 모두 초록색으로 보여도 원래 문제가 남을 수 있습니다. 변경 내역에서 테스트 파일이 제거되었는지, 검사가 건너뛰도록 바뀌었는지 확인하세요. 오류를 고치는 작업이라면 같은 오류를 다시 재현하는 검사가 남아 있는지도 중요합니다.
한 번에 너무 큰 일을 맡기면 확인도 어려워집니다. “회원가입 전체 개선”보다 “중복 이메일 입력 시 안내가 표시되는지 확인”처럼 결과를 판단할 수 있는 단위로 나누면 수정 범위와 검토 시간이 줄어듭니다. 물론 모든 작은 변경에 새 테스트가 필요한 것은 아닙니다. 위험도가 높은 동작부터 재현 가능한 확인 방법을 마련하는 것이 현실적입니다.
수정 범위와 프로젝트 규칙을 파일에 남기기
프로젝트마다 지켜야 할 규칙이 있습니다. 어떤 폴더만 수정할지, 데이터를 삭제하는 명령은 어떻게 다룰지, 배포는 누가 결정할지 같은 내용입니다. 이런 규칙을 매번 대화에서 반복하면 빠뜨리거나 서로 다른 내용으로 전달하기 쉽습니다.
Codex는 저장소의 AGENTS.md를 작업 지침으로 읽을 수 있고, Gemini CLI는 설정에 따라 사용할 지침 파일 이름을 지정할 수 있습니다. 도구마다 파일을 읽는 방식은 다르므로 실제 적용 여부는 각 도구의 공식 안내와 실행 결과로 확인해야 합니다. 파일을 만들어 놓았다는 사실만으로 규칙이 자동 집행되는 것도 아닙니다. 중요한 규칙은 가능한 경우 검사 도구나 권한 설정으로도 강제하고, 작업을 마친 뒤 실제 변경 파일 목록을 확인하세요.
비밀번호와 외부 작업은 별도 경계로 다루기
“비밀 파일은 읽지 마”라고 요청문에 적는 것만으로 접근 권한이 차단되지는 않습니다. AI가 사용할 수 있는 파일, 명령, 네트워크 범위를 실행 환경에서 정해야 합니다. OpenAI의 보안 안내도 에이전트가 접근할 수 있는 파일·자격 증명·네트워크를 실제로 사용할 수 있다고 설명합니다. 비밀번호나 API 키는 작업 설명이나 오류 기록에 그대로 붙이지 말고, 필요한 서비스에만 제한적으로 제공하세요.
게시, 메시지 전송, 결제, 배포처럼 외부에 결과를 남기는 작업에는 중복 방지 절차도 필요합니다. 요청이 시간 초과로 끝났을 때는 실패했다고 단정할 수 없습니다. 상대 서비스가 처리했지만 응답만 돌아오지 않았을 수도 있습니다. 같은 작업을 다시 실행하기 전에 해당 서비스에서 결과가 이미 만들어졌는지 확인하세요. 반복 실행하는 작업에는 고유한 작업 번호를 기록하면 중복을 줄이는 데 도움이 됩니다.
검토자는 수정자가 아닌 확인자로 두기
AI가 만든 결과를 다른 AI가 검토할 수 있지만, 검토와 수정을 한 번에 맡기면 무엇을 발견했고 무엇을 바꿨는지 흐려질 수 있습니다. 먼저 변경 내역과 요구 사항을 읽고 문제, 근거, 영향을 보고하게 하세요. 수정은 그 보고를 본 뒤 별도 작업으로 진행하면 판단 과정이 남습니다.
오래 운영하는 프로젝트라면 과거의 결정도 짧게 정리해야 합니다. 다만 예전 기록을 계속 덧붙이기만 하면 현재 설정과 충돌할 수 있습니다. 날짜와 근거를 함께 적고, 더 이상 맞지 않는 내용은 정리하세요. AI에게 과거 기록을 전달할 때도 지금 실제 화면과 파일을 확인하도록 요청하는 편이 안전합니다.
처음 시작할 때는 이 세 문장부터
복잡한 자동화 설정을 한 번에 도입할 필요는 없습니다. 다음 세 문장을 작업 요청에 추가해 보세요.
- “이번 작업에서 바꿀 파일과 바꾸지 않을 파일을 먼저 적어 주세요.”
- “완료 기준을 실행 가능한 확인 방법으로 적고, 실제 실행 결과를 알려 주세요.”
- “확인하지 못한 부분과 외부 서비스에 남긴 결과를 구분해 주세요.”
AI 코딩 도구를 잘 쓰는 기준은 얼마나 많은 파일을 빠르게 고쳤느냐보다, 결과를 사람이 확인하고 필요하면 되돌릴 수 있느냐에 가깝습니다. 작은 작업부터 완료 기준, 변경 범위, 권한, 외부 작업 기록을 갖추면 도구가 달라져도 같은 기준으로 결과를 판단할 수 있습니다.
참고 자료
- Adrian Studio, 15 Ways AI Coding Agents Fail in Real Repos (and the Guardrails That Fix Them) — 문제 사례의 출발점
- OpenAI, Iterating Development Workflows with Codex —
AGENTS.md와 검증 기록에 관한 안내 - OpenAI, Sandbox security — 실행 환경과 자격 증명 경계
- Gemini CLI, Provide context with GEMINI.md files — 지침 파일 설정 방식
자료 확인일: 2026년 10월 16일. 도구별 설정과 권한 동작은 업데이트될 수 있으므로 적용 전 공식 문서를 다시 확인해야 합니다.
