AI 에이전트가 실패하는 진짜 이유 모델 성능보다 상태 관리가 먼저다

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

이번 주제: AI 에이전트가 실패하는 진짜 이유 모델 성능보다 상태 관리가 먼저다.

선택: 연재 프로젝트와 전체 자료

연재 프로젝트를 이어 만드는 분을 위한 자료입니다. 이 글의 개념과 예제만 찾으셨다면 필요한 파일과 실행 방법만 펼쳐보세요.

TaskFlow 누적 적용

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

대기 → 작업 중 → 검증 실패 → 수정 중 → 검증 완료 → 승인.
응답이 끊겼을 때는 git status·diff·테스트 결과를 먼저 확인한 뒤 상태를 판정합니다.

변경 전후에는 Git을 기준으로 실제 결과를 확인합니다.

git status --short
git diff --stat
git diff

테스트나 build를 실행했다면 성공 여부뿐 아니라 어떤 명령을 실행했는지도 로그에 남깁니다. 외부 서비스가 필요한 검증은 실제로 실행하지 못했다면 미검증으로 표시합니다.

평가와 중단 기준

• “완료했습니다”라는 답변만 믿음
• 실행하지 않은 테스트를 성공으로 기록
• 중단 후 처음부터 다시 생성
• 이미 수정한 파일을 다시 덮어씀

에이전트가 더 많은 작업을 할 수 있다는 이유만으로 계속 진행하지 않습니다. 완료 조건을 충족했다면 멈추고 사람이 diff를 확인하는 것이 다음 단계입니다.

완료 체크리스트

• 상태 관리라는 용어를 앱 상태관리 라이브러리와 혼동하지 않게 설명
• 실제 저장소 증거를 기준으로 재개
• 다음 회차의 구조화된 에이전트 워크플로우로 연결

누적 기록과 실행 결과

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

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

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

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

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

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

완료 체크포인트

ai-step-06-state-recovery