AI 에이전트가 코드를 작성하는 시대가 왔다. GitHub Copilot Agent Mode, Claude Code, Cursor 등 다양한 도구가 등장하면서 “에이전트에게 맡기면 알아서 해준다”는 기대가 커지고 있다.
하지만 실제로 에이전트에게 자유롭게 맡겨본 경험이 있는 개발자라면 알 것이다. 어느 순간부터 내 프로젝트인데 내가 이해하지 못하는 코드가 늘어나고, 새로운 기능을 붙이려 해도 기존 코드가 어떻게 돌아가는지 파악이 안 되는 상황이 찾아온다는 것을.
이 글은 그런 시행착오를 겪은 뒤 내린 결론이다. 에이전트의 생산성을 활용하되, 프로젝트의 주도권은 반드시 개발자가 쥐고 있어야 한다는 방법론을 정리한다.
문제 인식: 에이전트가 만든 기술 부채
에이전트에게 “이거 만들어줘”라고 하면 놀랍도록 빠르게 결과물이 나온다. 처음에는 생산성이 폭발적으로 올라간 것 같은 착각이 든다.
하지만 이걸 반복하면 다음과 같은 문제가 발생한다:
- 개발자가 자기 프로젝트를 이해하지 못한다 — 에이전트가 만든 코드의 구조와 흐름을 개발자가 모른다.
- 새 기능 추가가 어려워진다 — 기존 코드를 파악하는 데만 시간이 소비된다.
- 프로젝트가 헛돈다 — 에이전트마다 다른 스타일로 코드를 붙이면서 일관성이 깨진다.
- 확인도 어렵다 — 에이전트가 뭘 했는지 추적할 수가 없다.
이 모든 것이 기술 부채다. 이해 없는 속도는 결국 빚이 된다.
핵심 철학: 개발자가 반드시 주도권을 쥐어야 한다
이 방법론의 대원칙은 단순하다.
에이전트의 모든 행동은 개발자가 이해하고, 확인하고, 승인해야 한다.
에이전트는 팀원이다. 유능하지만 방향 없이 움직이면 프로젝트를 망칠 수 있는 팀원. 그래서 개발자는 아키텍트이자 팀 리더 역할을 해야 한다. 에이전트가 어떤 행동을 하고 있는지 개발자는 반드시 이해하고 있어야 하고, 개발자가 생각하는 대로 에이전트가 움직여야 한다.
마치 한 팀이 같은 목표를 위해 움직여야 하는 것처럼. 팀원 하나가 이상한 방향으로 가면 다른 팀원이 고통받는 것처럼, 에이전트도 마찬가지다.
방법론: Git + GitHub를 활용한 에이전트 워크플로우
이 방법론의 핵심 도구는 Git과 GitHub이다. Git은 에이전트의 모든 행동을 기록하는 수단이고, GitHub는 프로젝트를 체계적으로 관리하는 플랫폼이다.
전체 프로세스 개요
작업 내용 합의"] B["2. GitHub Issue 생성
Project 보드에 등록"] C["3. 이슈 기반 브랜치 생성
이슈 1개 = 에이전트 1개 = 브랜치 1개"] D["4. 에이전트 작업 수행"] E["5. 사용자 확인 및 승인"] F["6. 커밋"] G{"작업 완료?"} H["7. Pull Request 생성"] I["8. 사용자 리뷰 → 머지"] J["9. 이슈 클로즈"] A --> B --> C --> D --> E --> F --> G G -- "아직 남음" --> D G -- "완료" --> H --> I --> J style A fill:#1a3a5c,stroke:#4a9eff,color:#e0e0e0 style B fill:#1a3a5c,stroke:#4a9eff,color:#e0e0e0 style C fill:#1a3a5c,stroke:#4a9eff,color:#e0e0e0 style D fill:#2d1a4e,stroke:#9b59b6,color:#e0e0e0 style E fill:#1a4a3a,stroke:#2ecc71,color:#e0e0e0 style F fill:#1a4a3a,stroke:#2ecc71,color:#e0e0e0 style G fill:#4a3a1a,stroke:#f39c12,color:#e0e0e0 style H fill:#1a3a5c,stroke:#4a9eff,color:#e0e0e0 style I fill:#1a4a3a,stroke:#2ecc71,color:#e0e0e0 style J fill:#1a4a3a,stroke:#2ecc71,color:#e0e0e0
Step 1: 에이전트와 충분히 대화하라
에이전트에게 바로 “만들어줘”라고 하지 않는다. 먼저 에이전트가 작업을 충분히 이해할 때까지 대화한다.
이 과정은 단순하다:
- 사용자가 작업을 설명한다.
- 에이전트가 이해가 부족한 부분에 대해 질문한다.
- 사용자가 답변한다.
- 에이전트가 또 질문한다.
- 이 과정을 반복한다.
사용자가 “이 정도면 작업할 수 있겠다”고 판단할 때, 그때 비로소 다음 단계로 넘어간다.
중요한 건 시작 타이밍의 판단은 항상 사용자에게 있다는 것이다. 에이전트가 “이제 이해했으니 시작할게요”라고 스스로 넘어가는 게 아니다. 사용자가 직접 “이슈 생성해”라고 명령해야 작업이 시작된다.
이유는 간단하다. 에이전트에게 시작 타이밍을 맡기면 이해가 부족한 상태에서 작업을 시작할 위험이 있다. 사용자가 게이트를 직접 열어주는 방식이 그 리스크를 제거한다.
Step 2: GitHub Issue로 작업을 정의하라
에이전트가 충분히 이해했다면, 대화 내용을 기반으로 GitHub Issue를 생성한다.
이 이슈는 GitHub Project 보드에 자동으로 등록되어, 프로젝트 전체의 작업 현황을 한눈에 파악할 수 있게 해준다.
핵심 규칙:
이슈 1개 = 에이전트 1개 = 브랜치 1개
이렇게 하면 GitHub Project 보드 하나만 봐도 “지금 어떤 에이전트가 뭘 하고 있고, 뭐가 끝났고, 뭐가 대기 중인지” 한눈에 파악할 수 있다. 이슈 번호로 커밋과 PR이 연결되니 추적성도 완벽하다.
Step 3: 브랜치에서 작업하고, 매 단계마다 확인받아라
이 단계가 이 방법론의 핵심 중 핵심이다.
에이전트가 브랜치에서 작업하는 동안, 매 커밋 전에 반드시 사용자의 확인을 받는다.
이 흐름이 반복된다:
작업 → 사용자 확인 → 커밋 → 작업 → 사용자 확인 → 커밋 → …
왜 매번 확인해야 하는가? 에이전트가 잘못된 방향으로 10단계를 진행한 후에 발견하면 롤백 비용이 크다. 하지만 매 단계마다 체크포인트를 두면 최대 1단계만 되돌리면 된다.
Step 4: 커밋 단위는 “사람이 이해할 수 있는 크기”로
커밋의 단위는 파일 하나 수정할 때마다 하는 건 너무 작고, 기능 전체를 한 번에 하는 건 너무 크다.
기준은 단순하다:
사람이 커밋 메시지만 보고 “이 시점에 뭘 했는지” 바로 이해할 수 있는 크기
파일이 3개가 바뀌든 10개가 바뀌든 상관없다. 그 변경들이 하나의 맥락으로 묶이면 하나의 커밋이다.
좋은 커밋 단위 예시:
- “로그인 API 엔드포인트 추가”
- “사용자 인증 미들웨어 적용”
- “에러 응답 포맷 통일”
나쁜 커밋 단위 예시:
- “파일 수정” (너무 모호)
- “로그인 기능 전체 구현” (너무 큼, 중간 과정 추적 불가)
Step 5: PR로 최종 검증 후 머지
에이전트의 작업이 끝나면 Pull Request를 생성한다. 사용자가 최종 리뷰를 하고, 문제가 없으면 원본 브랜치에 머지한다.
단계별로 이미 확인을 받았기 때문에 PR 단계에서는 전체 흐름이 맞는지를 확인하는 수준이면 충분하다.
에이전트의 모든 행동은 추적 가능해야 한다
이 방법론의 근간이 되는 원칙이 있다.
에이전트가 한 모든 행동은 개발자가 원할 때 언제든 확인할 수 있어야 한다.
에이전트가 작업하는 동안 개발자가 실시간으로 모든 것을 확인하긴 어렵다. 하지만 나중에라도 과거로 돌아가서 “이 시점에 에이전트가 뭘 했는지”를 확인할 수 있어야 한다.
그래서 Git이 중요하다. 커밋 히스토리가 곧 에이전트의 행동 기록이 된다. 단순히 최종 결과물만 보는 게 아니라, 과정 자체가 기록으로 남는 것이다.
멀티 에이전트 환경: 현실적인 고민
이슈가 여러 개이고 에이전트도 여러 개라면, 현실적인 문제가 생긴다.
브랜치 스위칭 비용이 너무 크다. 에이전트 A의 작업을 확인하려면 브랜치 A로, 에이전트 B를 확인하려면 브랜치 B로 이동해야 한다. 매번 스위칭할 때마다 프로젝트를 다시 빌드해야 하고, 그 시간이 상당하다.
현재 고려하고 있는 해결책은 이슈마다 프로젝트 폴더를 별도로 구성하는 것이다:
project-issue-1/ → VS Code 창 1 → 에이전트 A (브랜치 issue-1)
project-issue-2/ → VS Code 창 2 → 에이전트 B (브랜치 issue-2)
project-issue-3/ → VS Code 창 3 → 에이전트 C (브랜치 issue-3)
이 방식이면 브랜치 스위칭 없이 각 VS Code 창에서 독립적으로 작업, 확인, 커밋이 가능하다. Git의 worktree 기능과 유사한 개념이다.
아직 완벽한 해답은 아니지만, 현재로서는 이 방식이 가장 현실적이라고 생각한다.
트레이드오프: 초반 속도 vs 장기 일관성
솔직히 말하면, 이 방법론을 적용하면 에이전트로 인한 초반 생산성은 확실히 떨어진다. 매번 확인하고 승인해야 하니까.
하지만 프로젝트가 커질수록 이 방법론의 가치가 드러난다.
에이전트가 확인 없이 자유롭게 코드를 붙이면, 각자의 맥락에서는 맞지만 전체적으로는 일관성이 반드시 깨진다. 코드 스타일이 달라지고, 아키텍처 방향이 흩어지고, 의존성이 꼬인다.
이 일관성을 잡아줄 수 있는 건 개발자 한 사람의 가치관과 철학뿐이다. 에이전트는 지시받은 맥락 안에서 최선을 다하지만, 프로젝트 전체의 방향성을 판단하는 건 사람의 몫이다.
| 구분 | 자유 위임 방식 | 주도권 유지 방식 |
|---|---|---|
| 초반 속도 | 빠름 | 느림 |
| 장기 일관성 | 깨짐 | 유지됨 |
| 기술 부채 | 빠르게 누적 | 최소화 |
| 프로젝트 이해도 | 점점 떨어짐 | 항상 유지 |
| 새 기능 추가 | 점점 어려움 | 안정적 |
| 롤백 비용 | 큼 | 작음 (최대 1단계) |
비유: 건물을 올리는 것처럼
에이전트에게 작업을 요청할 때 건물을 올리는 느낌이 들어야 한다.
기초를 다지고, 1층을 올리고, 2층을 올리고. 각 층이 무엇으로 이루어져 있는지 개발자가 알고 있어야 다음 층을 올릴 수 있다.
만약 개발자가 3층이 뭘로 되어 있는지도 모르는 상태에서 7층을 올리라고 하면? 그 건물은 언제 무너져도 이상하지 않다.
이해 없는 속도는 모래 위에 짓는 건물과 같다.
정리: 이 방법론의 5가지 원칙
- 에이전트의 모든 행동은 추적 가능해야 한다 — Git 커밋으로 기록을 남겨라.
- 시작 타이밍은 사용자가 결정한다 — 충분한 대화 후, 사용자가 “이슈 생성해”를 말해야 작업이 시작된다.
- 이슈 1개 = 에이전트 1개 = 브랜치 1개 — GitHub Issue와 Project로 체계적으로 관리하라.
- 매 커밋 전에 사용자가 확인한다 — 에이전트가 혼자 달리지 않게 매 단계마다 체크포인트를 둬라.
- 일관성은 개발자의 철학으로 잡는다 — 프로젝트의 방향성은 사람만이 판단할 수 있다.
마치며
에이전트는 놀라운 도구다. 하지만 도구에게 주도권을 넘기면, 개발자는 자기 프로젝트의 관객이 된다.
이 방법론은 느릴 수 있다. 매번 확인하고, 매번 승인하고, 매번 커밋을 검토해야 한다. 하지만 그 과정에서 개발자는 항상 프로젝트를 이해하고 있고, 건물은 단단하게 올라간다.
에이전트 시대에 개발자에게 가장 중요한 역량은 코드를 잘 짜는 것이 아니라, 좋은 방향을 잡고 그 방향으로 에이전트를 이끄는 것이 아닐까.
여러분은 에이전트와 어떻게 협업하고 계신가요? 비슷한 고민을 하고 계시다면, 여러분만의 방법을 댓글로 공유해주세요.
자신만의 철학을 만들어가는 중입니다.
댓글남기기