AI 코딩 도구를 사용할 때 검토 부채는 왜 생기며 어떻게 줄이나요?
AI가 만든 변경을 이해하지 않은 채 쌓으면 나중에 사람이 한꺼번에 확인해야 하는 검토 부채가 생깁니다. 검색 추가·구조 정리·색상 변경을 한 요청에 묶지 말고 목적별로 나누세요.
본문 근거: learn.chatgpt.com
먼저 기준을 정합니다
검토 부채는 AI가 만든 변경을 충분히 이해하지 않은 채 계속 쌓아 나중에 사람이 한꺼번에 검토해야 하는 비용입니다. 생성 속도가 리뷰 속도를 앞지르지 않도록 작업 단위를 제한합니다.
AI 코딩 도구의 제품 이름이나 UI는 바뀔 수 있지만, 저장소를 읽고 변경하고 검증한다는 기본 흐름은 같습니다. 따라서 특정 버튼 위치를 외우기보다 다음 질문에 답할 수 있어야 합니다.
- AI가 지금 어떤 파일을 읽을 수 있는가?
- 어떤 파일을 수정해도 되는가?
- 어떤 명령을 실행해도 되는가?
- 비밀정보가 컨텍스트에 포함되지 않았는가?
- 완료를 무엇으로 증명할 것인가?
요청을 작업 계약으로 바꾸기
작업 단위
→ 작은 diff 생성
→ 사람이 변경 이유 이해
→ 테스트 확인
→ 승인
→ 다음 작업
큰 diff 여러 개 누적
→ 나중에 한 번에 검토
→ 검토 부채 증가
좋은 요청은 구현 방법을 모두 대신 결정하는 문서가 아닙니다. 목표와 경계, 완료 조건을 명확히 해서 AI가 불필요한 범위를 추측하지 않게 만드는 것이 목적입니다.
직접 해볼 일 · 입력과 검토 기준
독자 질문: AI가 만든 변경을 언제 멈춰 검토할까?
실습: ‘필터 추가+디자인 정리+의존성 업데이트’를 세 개의 독립 변경으로 나누고 첫 변경의 검토 예산을 정하세요.
입력 예시: 완료 항목 필터만 먼저 구현할 계획을 써 주세요. 포맷 정리와 패키지 업데이트는 별도 작업으로 남기세요. 수정 파일별 이유와 실행할 검증 명령을 먼저 열거해 주세요.
결과 검토: 첫 변경의 diff에서 기능과 무관한 줄·생성 파일·잠금 파일 변화를 표시합니다. 테스트 통과는 리뷰 완료와 다릅니다. 검토 시간이 과도하거나 설명할 수 없는 줄이 있으면 작은 단위로 다시 나눕니다.
수정 요청: ‘기능 관련 변경만 남겨 주세요. 포맷/업데이트는 별도 목록으로 옮기고 각 파일의 수정 이유를 한 줄씩 적어 주세요’로 재요청합니다.
다음 학습: 6회차에서 중단 후 이어갈 수 있도록 현재 상태를 남깁니다.
확인 범위: 공식 자료 learn.chatgpt.com를 대조했습니다. 이 글의 AI 도구 조작·저장소 변경·명령 실행은 편집자가 직접 수행하지 않았으므로 미확인입니다. 독자는 자신의 환경에서 결과를 기록해 주세요.
독립 실습: 큰 요청을 검토 단위로 나누기
“검색 추가, 폴더 구조 정리, UI 색상 변경”을 한꺼번에 맡기지 말고 먼저 검색 동작만 계약합니다. 다음에 구조 변경이 실제로 필요한지 별도로 판단하고, 색상은 별도 요청으로 둡니다. 각 단위는 기능이 돌아가는 상태에서 검증하고 다음 단위로 넘어갑니다.
검토 기록 예시(측정값은 직접 입력)
요청 단위: 검색어 공백 처리
예상 파일 / 실제 파일:
검토 시작·종료 / 재작업 시간:
범위 초과 변경:
요구사항을 사람이 확인한 근거:
남은 위험 / 승인 여부:
분리 결과 예: 1차는 검색 기능과 그 경계값 검증, 2차는 필요성이 입증된 폴더 구조 변경, 3차는 UI 색상 변경입니다. 1차 diff에 lockfile 변화가 있다면 검색 기능에 필요한 이유부터 확인합니다. 계획을 세 개 썼다는 사실보다 각 단위의 완료 조건과 다음 단위 시작 조건이 분리됐는지를 봅니다.
자주 발생하는 오류와 해결
테스트가 통과해도 요구하지 않은 동작은 검출하지 못할 수 있습니다. 계약과 실제 diff를 대조합니다. 검토 중 더 이상 변경 이유를 설명할 수 없다면 새 생성 요청을 멈추고 현재 변경부터 이해합니다. 파일 수·시간은 작업 조건과 함께 기록하며 생산성 향상 수치를 임의로 만들지 않습니다.
선택 실습: 같은 프로젝트로 연습하기
이 선택 실습은 TaskFlow 작업 관리 앱의 변경 요청을 AI와 함께 검토하는 연습입니다. 요청·코드·검증 결과를 구분해 기록합니다.
이번 주제: 개발자가 AI 코딩 도구를 쓸 때 생기는 검토 부채 문제.
TaskFlow 실습
이어서 읽기: AI 하네스 파일 사용법 AGENTS.md와 Codex 지침 구조 이해하기. 누적 작업 기록은 docs/ai-log.md에 회차별로 추가합니다. 새로 진입하면 실제 개발환경 시작 ZIP을 별도 폴더에 풉니다. 이 앱에는 상태 문구와 API URL 표시가 있으며 작업 목록·검색·완료 필터는 없습니다. 상단의 필터 예시는 독립 설계 문제이고, 현재 앱에서 그대로 실행된 기능으로 기록하지 않습니다.
하나의 큰 요청을 2~3개의 작은 작업으로 나눕니다.
각 작업 후 diff 검토 → 테스트 → 승인 → 다음 작업으로 진행합니다.
PR 또는 커밋 단위가 사람이 검토 가능한 크기인지 기록합니다.
실습은 가능한 한 작은 변경으로 시작합니다. 변경 전에 현재 working tree를 확인하고, AI가 작업한 뒤에는 대화 내용보다 실제 diff를 기준으로 판단합니다.
git status --short
git diff
프로젝트에 맞는 검증 명령이 있다면 함께 실행합니다.
pnpm lint
pnpm build
이 과정의 TaskFlow 기준은 pnpm 11.19.0이며 lint·build 스크립트를 사용합니다. test 스크립트는 없으므로 npm test나 pnpm test가 통과한다고 기록하지 않습니다. 별도 테스트가 있는 저장소는 package.json의 실제 명령을 추가하고, TaskFlow 동작은 브라우저 확인으로 별도 기록합니다.
변경을 검토하는 방법
AI-assisted 개발 로그에 예상 변경 범위, 실제 변경 파일 수, 테스트 결과, 재작업 여부를 기록합니다.
검토할 때는 “코드가 그럴듯한가”가 아니라 요구사항과 diff를 비교합니다.
요청한 파일만 바뀌었는가
기존 규칙을 재사용했는가
새 dependency가 필요한가
오류 처리와 접근성을 놓치지 않았는가
검증 결과가 실제 실행 결과인가
되돌리기 쉬운 변경인가
실패와 위험
- AI가 만든 테스트를 그대로 신뢰
- 대량 포맷 변경과 기능 변경 혼합
- 검토하지 않은 코드를 다음 작업의 기반으로 사용
- 성공한 실행 로그만 보고 코드 품질 판정
AI가 틀릴 수 있다는 추상적인 경고보다 실패를 발견할 구조를 만드는 것이 중요합니다. 작은 diff, 명확한 검증 명령, 사람 승인 지점이 있으면 모델이 달라져도 같은 작업 원칙을 유지할 수 있습니다.
완료 체크리스트
- 검토 부채를 정량 수치로 단정하지 않음
- 작은 diff가 항상 좋은 설계라는 식으로 단순화하지 않음
- 다음 상태 관리 회차에서 작업 중단·재개 문제로 확장
누적 기록과 실행 결과
이전 회차 ai-step-04-harness에 남긴 기록을 시작점으로 사용합니다.
현재 구조는 기존 TaskFlow 소스와 package.json을 유지하고, 학습 기록은 새로 만드는 docs/ai-log.md에 누적합니다. 이 경로는 앱 실행 파일이 아닌 실습용 기록 위치입니다. 기존 동명 파일이 있으면 덮어쓰지 않고 회차 항목을 추가합니다. 앱 수정 파일은 저장소 탐색 후 계약에 확정하며 문서의 예시 경로를 실제 파일로 가정하지 않습니다.
Before는 해당 회차의 기록 항목이 없는 상태이고, 적용은 위 실습을 수행하며 관찰 내용을 채우는 과정입니다. After는 아래 항목의 근거와 미검증 범위가 남은 상태입니다. 문서 제목을 바꾸는 것만으로 기능 구현이 완료된 것은 아닙니다.
아래는 docs/ai-log.md에 추가하는 회차 항목 전체입니다. 앱 전체 코드가 아닌 개발 로그 양식이며, 빈칸은 직접 확인한 결과로 채웁니다.
체크포인트: ai-step-05-review-debt
작업 요청 / 목표 / 비목표:
시작 상태 / 적용 지침:
허용 파일 / 실제 변경 파일:
계획 / diff 요약:
실행 명령 / 실제 결과 / 증거 위치:
미검증 항목 / 필요한 조건:
사람이 확인·수정한 내용:
승인 여부 / 승인 대상:
commit: 미생성 또는 실제 확인한 식별자
실패 지점 / 복구점 / 다음 행동:
검증란은 성공·실패·미실행을 구분합니다. 이 양식 자체는 실행 성공이나 사람 승인 증거가 아닙니다. 앱을 바꿨다면 diff → pnpm lint·pnpm build → 필요한 브라우저 확인 → 사람 검토 → 승인 → commit 순서로 기록합니다. 로그만 편집한 단계는 내용 대조가 검증이며 앱 테스트 통과로 부풀리지 않습니다.
완료 체크포인트
ai-step-05-review-debt
다음 학습
6회차 AI 에이전트가 실패하는 진짜 이유: 모델 성능보다 상태 관리가 먼저다
도구별 기능·권한 명칭·설치 방법은 발행 시점 공식 문서를 기준으로 다시 확인하고, 이 글의 원칙과 제품별 UI를 구분합니다.
글 소개·학습 준비·전체 목차
AI 코딩 도구 · 5 / 11
개발자가 AI 코딩 도구를 쓸 때 생기는 검토 부채 문제
AI가 코드를 빠르게 만들수록 사람이 검토해야 할 변경도 빠르게 쌓인다는 검토 부채를 설명합니다. 생성 속도가 아니라 검토 가능한 단위가 전체 개발 속도를 결정할 수 있음을 TaskFlow PR 단위로 확인합니다.
선수 지식
diff를 읽고 한 기능의 완료 조건을 설명할 수 있어야 합니다.
이번 글에서 배우는 내용
- 검토 부채 정의
- 큰 diff에서 결함을 놓치기 쉬운 이유
- 기능·리팩터링·포맷 변경 분리
- 테스트가 검토를 대체하지 않는 이유
- AI 설명이 아니라 실제 코드와 테스트를 검토
- 변경량·검토시간·재작업시간을 함께 보는 기준
목차
이 글이 도움이 되었나요?
읽음 기록
읽음 — / 전체 11개 · 필수 9개
새 글 받아보기
RSS 리더에서 BlogFlow의 새 글을 확인할 수 있습니다.
