AI 코딩 에이전트의 성과는 “더 길게 시키기”보다 프로젝트 맥락을 정리하고, 일을 작게 나누고, 매 단계의 검증과 되돌림을 정하는 데서 갈립니다

데모는 빨리 나오는데, 왜 다음 날 고치기 어려울까? 🤔

AI 코딩 도구를 처음 써보면 마법 같은 순간이 있어요. “로그인 화면 만들어줘”라고 입력했는데 화면이 나오고, 버튼을 누르면 API까지 호출되는 데모가 금방 만들어지죠. 그런데 그다음 기능을 하나 더 붙이려 하면 이야기가 달라집니다. 이전 코드가 어떤 가정을 했는지 모르겠고, 도구가 같은 파일을 다시 건드리면서 테스트가 깨지고, 결국 사람이 처음부터 읽어야 하는 상태가 되기 쉬워요.

이 문제는 모델이 코드를 못 써서만 생기지 않습니다. 도구에게 프로젝트의 현재 상태와 작업의 끝 조건을 충분히 주지 않았기 때문인 경우가 많아요. Google Cloud가 AI 코딩 보조 도구를 실제 개발 업무에 적용하며 정리한 실천도 비슷한 순서를 권합니다. 먼저 코드베이스를 문서화하고, 큰 작업은 계획으로 나누고, 필요한 단계에서 사람의 승인을 받으라는 내용이에요.

이 글의 결론은 단순합니다. AI 코딩 에이전트를 ‘한 번에 앱을 만드는 버튼’으로 쓰지 말고, 작은 작업을 검증 가능한 단위로 처리하는 동료로 다뤄야 합니다. 아래 다섯 단계는 특정 제품의 기능이 아니라, Claude Code·Gemini CLI·IDE 에이전트처럼 저장소를 읽고 수정하는 도구에 공통으로 적용할 수 있는 흐름입니다.

1. 먼저 결과물이 아니라 현재 상태를 설명하세요 📍

첫 요청에 기능 설명만 넣으면 에이전트는 빈 프로젝트를 상상하기 쉽습니다. 실제 저장소에는 이미 라우팅 규칙, 데이터 모델, 환경 변수, 배포 방식, 사용자 변경이 있죠. 기능을 만들기 전에 아래 네 가지를 짧게 정리해 주세요.

• 목적: 사용자가 이 변경 뒤에 무엇을 할 수 있어야 하나요?
• 현재 상태: 관련 파일, 이미 작동하는 흐름, 건드리면 안 되는 사용자 변경은 무엇인가요?
• 경계: 새 의존성, DB migration, 배포, 외부 API 호출 중 이번 작업에서 하지 않을 것은 무엇인가요?
• 검증: 어떤 명령·화면·응답이 성공을 증명하나요?

Anthropic이 공개한 내부 팀 사례에서도 문서를 읽어 런북과 개요를 만들고, 그 문서를 실제 문제 해결의 컨텍스트로 쓰는 방식이 나옵니다. 중요한 건 문서를 많이 넣는 게 아니라, 이번 작업의 판단을 바꾸는 정보만 남기는 거예요. “이 저장소는 Next.js다”보다 “이 라우트는 서비스 역할 키를 쓰므로 브라우저 코드에서 호출하면 안 된다”가 훨씬 유용합니다.

2. 큰 요청을 ‘한 번 검증할 수 있는 일’로 쪼개세요 🧩

“결제 기능 전부 만들어줘”, “관리자 화면 리팩터해줘”처럼 큰 요청은 계획처럼 들리지만 실제로는 여러 판단을 한 문장에 숨긴 상태입니다. AI가 한 번에 수정하면 어느 파일이 문제를 만들었는지, 무엇을 되돌려야 하는지 알기 어려워집니다.

대신 한 작업은 다음 질문 하나에만 답하도록 나눕니다.

작업 단위	좋은 끝 조건	나쁜 끝 조건
데이터 모델	migration이 적용되고 새 행을 읽을 수 있음	DB 관련 기능 완료
API	정상 입력은 201, 잘못된 입력은 400	API 만들어줘
화면	빈 상태·로딩·오류 상태가 보임	대시보드 예쁘게
자동화	dry-run은 외부 쓰기 없이 결과를 출력	매일 알아서 돌게

Google Cloud의 실천 가이드도 작은 함수 수정에는 인라인 보조가 맞고, 여러 파일을 바꾸는 큰 작업에는 에이전트와 계획이 맞는다고 구분합니다. 도구를 고르는 기준은 “모델이 얼마나 똑똑한가”가 아니라 작업의 영향 범위와 되돌리기 비용이에요.

3. 매 단계에 기대 결과와 확인 방법을 붙이세요 ✅

AI가 수정한 뒤 “완료했어요”라고 말하는 것과 실제로 동작하는 것은 다른 사실입니다. 그래서 프롬프트나 작업 카드에 결과뿐 아니라 관찰 방법을 같이 적어야 해요.

예를 들어 콘텐츠 수집 파이프라인을 고친다면 이렇게 쓸 수 있습니다.

목표: 오늘의 소재 큐를 근거 패킷으로 저장한다.
범위: Phase 2만 수정한다. 초안·발행·배포는 건드리지 않는다.
기대 결과: 실제 실행은 패킷을 저장하고, --dry-run은 DB에 쓰지 않는다.
검증: 기존 날짜 큐로 Phase 2 dry-run을 실행해 소스 파일·패킷 날짜가 같은지 확인한다.

여기서 핵심은 “테스트를 추가하라”는 말이 아닙니다. 누가 봐도 같은 결론에 도달할 관찰을 미리 합의하는 것이에요. 파일이 생겼다는 사실, API 응답, migration 결과, 실제 CLI 출력처럼 작업에 맞는 가장 작은 증거를 고르면 됩니다.

4. 체크포인트를 만들고, 불확실하면 그 자리에서 멈추세요 ⏸️

자율 실행이 유용한 이유는 사람이 반복 작업을 덜 하기 때문이지, 사람이 모든 판단을 포기해서가 아닙니다. Anthropic의 사례에는 변경 전 커밋을 남기고 에이전트의 시도를 받아들이거나 다시 시작하는 방식, 테스트 주도 흐름으로 이끄는 방식이 소개됩니다.

혼자 만드는 프로젝트에서도 같은 원칙을 쓸 수 있어요.

1. 작업 전 현재 상태를 커밋하거나 별도 브랜치·백업으로 남깁니다.
2. 에이전트에게 한 작업 단위만 맡깁니다.
3. 검증이 통과하면 다음 단위로 갑니다.
4. 원문 근거·권한·DB 변경처럼 되돌리기 어려운 판단이 나오면 멈추고 사람이 확인합니다.
5. 예상과 다르면 “더 고쳐줘”를 반복하기보다, 마지막으로 통과한 상태로 돌아가 문제를 다시 작게 나눕니다.

이 흐름은 속도를 늦추는 절차처럼 보일 수 있어요. 하지만 30분 동안 넓게 고친 뒤 실패 원인을 찾는 시간보다, 5분마다 작은 결과를 확인하는 편이 보통 더 싸고 안전합니다.

5. 첫 실험은 기능이 아니라 ‘검증 루프’로 하세요 🔁

처음부터 서비스 전체를 AI에게 맡길 필요는 없습니다. 다음 중 하나만 골라 30분 실험을 해보세요.

• 테스트가 없는 함수 하나에 입력·출력 사례를 정리하고 테스트를 먼저 추가한다.
• 오래된 문서의 링크 세 개를 확인하고, 변경이 필요한 문장만 수정한다.
• 반복되는 수작업 하나를 dry-run CLI로 바꿔 결과를 출력하게 한다.
• 버그 하나를 재현한 뒤, 원인 후보와 검증 명령을 분리해 에이전트에게 맡긴다.

실험이 끝나면 속도보다 세 가지를 기록합니다. 사람이 수정한 횟수, 검증 실패 이유, 다음에도 재사용할 컨텍스트예요. 이 기록이 쌓이면 에이전트의 프롬프트는 길어지는 대신 더 정확해지고, 프로젝트마다 같은 실수를 반복할 가능성은 줄어듭니다.

같은 기능 요청도 맡기는 방식이 달라야 해요 🧭

AI 코딩 도구를 쓸 때 가장 흔한 혼란은 “이 작업은 에이전트에게 맡겨도 되는가?”입니다. 아래 표처럼 결과물이 아니라 실수의 비용과 검증 난이도로 나누면 판단이 쉬워져요.

상황	에이전트에게 줄 수 있는 범위	사람이 먼저 정할 것	완료 확인
새 화면의 정적 UI	컴포넌트 초안, 기존 토큰 재사용	화면의 목적과 필수 상태	로컬 화면·빈 상태 확인
API 응답 형식 변경	타입·호출부 탐색, 테스트 초안	호환성 정책과 버전 경계	기존/새 요청 테스트
DB migration	읽기 전용 영향 분석, SQL 초안	데이터 보존·롤백·배포 시점	스테이징 migration·백업 확인
반복 문서 수정	관련 문장 탐색, 제안 diff	법무·브랜드·사실 검토	링크·용어·최종 diff 검토
결제·권한·삭제	영향 분석과 테스트 제안까지만	정책·승인·실제 실행	사람이 실행하고 결과 기록

즉 AI에게 “할 수 있는지”를 묻기보다, 잘못됐을 때 누가 피해를 보고 얼마나 빨리 되돌릴 수 있는지를 먼저 묻는 편이 좋아요. 되돌리기 쉬운 초안은 넓게 맡길 수 있지만, 운영 데이터나 권한처럼 한 번의 실수가 큰 영역은 분석과 테스트 제안까지만 맡기는 게 안전합니다.

잘 안 맞는 경우와 주의점 ⚠️

잘 안 맞는 경우와 주의점 ⚠️

AI 코딩 에이전트가 모든 작업에 같은 효과를 내지는 않습니다. 제품 요구가 아직 정해지지 않았거나, 권한·개인정보·결제·운영 데이터처럼 실수 비용이 큰 영역은 먼저 사람이 정책과 경계를 정해야 해요. 테스트가 없는 오래된 코드베이스도 한 번에 넓게 고치기보다, 읽기 전용 분석과 작은 재현부터 시작하는 편이 낫습니다.

또 “AI가 만들었으니 누가 책임지나”가 모호해지면 품질이 떨어집니다. 자동화가 조사·초안·반복 작업을 맡았더라도, 무엇을 배포하고 어떤 사실을 독자나 사용자에게 보여줄지는 사람이 확인해야 합니다. 도구의 속도는 책임의 속도를 대신하지 못해요.

잡돌쌤의 한마디 💬

바이브코딩의 진짜 실력은 멋진 한 줄 프롬프트가 아니라, AI가 틀려도 프로젝트가 망가지지 않는 작업장을 만드는 데서 나옵니다. 컨텍스트를 적고, 일을 작게 나누고, 검증을 붙이고, 되돌릴 수 있게 만드는 것. 이 네 가지가 갖춰지면 어떤 에이전트를 쓰더라도 결과가 훨씬 예측 가능해집니다.

오늘은 새 기능을 만들지 말고, 지금 가장 자주 고치는 파일 하나를 고르세요. 그 파일에 “이번 변경의 성공 조건”을 세 줄로 적고, AI에게 그 범위만 맡겨보면 됩니다. 검증이 통과했다면 다음 단위로 가고, 아니라면 거기서 멈추는 것. 그 작은 습관이 AI 코딩을 데모 만들기에서 제품 만들기로 바꿔줍니다.