코덱스 툴 사용법 09: 스크린샷과 로그로 디버깅 맡기기 | DAKER 커뮤니티

코덱스 툴 사용법 09: 스크린샷과 로그로 디버깅 맡기기

코덱스에게 버그를 맡길 때 가장 흔한 실패는 "이 화면이 이상해"라고만 말하는 것이다. 사람 동료에게도 그 말만으로는 부족하다. 어떤 화면인지, 실제로 무엇이 보이는지, 콘솔에는 어떤 오류가 있는지, 정상이라면 무엇이 보여야 하는지까지 있어야 빠르게 좁힐 수 있다.

OpenAI 공식 Codex CLI 도움말은 Codex가 텍스트뿐 아니라 스크린샷이나 다이어그램 같은 멀티모달 입력을 받을 수 있고, 로컬에서 코드를 읽고 수정하며 명령을 실행할 수 있다고 설명한다. 이 조합을 제대로 쓰면 "화면을 보고 추측하는 챗봇"이 아니라 "증거를 보고 코드와 테스트까지 닫는 디버깅 작업자"로 쓸 수 있다.

아래 Mermaid 다이어그램은 화면 버그를 코덱스에게 넘길 때의 기본 흐름이다. 게시 본문에서는 같은 흐름을 SVG 이미지로도 볼 수 있다.

1. 스크린샷은 "보이는 것"을 고정한다

UI 버그는 말로 설명할수록 흐려진다. "버튼이 깨졌다"는 말보다 한 장의 스크린샷이 낫고, 스크린샷보다 더 좋은 것은 URL, 뷰포트, 재현 순서를 함께 주는 것이다.

좋은 요청은 이렇게 시작한다.

첨부한 스크린샷은 /settings/billing 화면을 1440x900에서 본 상태다.
오른쪽 결제 카드의 가격 텍스트가 버튼 위로 겹친다.
재현 순서: 로그인 > 설정 > 결제 탭 > 연간 플랜 선택.
먼저 관련 컴포넌트와 스타일 파일을 읽고 원인을 좁혀줘.

이렇게 쓰면 코덱스는 "어떤 코드가 문제일까"보다 "이 화면 상태를 만드는 코드가 어디인가"로 탐색한다. 특히 프론트엔드에서는 이 차이가 크다.

2. 로그는 "왜 깨졌는지"를 좁힌다

스크린샷은 현상을 보여주지만 원인을 보장하지 않는다. 콘솔 오류, 네트워크 응답, 테스트 실패 로그를 같이 주면 코덱스가 훨씬 빠르게 원인을 좁힐 수 있다.

예를 들어 다음 세 가지를 함께 붙인다.

브라우저 콘솔 오류
실패한 API 요청의 상태 코드와 응답 요약
관련 테스트 또는 빌드 실패 출력

프롬프트는 이렇게 쓸 수 있다.

콘솔에는 "Cannot read properties of undefined (reading 'price')"가 나온다.
네트워크 탭에서 /api/plans 응답은 200이지만 enterprisePlan 필드가 없다.
이 조건에서 UI가 깨지지 않도록 방어 로직을 추가해줘.
새 API 필드를 만들지는 말고, 기존 응답 형태를 기준으로 처리해줘.

이 요청은 해결 방향도 좁힌다. "API를 고쳐라"가 아니라 "현재 응답에서 UI가 깨지지 않게 처리해라"라고 경계를 닫았기 때문이다.

3. 정상 동작을 짧게 써야 수정이 작아진다

코덱스가 과하게 고치는 이유 중 하나는 정상 기준이 없기 때문이다. 정상 기준은 길 필요가 없다.

정상 동작:
- enterprisePlan이 없으면 엔터프라이즈 카드를 숨긴다.
- 월간/연간 토글은 계속 동작한다.
- 가격 카드 높이는 기존 디자인을 유지한다.

이 정도면 충분하다. 코덱스는 이 기준에 맞춰 관련 코드만 수정하고, 필요하면 테스트를 추가할 수 있다. 반대로 "보기 좋게 고쳐줘"라고 하면 디자인, 데이터 구조, 레이아웃 전체를 넓게 건드릴 위험이 커진다.

4. 금지 범위는 꼭 적는다

화면 버그를 고치다 보면 코덱스가 API, 디자인 시스템, 글로벌 CSS, 환경 설정까지 읽을 수 있다. 읽는 것은 괜찮지만 쓰는 범위는 좁히는 편이 좋다.

아래처럼 적으면 diff가 작아진다.

수정 범위:


- billing 화면 컴포넌트와 관련 테스트만 수정
- 전역 CSS, 디자인 토큰, API 스키마는 수정하지 않음
- 배포 명령은 실행하지 않음

특히 실제 서비스와 연결된 프로젝트에서는 "배포하지 마", "환경 변수 파일은 읽거나 쓰지 마", "마이그레이션은 실행하지 마" 같은 문장이 중요하다. 디버깅은 빠르게 해야 하지만, 빠르다는 이유로 영향 범위를 넓히면 리뷰 비용이 더 커진다.

5. 검증은 다시 같은 화면으로 돌아와야 한다

UI 디버깅의 완료 기준은 테스트 통과만으로 부족할 때가 많다. 테스트가 있어도 실제 화면에서 텍스트가 겹치거나 버튼이 눌리지 않을 수 있다.

좋은 완료 요청은 이렇게 끝난다.

수정 후 다음을 확인해줘.
1. 관련 테스트 실행
2. 같은 URL과 같은 뷰포트에서 화면 재확인
3. 콘솔 오류가 사라졌는지 확인
4. 변경 파일과 남은 위험 보고

Codex App이나 브라우저 도구를 쓸 수 있는 환경이라면 실제 페이지를 열어 스크린샷으로 확인하게 하면 좋다. 로컬 서버가 필요하면 코덱스가 서버를 띄우고 브라우저로 확인할 수 있다. 서버를 띄울 수 없다면 그 이유와 대신 실행한 테스트를 보고하게 한다.

6. 바로 붙여 넣는 프롬프트 템플릿

아래 템플릿을 버그 리포트처럼 채워서 쓰면 된다.

다음 화면 버그를 고쳐줘.

화면:
{URL 또는 화면 이름}

증상:
{스크린샷에서 보이는 문제}

재현:
{클릭 경로, 뷰포트, 계정 조건}

로그:
{콘솔 오류, 네트워크 응답, 테스트 실패}

정상 동작:
{수정 후 기대하는 상태}

제약:
{수정 금지 파일, 배포 금지, 환경 변수 금지}

검증:
관련 테스트를 실행하고, 가능하면 같은 화면을 다시 확인해줘.
완료 보고에는 변경 파일, 검증 결과, 남은 위험을 포함해줘.

이 템플릿의 목적은 코덱스를 통제하는 것이 아니라, 코덱스가 쓸 증거를 정리해 주는 것이다. 증거가 좋으면 수정은 작아지고, 검증은 선명해진다.

7. 실무에서는 "스크린샷 하나 + 로그 하나 + 정상 기준 하나"로 시작한다

처음부터 완벽한 버그 리포트를 만들 필요는 없다. 다만 최소 세 가지는 챙기는 편이 좋다.

실제 화면 스크린샷
콘솔 또는 테스트 로그 한 묶음
정상이라면 무엇이 달라져야 하는지 한 문장

이 세 가지가 있으면 코덱스는 파일 탐색, 원인 추정, 패치, 검증을 훨씬 안정적으로 이어갈 수 있다.

Senior takeaway: 코덱스 디버깅은 프롬프트 길이보다 증거 품질이 좌우한다. 스크린샷으로 현상을 고정하고, 로그로 원인을 좁히고, 정상 기준과 금지 범위로 수정면을 닫으면 화면 버그도 리뷰 가능한 작은 작업으로 끝낼 수 있다.