AI 바이브 코딩 기준: 코드 품질이 무너지기 전 확인할 것

목표와 사전 지식

이 글에서는 AI에게 요청할 작은 기능의 합격 기준을 작성하고, 생성된 diff가 그 범위에 맞는지 판단합니다. HTML 폼, JavaScript 이벤트, Git 변경 내역을 읽을 수 있으면 따라갈 수 있습니다. 특정 모델의 속도나 작성자의 체험을 성능 근거로 삼지 않고 변경 계약과 검증 방법을 설명합니다.

코드 품질을 유지하는 출발점은 “잘 만들어 줘”를 더 길게 쓰는 것이 아닙니다. 누가 무엇을 입력하면 어떤 결과를 받는지, 이번에 바꾸지 않을 범위가 무엇인지 먼저 정해야 합니다.

하나의 기능 계약: 게시물 목록의 제목 검색

예제로 기존 게시물 목록에 제목 검색을 추가하는 상황을 가정합니다. 처음부터 검색 서버, 추천 엔진, 저장된 필터를 모두 요청하지 않습니다. 이미 로드된 목록에서 제목 문자열을 비교하는 동작 하나가 이번 작업입니다.

항목	이번 과제의 계약
입력	검색 문자열과 이미 로드된 게시물 배열
처리	검색어 앞뒤 공백 제거 후 대소문자 구분 없이 제목 포함 여부 검사
결과	일치 항목만 표시; 검색어가 비면 원래 목록 표시
빈 결과	결과 없음 안내와 검색어 지우기 제공
제외	서버 API, 페이지네이션 계약, 로그인, 새 검색 패키지

요청에는 수정할 위치와 멈출 조건을 넣기

다음은 기존 프로젝트에 적용할 요청문 예시입니다. 파일명은 예제 이름이므로 실제 저장소에서 대응 위치를 찾고 바꿔야 합니다. 없는 파일을 있다고 가정한 실행 안내는 아닙니다.

먼저 게시물 목록과 검색 입력의 현재 구현 위치를 찾아 설명해 주세요.
현재 로드된 목록의 제목 검색만 추가합니다.
검색어는 trim 후 대소문자 구분 없이 비교합니다.
검색어가 비면 원래 순서를 보존하고 전체 목록을 보여 주세요.
API와 인증, 페이지네이션 방식, 의존성은 바꾸지 않습니다.
필요한 파일과 기존 검증 명령을 확인한 뒤 해당 범위만 수정하세요.
완료 보고에는 diff 요약, 실행한 검증, 미확인 동작을 구분하세요.

좋은 diff와 과한 diff를 구분하는 질문

좋은 diff는 줄 수가 무조건 적은 변경이 아니라 요구사항과 한 줄씩 연결되는 변경입니다. 필터 함수, 검색어 상태, 결과 없음 표시, 필요한 검증이 함께 바뀌는 것은 자연스럽습니다. 반면 전체 폴더 이동이나 전역 상태 라이브러리 추가는 제목 검색에 왜 필요한지 별도 설명이 있어야 합니다.

목록이 이미 서버에서 페이지 단위로 내려온다면 로컬 필터는 현재 페이지의 항목만 검색합니다. 이 제약을 화면에 알릴지, 전체 검색 API를 새 과제로 설계할지 결정해야 합니다. AI가 클라이언트 필터만 만들었는데 “전체 게시물 검색 완료”라고 보고하면 요구사항과 결과가 어긋납니다.

검토할 변경	확인할 이유
기존 배열을 직접 정렬·수정했는가	검색 해제 후 원래 순서가 보존되는지
제목 없는 항목 처리	API 계약 위반을 숨길지 오류로 표시할지
검색 입력과 목록 연결	입력할 때 실제 렌더 결과가 바뀌는지
테스트와 설정 파일	무관한 규칙 완화로 검증을 통과시키지 않았는지

검증은 같은 사용자 행동으로 반복하기

검색어 ” REACT “를 입력해 앞뒤 공백과 대소문자 조건을 함께 확인합니다. 없는 제목을 넣으면 결과 없음 안내가 보여야 하고, 검색어를 지우면 원래 목록과 순서가 돌아와야 합니다. 목록이 비어 있을 때도 오류가 없어야 합니다. 이는 기대 결과이며 이 글에서 특정 앱의 브라우저 실행을 완료했다는 뜻은 아닙니다.

함수 테스트는 문자열 비교를 확인하고, 브라우저 검증은 입력 반영과 안내, 포커스, 좁은 화면을 확인합니다. 빌드 성공은 실행 파일 생성 가능성을 보여 줄 뿐 이 사용자 흐름을 모두 보장하지 않습니다. 문제가 생기면 재현 입력과 실제 결과를 먼저 기록한 뒤 해당 경로를 수정합니다.

다음 작업으로 넘어가는 기준

수정 목적, 변경 파일, 합격한 검사, 남은 제한을 짧게 남깁니다. 현재 페이지 검색이라는 제한을 수용했다면 그 이유를 적고, 전체 검색이 필요하다면 다음 과제로 분리합니다. 검증되지 않은 범위를 완료라고 쓰지 않는 습관이 이후 구조 변경과 운영 판단을 단순하게 만듭니다.

관련 학습

• AI 하네스 파일 사용법: AGENTS.md와 Codex 지침 구조 이해하기
• VS Code Copilot 디버깅: Agent Log와 Chat Debug 사용법
• VS Code 1.113 업데이트 정리: MCP와 Thinking Effort 변화 확인하기

공식 자료와 확인 범위

공식 자료 확인일은 2026-09-13입니다. 제품 설명은 아래 원문을 기준으로 확인했으며, 본문의 판단 표와 가상 과제는 독자가 적용할 수 있도록 구성한 설명입니다.

• https://learn.chatgpt.com/guides/best-practices