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

이 선택 실습은 TaskFlow 작업 관리 앱의 변경 요청을 AI와 함께 검토하는 연습입니다. 요청·코드·검증 결과를 구분해 기록합니다.

제공 스타터의 상태 문구 변경 한 건에 목표 / 비목표 / 변경 파일 / 유지해야 할 동작 / 검증 항목을 추가합니다. apps/web/src/main.js의 실제 문구를 읽고 변경할 위치를 확정하며 API URL 표시와 기존 환경 설정은 유지합니다.

TaskFlow 실습

이어서 읽기: 바이브 코딩이란 Cursor Claude Code Codex로 앱 만드는 방식과 현실. 누적 작업 기록은 docs/ai-log.md에 회차별로 추가합니다. 새로 진입하면 실제 개발환경 시작 ZIP을 별도 폴더에 풉니다. 이 앱에는 상태 문구와 API URL 표시가 있으며 작업 목록·검색·완료 필터는 없습니다. 상단의 필터 예시는 독립 설계 문제이고, 현재 앱에서 그대로 실행된 기능으로 기록하지 않습니다.

제공 스타터의 상태 문구 변경 한 건에 목표 / 비목표 / 변경 파일 / 유지해야 할 동작 / 검증 항목을 추가합니다. apps/web/src/main.js의 실제 문구를 읽고 변경할 위치를 확정하며 API URL 표시와 기존 환경 설정은 유지합니다. 상단의 검색·필터 비교표는 독립 설계 과제입니다. AI가 무관한 리팩터링을 제안하면 별도 작업으로 분리합니다.

실습은 가능한 한 작은 변경으로 시작합니다. 변경 전에 현재 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 동작은 브라우저 확인으로 별도 기록합니다.

변경을 검토하는 방법

요청 전 범위 계약과 실제 diff를 나란히 저장합니다.
계획에 없던 파일 변경은 사유를 기록합니다. 승인되지 않은 변경은 사용자 변경과 구분한 뒤 해당 범위만 수정하며, 전체 파일을 강제로 되돌리지 않습니다.

검토할 때는 “코드가 그럴듯한가”가 아니라 요구사항과 diff를 비교합니다.

요청한 파일만 바뀌었는가
기존 규칙을 재사용했는가
새 dependency가 필요한가
오류 처리와 접근성을 놓치지 않았는가
검증 결과가 실제 실행 결과인가
되돌리기 쉬운 변경인가

실패와 위험

• 요청 한 줄만 전달
• “코드 정리도 해줘” 같은 무제한 범위
• dependency 추가를 자동 허용
• 기존 테스트 삭제 후 성공 처리
• 요구하지 않은 설계 변경

AI가 틀릴 수 있다는 추상적인 경고보다 실패를 발견할 구조를 만드는 것이 중요합니다. 작은 diff, 명확한 검증 명령, 사람 승인 지점이 있으면 모델이 달라져도 같은 작업 원칙을 유지할 수 있습니다.

완료 체크리스트

• 품질을 취향이 아니라 관찰 가능한 기준으로 설명
• 최소 변경 원칙과 무조건 작은 코드의 차이 설명
• 다음 AGENTS.md 회차에서 반복 지침을 저장소 규칙으로 승격할 준비

누적 기록과 실행 결과

이전 회차 ai-step-02-vibe에 남긴 기록을 시작점으로 사용합니다.

현재 구조는 기존 TaskFlow 소스와 package.json을 유지하고, 학습 기록은 새로 만드는 docs/ai-log.md에 누적합니다. 이 경로는 앱 실행 파일이 아닌 실습용 기록 위치입니다. 기존 동명 파일이 있으면 덮어쓰지 않고 회차 항목을 추가합니다. 앱 수정 파일은 저장소 탐색 후 계약에 확정하며 문서의 예시 경로를 실제 파일로 가정하지 않습니다.

Before는 해당 회차의 기록 항목이 없는 상태이고, 적용은 위 실습을 수행하며 관찰 내용을 채우는 과정입니다. After는 아래 항목의 근거와 미검증 범위가 남은 상태입니다. 문서 제목을 바꾸는 것만으로 기능 구현이 완료된 것은 아닙니다.

아래는 docs/ai-log.md에 추가하는 회차 항목 전체입니다. 앱 전체 코드가 아닌 개발 로그 양식이며, 빈칸은 직접 확인한 결과로 채웁니다.

체크포인트: ai-step-03-scope-quality
작업 요청 / 목표 / 비목표:
시작 상태 / 적용 지침:
허용 파일 / 실제 변경 파일:
계획 / diff 요약:
실행 명령 / 실제 결과 / 증거 위치:
미검증 항목 / 필요한 조건:
사람이 확인·수정한 내용:
승인 여부 / 승인 대상:
commit: 미생성 또는 실제 확인한 식별자
실패 지점 / 복구점 / 다음 행동:

검증란은 성공·실패·미실행을 구분합니다. 이 양식 자체는 실행 성공이나 사람 승인 증거가 아닙니다. 앱을 바꿨다면 diff → pnpm lint·pnpm build → 필요한 브라우저 확인 → 사람 검토 → 승인 → commit 순서로 기록합니다. 로그만 편집한 단계는 내용 대조가 검증이며 앱 테스트 통과로 부풀리지 않습니다.

완료 체크포인트

ai-step-03-scope-quality