AI 코딩 에이전트 실전: TaskFlow 기능 요청부터 검증·승인·커밋까지

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

이번 회차에서는 지금까지 배운 원칙을 한 번에 적용합니다. 목표는 AI가 코드를 많이 작성하게 만드는 것이 아니라, 사람이 요청한 작은 기능이 검증 가능한 상태로 저장소에 들어가는 전체 흐름을 완성하는 것입니다.

TaskFlow 누적 실습: 최종 작업 흐름

이어서 읽기: ChatGPT와 Codex로 워드프레스 블로그 자동 업로드 파이프라인 만들기. 누적 작업 기록은 docs/ai-log.md에 회차별로 추가합니다. 새로 진입하면 실제 개발환경 시작 ZIP을 별도 폴더에 풉니다. 이 앱에는 상태 문구와 API URL 표시가 있으며 작업 목록·검색·완료 필터는 없습니다. 상단의 필터 예시는 독립 설계 문제이고, 현재 앱에서 그대로 실행된 기능으로 기록하지 않습니다.

이번 회차에서는 지금까지 배운 원칙을 한 번에 적용합니다. 목표는 AI가 코드를 많이 작성하게 만드는 것이 아니라, 사람이 요청한 작은 기능이 검증 가능한 상태로 저장소에 들어가는 전체 흐름을 완성하는 것입니다.

요구사항 확인
→ 현재 저장소 상태 확인
→ 수정 범위 계약
→ AI 구현
→ git diff 검토
→ lint/test/build
→ 오류 수정
→ 사람이 승인
→ commit
→ 작업 로그 저장

1. 작업 시작 전에 기준점 만들기

git status --short
git branch --show-current
git log --oneline -5

기존 변경이 있다면 AI 작업과 섞지 않습니다. 현재 수정사항이 어떤 작업에서 생겼는지 모르는 상태에서는 새 기능을 시작하지 않는 편이 좋습니다.

2. 기능 요청 작성

실제 시작 파일은 개발환경 최종 체크포인트의 apps/web/src/main.js입니다. status.textContent에 있던 ‘개발환경 스타터가 실행 중입니다.’를 ‘TaskFlow 개발환경 준비 완료’로 바꾸는 한 곳의 문구 수정으로 연습합니다. 파일을 읽어 시작 문구가 일치할 때만 바꾸고, 다른 앱 상태라면 먼저 요청 범위를 조정합니다. 이는 Next.js의 가상 파일이나 새 기능 구현 결과를 주장하는 예제가 아닙니다.

목표:
TaskFlow 스타터의 상태 문구를 ‘TaskFlow 개발환경 준비 완료’로 변경

수정 허용:
- apps/web/src/main.js의 status.textContent 문구 1곳

수정 금지:
- package.json
- 인증/배포 설정
- 무관한 공통 component

완료 조건:
- 지정 상태 문구가 브라우저에 표시됨
- 기존 기능 회귀 없음
- 정의된 lint/build 확인과 브라우저 회귀 검증
- diff 설명 가능

• 작업 요청 원문
• AI가 받은 저장소 규칙
• 계획
• 변경 파일 목록
• 주요 diff 요약
• 실행한 검증 명령
• 테스트 결과
• 사람이 수정한 내용
• 최종 승인 여부
• commit/checkpoint
• 실패 시 복구 방법

3. diff를 먼저 읽기

git diff --stat
git diff

파일 수가 예상보다 많으면 구현 내용을 읽기 전에 범위가 커진 이유부터 확인합니다. AI가 만든 설명이 아니라 실제 diff가 검토 대상입니다.

4. 검증

프로젝트에 정의된 실제 script를 확인한 뒤 필요한 검증을 실행합니다.

pnpm lint
pnpm build

실행하지 못한 검증은 통과로 기록하지 않습니다. 외부 서비스, 모바일 실기기, Production 환경이 필요하다면 해당 범위를 별도 미검증으로 남깁니다.

5. 승인과 commit

AI가 자동으로 할 수 있는 것과 사람이 승인해야 하는 것을 구분합니다.
읽기/분석/테스트는 자동화 가능 범위를 넓게 잡을 수 있지만, 새 dependency·대규모 삭제·외부 서비스 쓰기·배포·비밀정보 접근은 별도 승인 대상으로 둡니다.

사람이 변경 목적과 위험을 이해한 뒤 승인합니다. commit 메시지는 AI가 작성했는지보다 변경 내용과 맞는지가 중요합니다.

git add <검토한 파일>
git diff --cached
git commit -m "feat: TaskFlow 기능 설명"

실패 시 처리

• Before: AI에게 기능 요청 → 결과만 확인
• After: 요청 계약 → 작업 상태 → 변경 증거 → 검증 → 승인 → 복구 가능한 commit

최종 개발 로그

요청:
허용 파일:
변경 파일:
검증 명령:
검증 결과:
미검증:
사람 검토:
승인:
commit:

이 기록은 특정 AI 제품에 종속되지 않습니다. 모델이나 도구를 바꾸더라도 같은 완료 기준을 재사용할 수 있습니다.

완료 체크리스트

• TaskFlow AI-assisted 개발 로그 최종본.
• AI 사용 여부와 상관없이 다른 개발자가 변경 이유와 검증 근거를 따라갈 수 있어야 합니다.

누적 기록과 실행 결과

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

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

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

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

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

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

완료 체크포인트

ai-step-11-final-delivery

이 체크포인트로 AI 코딩 도구 과정의 핵심 학습을 마무리합니다. 이후 업무·자동화 과정에서는 한 번의 코드 수정이 아니라 파일·API·Webhook·예약 실행이 이어지는 운영 자동화로 범위를 확장합니다.