AI Coding Workflow: AI가 코드를 반복 수정하는 문제 줄이기

Plan → Scoped Edit → Verify / Cursor Rules / 작은 diff / 수용 체크리스트 / 데드루프 대처

Cursor, Claude Code, Copilot Workspace로 기능을 작성할 때 이런 밤을 겪어본 적 있나요? AI가 A 파일을 고치면 테스트가 깨지고, B를 고치면 A가 망가집니다. "다시 해봐"라고 하면 어제까지 잘 돌아가던 코드까지 사라집니다. 이건 모델이 "덜 똑똑해서"가 아니라 반복 가능한 AI Coding Workflow가 없기 때문입니다. "계획·변경 범위·검증"을 독립된 단계로 나누지 않으면 Agent는 같은 잘못된 가정 위에서 무한 루프에 빠집니다.

이 글은 2026년 팀 현장에서 검증된 흐름을 소개합니다: 먼저 Plan하고 손을 대며, 각 라운드는 작은 범위만 바꾸고, Verify를 통과한 뒤에야 다음으로 간다. Cursor Rules와 Git의 작은 커밋을 함께 쓰면 "같은 버그를 8라운드 고치기"를 2라운드 이내로 압축할 수 있습니다. 클라우드 Mac의 MCP Server를 구축 중이거나 GitHub AI Agent 오픈소스 프로젝트를 고르는 중이라도 이 워크플로는 그대로 적용됩니다.

왜 AI는 끝없는 수정 루프에 빠지는가?

Agent 모드의 본질은 불확실한 환경에서 시행착오하는 것입니다. "로그인 버그 고쳐줘"만 말하면 OAuth 콜백인지, 세션 만료인지, 프론트 라우팅인지——모델은 알 수 없습니다. 가장 그럴듯한 답을 추측해 수정하고, 테스트를 돌리고, 실패하면 다른 방향을 시도합니다. 매 라운드 이전 라운드 가정의 일부가 뒤집히면서 diff는 점점 커지고, 컨텍스트에는 서로 모순되는 변경 기록이 쌓여 결국 "고칠수록 엉망" 상태에 이릅니다.

3가지 근본 원인

• 목표가 모호함——"성공의 모습"이 적혀 있지 않아 AI는 테스트 에러로 역추적할 수밖에 없음. 에러는 증상을 가리키는 경우가 많고 근본 원인을 가리키지는 않음
• 범위 통제 실패——한 작업에 10개 이상 파일을 건드림. 인증을 고치다 utils를 리팩터링하며 새 회귀를 만듦
• 수용 게이트 부재——"통과 후 다음"이라는 단단한 규칙이 없고, 실패 시 기본 전략이 "한 번 더 생성"이지 "롤백 후 범위 재정의"가 아님

경험 법칙: 3라운드 연속 "아니야, 다시 고쳐"라고 말하고 있다면 문제는 모델이 아니라 작업이 재 Plan되지 않았다는 점입니다.

3단계 워크플로: Plan → Scoped Edit → Verify

AI 협업을 3개의 건너뛸 수 없는 단계로 나누는 것이 더 강한 모델로 바꾸는 것보다 효과적입니다:

1. Plan(계획)——Plan 모드나 대화만으로 바꿀 파일, 건드리지 않을 것, 수용 명령(예: npm test -- auth)을 나열. 붙여넣기 가능한 "작업 명세"를 만들고, Agent에게 바로 고치게 하지 말고 명세를 확인한 뒤 진행
2. Scoped Edit(범위 제한 변경)——"src/auth/login.ts만 변경, 다른 파일 금지"를 명시. 라운드당 목표: 1~3개 파일, 순변경 200줄 미만
3. Verify(검증)——테스트, lint, 수동 스모크 테스트 실행. 통과 → 커밋 후 다음 작업. 실패 → 전체 에러 로그를 들고 Plan으로. "다시 해봐"가 아님

프롬프트 구조: 목표·경계·수용 기준을 한번에

복사 가능한 템플릿(괄호를 프로젝트에 맞게 교체):

## 목표
(한 문장: 로그인 후 3초 안에 대시보드 진입)

## 범위
- 변경 가능: src/auth/login.ts, src/auth/session.ts
- 변경 금지: 라우팅, 스타일, 기타 모듈

## 수용 기준
- npm test -- --grep "login"
- 수동: 잘못된 비밀번호 시 "아이디 또는 비밀번호가 올바르지 않습니다" 표시. 사용자 존재 여부 노출 금지

## 컨텍스트
- 현재 에러: (전체 stack trace 붙여넣기)
- 관련 규칙: Session은 Redis 저장, docs/auth.md 참고

이 구조는 Anthropic의 Claude Code 모범 사례가 강조하는 "명확한 경계"와 맞닿아 있습니다. 모델이 의도를 추측할 필요가 없고 회귀 면도 통제하기 쉽습니다.

Rules / Skills: 프로젝트 제약을 저장소에 기록

매 대화마다 "pnpm 쓴다, class 컴포넌트 안 쓴다, 테스트는 __tests__에 둔다"를 반복하면 토큰을 낭비하고 AI도 때로 지키고 때로 잊습니다. 약속을 .cursor/rules나 프로젝트 AGENTS.md에 적어두세요:

Rules(규칙)

지속적 제약: 네이밍 스타일, 금지 패턴, 커밋 전 실행할 명령. Cursor가 Agent 호출마다 자동 주입합니다.

Skills(스킬)

재사용 가능한 작업 대본. 예: "새 API 엔드포인트 추가" 단계 체크리스트. AI가 매번 프로젝트 구조를 처음부터 탐색하는 일을 줄입니다.

User Rules vs Project Rules

개인 취향("한국어로 답변")은 User에. 팀 합의("명시적 요청 없이는 backend 건드리지 않음")는 Project에. 협업 시 인식 차이를 막습니다.

Cursor Skills 문서를 참고해 고빈도 흐름을 고정하면 같은 유형 오류를 반복 수정하는 횟수가 눈에 띄게 줄어듭니다.

작은 diff와 Git 규율

AI는 큰 코드 블록을 한 번에 생성하는 데 능숙하지만, 사람이 큰 diff를 리뷰하는 능력에는 한계가 있습니다. 권장 사항:

• Agent 작업 1건 = 커밋 1개——메시지에 "Plan 요약"을 적어 git revert하기 쉽게
• 엉망이면 reset——큰 diff에 패치를 덧붙이지 말 것. git checkout -- .로 그린 테스트 지점으로 돌아가 더 작은 범위로 재시작
• 브랜치로 실험——클라우드 Mac이나 CI에서 Agent를 시험할 때 git worktree나 독립 브랜치로 "AI 난동"을 격리

컨텍스트 관리: Agent를 파일 바다에 빠뜨리지 마라

monorepo 전체를 Agent에 넘기는 것은 노이즈 속에서 신호를 찾게 하는 것과 같습니다. 더 효과적인 방법:

1. @filename으로 관련 파일 3~5개를 정확히 참조. "프로젝트 전체 스캔"은 피하기
2. 대규모 리팩터는 여러 Plan으로 분할: 먼저 인터페이스, 다음 구현, 마지막 테스트. 각 단계에서 Verify
3. 대화가 15라운드를 넘으면 새 대화를 열고 "작업 명세 + 현재 상태"를 붙여넣기. 역사 짐을 지고 계속 고치는 것보다 깔끔

4가지 전형적 데드루프와 돌파법

Agent로 복잡한 파이프라인(배치 문서 처리나 MCP 툴체인 등)을 짜고 있다면 "라우팅 → 실행 → 검증" 계층 분리는 PDF 일괄 인식 파이프라인에서 설명한 분류 아키텍처와 같은 패턴입니다: 먼저 판단하고 손을 대며, 모든 작업을 가장 느리고 오류 나기 쉬운 경로로 보내지 않는다.

자주 묻는 질문

1. 모델이 강할수록 반복이 줄어드나?——강한 모델은 "구문 수준" 오류를 줄이지만 범위 통제 실패로 인한 회귀는 모델 등급과 무관합니다. Workflow가 핵심입니다
2. 팀은 어떻게 통일하나?——Rules, PR 템플릿, 수용 체크리스트를 저장소에 둡니다. Code Review에서 "작은 커밋인지" 확인
3. Agent에 전부 맡길 수 있나?——실행 자동화는 가능하지만 Plan과 Verify는 특히 결제·인증·데이터 마이그레이션에서 사람 게이트를 권장
4. TDD와 어떻게 맞추나?——먼저 AI에게 실패 테스트 작성(Plan), 다음 구현(Scoped Edit), 그린 후 리팩터——3단계와 자연스럽게 맞습니다

제목으로 돌아가면: AI 반복 수정을 줄이는 것은 "여러 번 시도"가 아니라 Plan → Scoped Edit → Verify 규율, 명확한 프롬프트, 저장소 안 Rules, 그리고 git revert할 용기에 달려 있습니다. 흐름을 고정하면 시간을 "N번째 패치"가 아니라 "문제 정의"에 쓸 수 있습니다.