나는 오랫동안 개발을 업으로 하고 있다. 주로 소규모 기업에서 거의 1인 개발을 해왔다. 다른 개발자가 있더라도 각자 자기 일을 하는 그런 회사였다. 그러다 보니 여러 명이 하나의 프로젝트를 같이 수행하는 형태의 일이 별로 익숙하지 않다. 혼자 개발하고 테스트하다 보니, 체계화된 문서화도 나에겐 익숙하지 않다. 장기간 나만의 룰로 관습적으로 개발을 해왔다. 매번 새로 입사한 개발자 AI를 통해 코딩을 시작한 초기에는 에이전트에게 내가 지금 하고자 하는 일과 현재 상황을 전달하는 방법에 집중할 수밖에 없었다. AI 에이전트와 일하는 것은 매번 새로 입사한 개발자와 일하는 상황과 같다고 느꼈다. 아무것도 모르는 개발자에게 전후 사정 설명 없이 "이걸 해줘" 하면, 원하는 대로 동작하는 것 같지만 제대로 동작하지 않는 결과물을 만들어 내곤 했다. 그리고 이걸 수정하기 위해 대화가 길어지면 에이전트가 맥락을 잃어버리는 경우가 빈번히 발생했다. 문서화라는 해답 그래서 선택한 방법이 문서화였다. 내가 개발하고자 하는 기능을 문서로 정리하고, 이 문서를 기반으로 에이전트에게 개발을 요청하는 방식이다. 비슷한 시기에 AI를 이용한 코딩 관련 콘텐츠를 보면 문서화 이야기가 많았고, 그 시기에 아마존에서 출시한 Kiro라는 IDE는 이런 부분을 아예 내장하기까지 했다. 이야기했듯이 나는 문서화에 익숙하지 않다. 그래서 개발하고자 하는 기능을 문서로 정리하는 작업도 나에게는 그렇게 만만한 작업이 아니었다. 그래서 선택한 방법은 "문서화도 에이전트에게 시키자" 였다. 에이전트와 기획 회의하기 새로운 기능 개발이 필요하면 기획 회의를 에이전트와 진행한다. 보통 대화는 이렇게 시작한다. "지금부터 이런이런 기능을 개발하기 위한 기획 문서를 작성할 예정이다. 아직 코딩을 하지는 않을 것이다." 왜 "아직 코딩을 하지는 않을 것이다"라고 붙였을까 궁금할 텐데, 개발용 에이전트들은...
나는 오랫동안 개발을 업으로 하고 있다. 주로 소규모 기업에서 거의 1인 개발을 해왔다. 다른 개발자가 있더라도 각자 자기 일을 하는 그런 회사였다. 그러다 보니 여러 명이 하나의 프로젝트를 같이 수행하는 형태의 일이 별로 익숙하지 않다. 혼자 개발하고 테스트하다 보니, 체계화된 문서화도 나에겐 익숙하지 않다. 장기간 나만의 룰로 관습적으로 개발을 해왔다.
매번 새로 입사한 개발자
AI를 통해 코딩을 시작한 초기에는 에이전트에게 내가 지금 하고자 하는 일과 현재 상황을 전달하는 방법에 집중할 수밖에 없었다. AI 에이전트와 일하는 것은 매번 새로 입사한 개발자와 일하는 상황과 같다고 느꼈다. 아무것도 모르는 개발자에게 전후 사정 설명 없이 "이걸 해줘" 하면, 원하는 대로 동작하는 것 같지만 제대로 동작하지 않는 결과물을 만들어 내곤 했다. 그리고 이걸 수정하기 위해 대화가 길어지면 에이전트가 맥락을 잃어버리는 경우가 빈번히 발생했다.
문서화라는 해답
그래서 선택한 방법이 문서화였다. 내가 개발하고자 하는 기능을 문서로 정리하고, 이 문서를 기반으로 에이전트에게 개발을 요청하는 방식이다. 비슷한 시기에 AI를 이용한 코딩 관련 콘텐츠를 보면 문서화 이야기가 많았고, 그 시기에 아마존에서 출시한 Kiro라는 IDE는 이런 부분을 아예 내장하기까지 했다.
이야기했듯이 나는 문서화에 익숙하지 않다. 그래서 개발하고자 하는 기능을 문서로 정리하는 작업도 나에게는 그렇게 만만한 작업이 아니었다.
그래서 선택한 방법은 "문서화도 에이전트에게 시키자"였다.
에이전트와 기획 회의하기
새로운 기능 개발이 필요하면 기획 회의를 에이전트와 진행한다. 보통 대화는 이렇게 시작한다.
"지금부터 이런이런 기능을 개발하기 위한 기획 문서를 작성할 예정이다. 아직 코딩을 하지는 않을 것이다."
왜 "아직 코딩을 하지는 않을 것이다"라고 붙였을까 궁금할 텐데, 개발용 에이전트들은 코드를 작성하는 룰이 기본으로 적용되어 있어서인지, 모든 대화의 끝은 "구현할까요?"와 같이 구현으로 넘어가려는 경향이 강하다. 잠깐 대답을 잘못하면 혼자 코드를 작성하는 상황에 빠져 버린다. 그래서 지금 대화는 코딩이 목적이 아님을 명확히 해서 이를 방지하는 것이다.
나열하고, 정리하고, 첨삭하고
그다음, 내가 원하는 기능에 대해서 쭉 나열한다. 이런 기능, 저런 기능, 이건 이렇게, 저건 저렇게.. 앞뒤 맥락 없이 단순 나열만 해도 된다. 이렇게 해서 에이전트에게 정리를 요청하고, 결과를 마크다운 파일로 생성하라고 지시한다.
생성된 마크다운 파일을 읽고, 마음에 들지 않는 내용은 직접 수정한다. 이건 이게 아니고, 저건 저게 아니다.. 이렇게 마크다운 파일을 수정한 후 에이전트에게 변경했음을 알리고 다시 정리를 시킨다. 정리 결과는 역시 해당 파일을 업데이트하도록 한다.
이런 과정을 반복하여 내가 원하는 사항이 다 정리되면, 이를 바탕으로 기획서 작성, 화면 구성, API 명세 등을 작성하도록 지시한다. 한꺼번에 작성하기도 하고, 각각 개별 문서 단위로 하기도 한다. 모든 문서는 마크다운 파일로 생성하도록 하고, 생성된 문서에 대해서도 앞에서와 같이 읽고 첨삭하고 에이전트에게 다시 작성시키는 과정을 반복한다.
컨텍스트가 중요하다
경우에 따라서는 이 과정이 실제 코드를 생성하는 시간보다 오래 걸리기도 한다. 내가 Cursor나 Copilot을 버리고 Claude Code에 정착한 가장 큰 이유는 컨텍스트 크기였다. 이렇게 길게 이야기를 이어 나가도 맥락을 잃지 않고 진행이 가능했기 때문이다.
문서를 프로젝트에 심기
문서 작성이 완료되면 개발할 프로젝트에 이 문서들을 포함시킨다. 이걸 소스 코드만큼 중요한 원천 자료라고 생각하고, CLAUDE.md에 "이 기능에 대해서는 이 파일들을 참고해라"라는 내용을 추가해 준다. 다른 에이전트를 사용한다면 해당 에이전트의 룰 파일에 추가하면 된다.
그리고 마지막으로 "이 기능에 대해서 구현을 해줘"라고 에이전트에게 구현을 지시한다.
남는 것은 문서
이런 방식으로 개발하면 최소한 문서 파일이 하나는 생성된다. 이건 두고두고 내가 작업하는 데 도움이 된다. 원래 문서란 게 두고두고 보는 것이니까. 그리고 항상 새로 입사한 직원인 에이전트에게 설명을 프롬프트에서 직접 하지 않아도 된다.
이것만 해도 그냥 프롬프트만 가지고 개발하는 것보다 훨씬 좋은 결과를 얻을 수 있었다.
✍️ 이 글은 Claude의 도움을 받아 다듬어졌습니다.
댓글
댓글 쓰기