Claude Code·Codex 실무 세팅에서 놓치기 쉬운 실패 패턴 7가지
AI 코딩 에이전트를 저장소에 붙일 때는 설치보다 작업 범위와 검증 기준을 정하는 일이 중요합니다. 코드가 생성됐다는 사실과 요구사항이 충족됐다는 사실은 별개이기 때문입니다.
1. 처음부터 “전체 개선”을 요청한다
목표가 넓으면 오류 수정과 리팩터링, 의존성 변경이 한 번에 섞입니다. 첫 작업은 재현 가능한 오류 하나로 제한하고, 수정 가능한 디렉터리와 건드리지 않을 영역을 함께 적는 편이 좋습니다.
2. 실행 환경을 확인하기 전에 수정한다
런타임 버전이나 환경변수가 다르면 기존 테스트 실패를 새 코드 문제로 오해할 수 있습니다. 변경 전에 현재 브랜치, 변경 파일, 실행 명령과 기존 테스트 결과를 확인합니다. 이미 실패하던 항목은 따로 기록합니다.
3. 저장소 설명서를 길게만 만든다
설명이 많아도 실제 빌드·테스트 명령이 없으면 작업자가 추측하게 됩니다. 안내 문서에는 최소한 다음을 넣습니다.
실행 명령
검증 명령
주요 디렉터리
금지 작업
완료 기준
오래된 설명과 현재 코드가 충돌하면 코드와 실행 결과를 확인해야 합니다.
4. 권한을 한 번에 넓힌다
코드 읽기와 로컬 수정에 필요한 권한이 배포나 운영 데이터 변경 권한까지 포함할 필요는 없습니다. 개발용 계정과 테스트 데이터를 사용하고, 외부 발송·결제·배포·데이터 삭제는 별도 확인 단계로 둡니다. 비밀번호나 토큰을 대화와 로그에 붙여 넣지 않습니다.
5. 테스트 통과만 보고 완료 처리한다
테스트를 지우거나 검증 조건을 약하게 바꿔도 결과는 초록색이 될 수 있습니다. 수정 전 실패하는 재현 사례를 확보하고, 수정 후 같은 사례가 통과하는지 봅니다. 테스트 파일 변경도 구현 코드와 함께 리뷰합니다.
6. 병렬 작업자에게 같은 파일을 맡긴다
작업 수를 늘려도 같은 설정이나 공통 모듈을 동시에 수정하면 충돌이 늘어납니다. 파일 소유 범위와 인터페이스를 먼저 나누고, 통합 담당자를 한 명 정합니다. 각 작업자의 통과 결과만으로 통합 성공을 판단하지 않습니다.
7. “완료했습니다”를 결과물로 받는다
완료 보고에는 다음이 필요합니다.
변경 파일
실제 실행한 검증과 결과
실행하지 못한 검증
남은 제약
“테스트 추가”와 “테스트 실행 성공”, “로컬 동작”과 “배포 확인”을 구분해서 받으면 과장을 줄일 수 있습니다.
첫 작업 요청 예시
“이 오류 하나만 수정해 주세요. 먼저 재현 방법과 기존 테스트 결과를 확인하고, 수정할 파일을 알려주세요. 관련 없는 리팩터링과 의존성 변경은 제외합니다. 완료 시 변경 내역, 실제 검증 결과, 남은 문제를 정리해 주세요.”
반복해서 쓰는 작업일수록 긴 프롬프트보다 재현 절차와 완료 기준을 저장소에 남기는 편이 관리하기 쉽습니다.
관련 내용을 정리한 AdrianStudio 글:
