에이전트와 협업하기

최근에 좋은 기회가 닿아서 사주 챗봇 프로젝트에 참여하고 있다.

이번 프로젝트는 조금 특이한데, 개발을 거의 전적으로 AI 에이전트에게 위임했다.

이제 런칭 준비 막바지라, 오로지 클로드만을 이용해서 개발해본 후기를 작성해보려고 한다.

결정을 기록하자

처음에 가장 난항을 겪던 것은 프로젝트 히스토리 파악이었다.

내가 사주에 대한 베이스 지식도 없고, 프론트 코드도 잘 모르다 보니 에이전트한테 어떤 지시를 내려야 할 지도 모르겠더라. 제일 먼저 했던건 프로젝트에 대해 어떤 에이전트가 붙어도 이해할 수 있는 구조를 만드는 작업이었다. 일종의 하네스려나.

루트에 CLAUDE.md를 만들고, DECISION.md를 만들었다. 각자 다른 세션에서 코드를 작성하고, 콘솔에서 어떤 의도로 이 작업을 했는지 커밋 로그만으로는 파악에 한계가 있기 때문에 DECISION.md에 결정의 근거들을 기록하게 했다. 그리고 매번 커밋시에 이 파일에 내용을 추가하는 방식으로 가이드를 했다.

기록 규칙
추가만(append-only). 이미 적은 항목은 지우지 말고, 뒤집혔으면 새 항목으로 "○○ 결정을 번복함"이라 적는다.
새 항목은 **맨 위(최신순)**에 추가. 형식:
## YYYY-MM-DD — <한 줄 제목>
- **맥락**: 왜 이 판단이 필요했나
- **결정**: 무엇으로 정했나
- **이유**: 근거 (특히 "안 한 것"과 그 이유)
- **영향 파일/범위**: 어디를 건드렸나 (선택)
코드로 자명한 것(무엇을 바꿨나)은 git이 기록한다. 여기엔 왜만 남긴다.

위의 규칙을 최상단에 명시하고, 작업을 이어나갔다.

그러나 이 방식의 문제점도 존재했다.

• 종종 클로드가 기록을 스킵한다는 것
• 작업이 다 끝나고 머지가 된 이후에야 방향성 파악이 가능하다는 점

팀원간 효율적인 에이전트의 협업을 위해 조금 더 구체적인 지침이 필요하단 걸 느꼈다.

워크플로우를 만들자

작업 방식을 구체화해서 따를 수 있도록 가이드 해봤다.

협업 방식에서 조금 더 개선해보고 싶었던 점은 아래와 같다.

• main 브랜치에서 바로 작업한다는 점
• 팀원의 기획 의도, 개발 방향성을 사전에 인지하기 힘들다는 점
• 어떤 작업을 하고 있는지 트래킹이 힘들다는 점

지라나 컨플을 따로 쓰는건 오버스펙에 오히려 관리해야할 인프라만 늘어나는 것 같아서, 깃허브를 적극적으로 이용해 보기로 했다. 작업 전에 개발 의도, 기획 내역을 이슈로 먼저 등록한 다음에 이슈 번호로 브랜치를 딴 후, pr을 올리는 방법이었다.

종종 빌드가 깨진채로 올라오는 경우도 있어서, 빌드 검증 단계도 추가해봤다. 리뷰어 등록도 자동으로 진행해서 메일로 알람이 오도록 했다. 대략 아래와 같은 내용이다.

1. 이슈 생성
2. issue 브랜치 생성
3. PR
4. Squash Merge
5. pre-push build

그 외에는 빌드 명령어와 프로젝트 구조, 히스토리에 대해 간략히 참고할 점들이 문서에 포함되었다.

클로드의 쾌속작업

한주의 업무들을 등록하는 상위 이슈인 (TASK)가 존재하고, 금주 회의록을 정리하는 (LOG) 이슈, 그리고 클로드가 등록하는 (TODO), 실제 작업 티켓들로 분류되는 방식이다.

히스토리가 훨씬 구체적으로 남고, 팀원이 작업중이라는 사실은 훨씬 간편하게 인지가 가능했으나 생각보다 클로드의 업무 사이클이 너무 빨랐다.

이슈가 등록되고, 기획을 파악하기도 전에 pr이 올라오고, 스쿼시 머지가 진행되었다. 기획 논의를 먼저 하는게 맞으려나 고민도 했는데, 오히려 지금 팀의 업무 효율이 더 떨어지는 방식이라 현황 유지했다.

아직은 프로토타입 단계이기 때문에, 빠르게 서로의 아이디어를 구현하는게 먼저라고 생각했다. 큰 틀은 매주 진행되는 회의에서 어느정도 협의가 되어있기 때문에 세부적인 기획, 개발은 각자의 자율성에 맡기는게 훨씬 나으리라 판단했다.

너와 나의 블랙박스

그러나 가장 큰 문제는 내가 프로젝트 구조 파악이 어려워졌다는 점이다.

개발자다 보니 세부적인 호출 조건이나 제약들이 궁금한데, 생각보다 자주 바뀌는 내용들과 점점 싱크가 틀어지는 README.md의 아키텍쳐들을 보며 고민했다. 계속 리드미 새로고침 명령을 내리다가 보니, 어느순간 나도 이 문서를 팔로업하고 있지 않았다.

그래서 내린 결론은, 당분간은 클로드에게 모든걸 맡겨보자는 것이다. qa도 playwright를 이용해서 클로드가 진행할 수 있도록 세팅중이다.

‘클로드가 조건 잘못 작성했으면 어쩌지?’ ‘내가 지시한 대로, 의도한 대로 잘 작성하는 코드를 짠 게 맞나?’ 라는 걱정들이 있기는 했는데, 사실 이건 사람이 작성한다 해도 할 수 있는 실수들이고, 그래도 페이블이 나보다는 프론트 코드를 잘 작성할 것이기 때문에 일단 진행중이다.

최근에 아이로봇 이란 영화의 클립을 봤는데, 형사가 로봇을 심문하는 장면이었다. ‘너같은 로봇 따위가 명화를 그릴수 있냐? 명곡을 작곡할 줄 아냐?’ 라고 형사가 거칠게 물어보는데, 로봇이 되묻는다. ‘그럼 당신은요?’

보통 AI가 작성한 코드를 보며 했던 걱정들을 가만히 생각해보면, 결국 사람도 할 수 있는 실수들이다. 당분간은 에이전트를 도구가 아니라 팀 동료처럼 믿어보기로 했다.