AI-assisted 프론트엔드 PR workflow 사례 정리
AI 코딩 에이전트를 잘 쓴다는 말은 아직 너무 넓습니다. 실무에서 중요한 것은 “얼마나 빨리 만들었는가”보다 어떤 범위 안에서, 어떤 검증을 통과시켜, 어떤 기록을 남겼는가입니다.
이번 글은 Next.js 기반 프론트엔드 프로젝트에서 AI-assisted PR workflow를 운영하는 사례를 정리합니다. 더 넓은 배경은 Context Contract 플레이북, PR 품질 기준은 Harness 기반 PR 품질 운영 가이드와 이어집니다.
1단계: 입력 계약을 먼저 만든다
AI에게 바로 구현을 맡기면 변경 범위가 쉽게 번집니다. 먼저 아래 네 가지를 고정합니다.
## Task Contract
- Goal: archive page 검색 UX 개선
- Scope: app/archives, app/api/posts, app/lib/posts만 수정
- Non-goals: 디자인 시스템 전면 개편, 라우팅 구조 변경
- Verification: pnpm check, pnpm build이 입력 계약은 에이전트를 통제하기 위한 문서이면서, 리뷰어에게도 “왜 이 파일만 바뀌었는지”를 설명하는 근거가 됩니다.
2단계: 변경 범위를 작게 나눈다
AI-assisted PR은 작을수록 강합니다. 한 번에 “검색 UX 개선 + 디자인 변경 + 캐시 개선 + 테스트 추가”를 묶으면 리뷰가 흐려집니다.
권장 분해 방식은 다음과 같습니다.
| PR 유형 | 예시 | 검증 |
|---|---|---|
| 구조 정리 | post metadata parser 분리 | unit/build |
| UX 개선 | empty/loading/error 상태 추가 | browser smoke |
| 성능 개선 | cache key와 revalidate 정리 | build/log |
| 문서화 | README 운영 흐름 보강 | link check |
이렇게 나누면 AI가 만든 변경도 사람이 리뷰 가능한 단위로 남습니다.
3단계: 리뷰 로그를 PR 본문에 남긴다
AI 작업은 “사용했다”는 사실보다 검증 로그가 중요합니다.
## AI-assisted Review Log
- Context: archive search state and post metadata parser
- Human decisions: keep /archives as canonical route, preserve /posts redirect UX
- Checks:
- pnpm check
- pnpm build
- browser smoke: search, tag filter, empty state
- Risks:
- Pagefind index generation runs postbuild이 로그는 나중에 면접에서 강력한 자료가 됩니다. 단순한 사용기가 아니라, 품질 통제 경험으로 설명할 수 있기 때문입니다.
4단계: 실패를 학습 데이터로 남긴다
AI-assisted workflow의 핵심은 실패를 지우지 않는 것입니다.
- 어떤 명령이 실패했는지
- 원인이 코드인지 환경인지
- 어떤 검증으로 다시 통과했는지
- 다음 PR에서 어떤 guardrail을 추가할지
이 구조는 AI 디버깅 런북, 변경 실패율(CFR) 운영법과 함께 쓰면 운영 체계로 확장됩니다.
실제 운영 기준
팀에서 바로 적용하려면 아래 규칙부터 시작하세요.
- AI가 수정할 파일 범위를 먼저 선언한다.
- 구현 전 non-goal을 적는다.
- 검증 명령을 PR 본문에 고정한다.
- 실패 로그와 최종 통과 로그를 둘 다 남긴다.
- 리뷰어는 코드 스타일보다 scope drift를 먼저 본다.
AI는 작성 속도를 올려주지만, 제품 품질은 workflow가 결정합니다. 프론트엔드 개발자의 차별점은 여기서 만들어집니다.