핵심 요약
AI coding agent는 빠르게 코드를 바꾸는 도구입니다. 하지만 빠르다는 이유만으로 merge 권한까지 맡기면 안 됩니다. 좋은 워크플로우는 작업 범위 정의, 저장소 탐색, 짧은 계획, 코드 수정, 테스트 실행, diff 리뷰, 사람의 최종 판단으로 이어져야 합니다.
이미지는 agent가 혼자 코드를 끝내는 구조가 아니라, 사람과 함께 검증 루프를 도는 구조를 보여줍니다. 중요한 것은 자동화 자체가 아닙니다. 변경 내용을 작게 만들고, 검증 증거를 남기고, 되돌릴 수 있게 만드는 것입니다.
왜 워크플로우가 필요한가
AI coding tool은 파일을 읽고, 수정하고, 명령을 실행하고, 변경 이유를 설명할 수 있습니다. 이 능력은 매우 유용하지만 실패 방식도 달라집니다. 자동완성은 보통 개발자가 한 줄씩 받아들이지만, coding agent는 여러 파일을 연속으로 바꿀 수 있습니다. 리뷰어가 첫 번째 변경을 보기 전에 열 번째 변경까지 만들어질 수 있다는 뜻입니다.
그래서 prompt보다 workflow가 더 중요합니다. 좋은 prompt는 한 번의 답변을 개선합니다. 좋은 workflow는 모든 답변을 검증 가능한 상태로 만듭니다.
OpenAI Codex 같은 coding agent 흐름에서도 핵심은 agent에게 모든 판단을 맡기는 것이 아닙니다. 명확한 작업을 주고, 저장소를 읽게 하고, 범위를 제한한 뒤, 테스트와 diff로 결과를 확인하는 방식이 실전적입니다.
1. 작은 작업 계약부터 쓴다
나쁜 요청은 이런 형태입니다.
대시보드를 개선해줘.
좋은 요청은 작업 계약에 가깝습니다.
대시보드 empty state 레이아웃을 수정해줘.
범위: dashboard page와 기존 empty-state component만.
제외: routing, API contract, 전역 디자인 변경.
검증: 기존 frontend test와 desktop/mobile screenshot.
작업 계약에는 다섯 가지가 들어가야 합니다.
- 기대 결과가 무엇인가?
- 어떤 파일이나 영역이 범위 안인가?
- 어떤 영역은 건드리면 안 되는가?
- 어떤 검증 명령으로 확인할 것인가?
- 완료 보고에 무엇을 포함할 것인가?
큰 저장소일수록 이 기준이 중요합니다. 범위가 없으면 agent는 그럴듯한 주변 패턴을 따라가다가 전혀 다른 기능을 바꿀 수 있습니다.
2. 컨텍스트는 충분히, 그러나 관련 있게 준다
좋은 컨텍스트는 issue 내용, 에러 로그, screenshot, 실패한 test, design note, API 예시, naming convention입니다. 반대로 너무 많은 설명은 noise가 됩니다. agent가 먼저 저장소를 읽고, 필요한 파일과 제약을 파악하게 하는 편이 낫습니다.
예를 들면 다음과 같이 시작할 수 있습니다.
먼저 관련 파일을 읽고 현재 동작과 변경 가능성이 높은 영역을 요약해줘.
그 다음 요청을 만족하는 가장 작은 수정만 적용해줘.
이 과정은 형식적인 절차가 아닙니다. agent가 자신 있게 엉뚱한 문제를 푸는 것을 막아 줍니다.
3. 수정 전에 짧은 계획을 요구한다
한 줄 수정에는 계획이 필요 없습니다. 하지만 shared component, database query, authentication, payment, deployment config, generated content를 건드린다면 짧은 계획이 필요합니다.
좋은 계획은 구체적입니다.
- 실패하는 component와 test를 읽는다.
- 기존 shared helper가 해당 상태를 지원하는지 확인한다.
- API를 바꾸지 않고 component만 수정한다.
- 집중된 test 하나를 추가하거나 갱신한다.
- 관련 test command를 실행한다.
나쁜 계획은 모호합니다.
- 코드를 분석한다.
- 품질을 개선한다.
- 전체적으로 테스트한다.
계획은 리뷰어가 불필요한 확장을 초기에 발견할 수 있을 만큼 작고 명확해야 합니다.
4. 테스트를 통제 장치로 쓴다
agent 작업을 안전하게 늘리는 가장 좋은 방법은 검증 비용을 낮추는 것입니다. 테스트가 없으면 agent도 도움은 됩니다. 다만 그때는 사람이 더 많은 시간을 들여 동작을 직접 확인해야 합니다.
유용한 검증 기준은 다음과 같습니다.
- 순수 함수와 validation logic을 위한 unit test
- API 동작을 위한 integration test
- TypeScript나 typed Python의 type check
- formatting과 import rule을 위한 lint
- framework build check
- UI 회귀를 확인하는 browser screenshot
- 자동화가 어려운 버그의 수동 재현 절차
agent가 단순히 “테스트 통과”라고 말하는 것만으로는 부족합니다. 어떤 명령을 실행했는지, 결과가 무엇인지, 실행하지 못했다면 왜 못 했는지를 남겨야 합니다.
5. 설명보다 diff를 리뷰한다
agent summary는 유용하지만, 진짜 기준은 diff입니다. 리뷰어는 요청과 무관한 formatting churn, 숨은 동작 변경, 넓은 dependency upgrade, 삭제된 error handling, public API 변경, 구현 세부사항만 확인하는 test, commit하면 안 되는 generated file을 확인해야 합니다.
가장 좋은 질문은 단순합니다.
변경된 모든 줄이 작업 계약과 연결되는가?
연결되지 않는 줄이 있다면 작업을 나누거나, agent에게 관련 없는 변경을 되돌리게 해야 합니다.
6. 위험 판단은 사람이 소유한다
보안, 결제, 개인정보, 데이터 삭제, migration, 법률·의료·금융 주장, production deployment와 관련된 변경은 더 강한 사람 리뷰가 필요합니다. agent는 초안을 만들고 테스트를 도울 수 있지만, 위험의 최종 책임자가 되어서는 안 됩니다.
고위험 변경에는 이런 gate를 둡니다.
- merge 전 human reviewer 필수
- rollback note 작성
- migration up/down 확인
- log redaction 검토
- production 전 staging 확인
이 절차는 느려 보일 수 있습니다. 하지만 production에서 자신감 있는 자동화 실수를 추적하는 것보다 훨씬 빠릅니다.
바로 쓸 수 있는 Agent Prompt
이 저장소에서 작업해줘.
목표: profile settings 저장 흐름 실패를 수정.
범위: profile settings page, 관련 API handler, 기존 tests.
제외: auth 변경, database schema 변경, visual redesign.
먼저 관련 파일을 읽고 원인 후보를 요약해줘.
그 다음 작은 patch를 적용해줘.
집중된 test command를 실행해줘.
변경 파일, 검증 결과, 남은 위험을 보고해줘.
이 prompt는 agent에게 일할 자유를 주지만, 시스템 전체를 재설계할 자유까지 주지는 않습니다.
흔한 실수
첫 번째 실수는 한 번에 너무 많이 맡기는 것입니다. “앱을 현대적으로 바꿔줘”는 리뷰하기 어려운 diff를 만들기 쉽습니다. navigation, typography, form, performance, test처럼 나누어야 합니다.
두 번째 실수는 실행하지 않은 코드를 받아들이는 것입니다. agent output은 검증이 아니라 제안입니다. 사람이 만든 코드와 같은 기준을 통과해야 합니다.
세 번째 실수는 기존 helper가 있는데도 새 패턴을 만들게 두는 것입니다. local pattern을 우선하라고 지시해야 프로젝트 일관성이 유지됩니다.
네 번째 실수는 실행하지 못한 테스트를 숨기는 것입니다. 테스트가 너무 느리거나, 환경이 없거나, unrelated failure가 있다면 그대로 기록해야 합니다. “통과”와 “실행하지 않음”은 전혀 다릅니다.
함께 보면 좋은 글
- AI Agent Workflow 2026
- Prompt Engineering Checklist
- RAG Evaluation Checklist
- OpenAI Codex documentation
최종 체크리스트
[ ] 작업 범위가 좁다.
[ ] agent가 수정 전에 저장소를 읽었다.
[ ] 범위와 제외 범위가 적혀 있다.
[ ] 검증 명령이 정해져 있다.
[ ] diff를 줄 단위로 리뷰했다.
[ ] 실행하지 못한 테스트와 남은 위험을 보고했다.
[ ] merge 결정은 사람이 한다.
AI coding agent는 engineering judgment를 대체하지 않습니다. 반복 구현을 빠르게 처리하고, 리뷰 가능한 증거를 더 쉽게 만들기 위한 도구입니다. 가장 큰 효과를 보는 팀은 agent의 작업을 작고, 관찰 가능하고, 되돌릴 수 있게 만드는 팀입니다.
자주 묻는 질문
이 글은 언제 먼저 적용하면 좋나요?
새 도구를 바로 도입하기 전, 반복 업무와 검증 기준이 이미 있는지 확인할 때 먼저 적용하면 좋습니다.
초보자가 가장 먼저 확인할 부분은 무엇인가요?
처음에는 모델 성능보다 입력 데이터, 검증 기준, 실패 시 복구 방법을 먼저 정하세요. AI workflow는 자동화보다 검증 설계가 먼저입니다.
더 찾아볼 때 어떤 키워드를 쓰면 좋나요?
추가 검색할 때는 “AI Coding Agent Workflow: 코드 품질을 잃지 않고 에이전트 쓰는 법” 같은 핵심 문구와 evaluation, workflow, guardrail, structured output, agent 같은 실무 키워드를 조합해 보세요.
Leave a comment