쉽게 설명한 에이전트 주도 개발

• #ai
• #agent
• #agent-driven-development
• #agentic-ide
• #cursor
• #windsurf
• #cline
• #roo
• #aider

TL;DR

• 커서(Cursor)를 쓴다
• 스펙 문서를 만든다
• 각 기능을 만든다
• 배포한다

시작하며

회사에서는 보안 때문에 AI 코딩 어시스턴트를 다 막아두고, 쓰면 오히려 방해가 되는 툴들만 쓰게 허용하고 있어서, 회사 일 할때는 아예 AI 어시스턴트 자체를 안썼다. 개인적으로도 깃헙 코파일럿 edits(beta) 기능만 쓰고 있었다.

그러다 유튜브에 커서로 개발하는 영상들과 아티클들을 보고, 지금 시장은 이미 에이전트 기반의 개발방법을 도입하고 있다는 것을 깨닫게 되었다.

그리고 개인 프로젝트¹를 다시 꺼내서 몇 이터레이션을 돌리면서 챗봇을 구현해보고 나니 머리속에 어느정도 정리가 되는 것 같았다.

본 글에서는 에이전트 기반의 개발 – 이후 그냥 에이전트 주도 개발 이라고 부르겠다. 딱히 지정된 명칭이 없이 agentic dev workflow, agent dev process 등 다양한 이름으로 불리고 있기 때문이다. – 에 대한 현재까지 내가 정리한 베스트 프랙티스를 간단히 소개해본다.

Cursor vs others

일단 이후 설명할 에이전트 주도 개발은 에이전틱 IDE 를 전제로 한다. 따라서 에이전트 기반의 IDE 를 선택해야한다.

에이전틱 IDE 는 대표적으로 Windsurf², Cursor³, Aider, Roo, Github Copilot, Cline, Amazon Q Developer 가 있다.

인터넷에 각종 비교글이 많지만, 진짜 한달에 20달러를 쓸 수 없는 상황이 아니라면 Windsurf 와 Cursor 중에 하나를 골라서 쓰자.

개인적으로 Windsurf 는 개발자의 제어권보다 에이전트 기반의 자동화에 좀 더 초점을 맞추고 있고(방향성이), 커서(Cursor)는 제어권과 자동화의 밸런스를 잘 잡고 있다고 생각된다. 약간 과장되게 말하면, MVP 를 빨리 자동으로 만들고 싶으면 Windsurf 를 쓰고, MVP 이후 프로덕션에도 계속 사용할 툴을 찾고 있다면 커서를 쓰면 된다고 생각하면 된다.

나느 에이전트 기반의 개발을 주도하고 있는 IDE 는 커서(Cursor)라고 생각하고 있으며, 본인이 개발자이며 특별히 다른 IDE 를 써야하는 이유가 없다면 일단 커서로 시작하는 것을 권장한다.

이후 내용은 커서의 기능들을 기준으로 설명한다.

결국 쓰다보면 claude sonnet 3.5(v2), gemini 2.0 pro, o3-mini 를 번갈아 가면서 사용하게 되는데, 자유롭게 필요한 모델을 선택해 가면서 개발하려면 이것저것 결제하고 설정하고 하느니 그냥 깔끔하게 커서를 쓰고 하루나 이틀 커피 참으면 한달동안은 비즈니스 로직에 집중할 수 있게 된다.

Agent driven development process Best Practice

에이전트 주도 개발은, 사람이 코드를 메인으로 생성하고 AI 가 어시스턴트로 동작하는 것이 아니라, AI 가 코드를 메인으로 생성하고 사용자가 평가자로 동작하는 형태로 코드 생성의 책임이 역전되는 방식을 말한다.

에이전트 주도 개발시 핵심 문제는, LLM 이 우리가 원하는 코드를 안정적으로 생성하게 가이드하기 어렵다는 점이다. (즉, LLM 이 원하는 코드를 생성할 수 있는 능력은 있다는 전제가 있다.)

이 문제를 극복하기 위한 별 방법이 다 있지만, 현재까지 가장 안정적이라고 인정받고 공유되는 것들을 정리해보면 크게 다음과 같은 프로세스를 가진다.

1. PRD (Product Requirement Document) 를 작성한다.
2. 개발 환경을 설정한다.
3. Chat/Composer 기능을 통해 PRD 의 기술요구사항을 순차적으로 구현한다.
4. 서비스에 저장 레이어를 연결한다.
5. 서비스에 인증 레이어를 연결한다.
6. (선택사항) V0⁴ 등의 특화된 서비스를 통해 UI 를 개선한다.
7. 서비스를 배포한다.

각 과정을 약간 더 디테일하게 설명하는 것으로 문서를 마무리해본다.

1. PRD 작성

대부분의 개발과정은 많은 변수(모호함)를 가지고 있고 초반에 얼마나 많은 변수를 상수로 바꿔두느냐에 따라 이후 개발의 속도나 변동이 적다는 것은 모두가 아는 사실이다. (예를 들면, 애자일은 전체 프로젝트 중 2주치의 변수 정도를 상수로 바꿔두고 개발하는 프로세스라고 볼 수 있다.)

에이전트가 개발을 진행하기 위해서는 어떤 것이 변수이고 어떤 것이 상수인지를 자연어로 잘 기술되어 전달할 필요가 있다. 보통 이런 변수와 상수들을 요구사항이라고 부른다.

베스트 프랙틱스 프로세스에서는 개발시 에이전트에게 전달될 요구사항 문서를 만드는 프로세스를 가장 초반에 진행한다.

이 문서는 많은 아티클들에서 PRD 라고 부르고 있고, 문서의 템플릿도 제각각으로 사용하고 있다.⁵⁶

원래의 PRD 는 비즈니스 관점에서의 요구사항과 기준을 정의하는 문서이다. 따라서 일반적인 PRD 템플릿은 개발에 적합한 형태라고 볼수는 없다.

ADR(Architecture Decision Record) 이나 TSD (Technical Specification Document) 등의 좀더 기술 요구사항에 적합한 기술문서 형태들이 있지만, 실제로 개발을 해보면 PRD 의 비즈니스 관점 요구사항들 (혹은 비기능적 요구사항들)도 매우 중요한 요소로 동작하는 경우가 있다.

따라서 PRD 라고 부르는 형태의 비기능적 요구사항에 대한 정리와 TSD 에 포함된 기능적 요구사항에 대한 정리가 모두 포함되고, ADR 의 아키텍쳐적인 의사결정에 대한 내용이 모두 포함된 형태의 문서가 필요하다. 추가로 프론트엔드 개발이 포함된 경우, UI/UX 에 대한 내용도 포함되어야 한다.

이 PRD 문서의 특징은 크게 2가지가 있다.

1. 이 문서는 한번만 만들고 치우는 것이 아니라 개발 기간동안 지속적으로 업데이트되면서 코드와 함께 수정된다. 물론 문서의 업데이트도 에이전트를 통해 처리하는 것이 일반적이며, 이 과정을 통해 자연스럽게 최신화된 문서를 유지하게 된다.
2. 하나의 문서에 모든 정보를 담지 않는다. 즉, 기능의 단위별 혹은 도메인의 단위별 등 코드의 구조나 팀의 구조를 반영하여, 기능이 추가될 때마다 문서가 추가적으로 만들어지게 된다. 따라서 문서를 생성하는 과정을 자동화 할 필요가 있다.

스펙문서 생성 자동화

스펙 문서(PRD) 생성을 자동화하는 방법을 간단히 살펴보고 넘어가자.

스펙 문서 생성은 대부분 아래와 같은 방식으로 진행하게 된다.

1. 사용할 템플릿을 만든다. (주로 마크다운으로 생성할 내용을 정리한다.)
2. 해당 템플릿을 Claude Sonnet 또는 GPT4o 와 대화형으로 생성한다.⁵
3. 템플릿을 기반으로 완성된 문서를 리즈닝 모델 (o3-mini, o1) 를 통해 검수받고 수정을 진행한다.

3번이 상당히 중요한 부분으로, 개발자가 실제로 해당 문서를 통해 개발할 때, 생산성을 저하시킬 수 있는 모호한 포인트를 리즈닝 모델로 이유와 함께 찾아달라고 하고, 어떤 내용이 채워져야 하는지를 설명해달라고 하면 된다. 실제 내용도 리즈닝 모델로 채워도 되지만 어떤 내용이 부족하고 어떤 내용이 채워져야 하는지만 얻을 수 있으면, 해당 내용을 프롬프트로 전달해서 GPT-4o 로 다시 대화형으로 개선하면 큰 퀄리티 차이를 보이지 않았다.

마찬가지로 구조화된 상세 템플릿을 잘 지정해두면 GPT-4o 모델로도 o1 모델의 결과와 비슷한 수준의 스펙 문서를 생성할 수 있었다. 템플릿이 없다면 o3-mini 등의 모델과 함께 템플릿을 먼저 만드는 것도 좋다.

아래는 내가 MVP 생성시 자주 사용하는 템플릿의 일부이다.

## 2. MVP Goals and Key Metrics

### 2.1 Purpose

- Briefly describe the hypothesis or goals to be validated through this MVP.

**Example**

"If we provide a 30% discount coupon upon sign-up, the revisit rate within 14 days will increase."

### 2.2 Key Performance Indicators (KPIs)

- Define the quantitative metrics to evaluate the purpose (hypothesis) stated above.

**Example**

"Revisit rate within 14 days after sign-up: 30% or higher."

2. 개발환경 설정

실제 코드를 생성하기 위한 개발환경을 설정해야한다.

많은 영상이나 글에서는 직접 생성하는 편이다.

하지만 개인적으로 스펙 문서가 있다면 해당 문서를 기반으로 README.md 파일을 생성해달라고 하는 것도 좋은 것 같다.

@SPEC.md 를 읽고 README.md 파일을 작성해줘. Installation 섹션이 반드시 포함되어야 해

이렇게 하고 Installation 을 실행하면서 필요하다면 스펙문서와 함께 고쳐나가면서 문서를 완성하면 자연스럽게 개발환경도 설정이 된다.

특히 대부분의 에이전틱 IDE 는 VSCode 기반이므로 DevContainer 를 사용하는 것이 좋다. 언어를 새로 깔거나 버전을 맞추는 작업은 생각보다 오래걸리고 귀찮기 때문이다. (팀원들이 윈도우, 맥, 그리고 리눅스를 혼용하는 경우에는 더더욱 )

3. 구현하기

스펙문서를 통해 구현을 한다. 보통 아래와 같은 식의 프롬프트를 전달하여 구현하게 된다.

@SPEC.md 의 6.4 섹션을 구현해줘.

본 글의 시작부분에서 다뤘지만, LLM 은 대부분의 코드를 생성할 능력이 있다. 우리가 원하는 코드가 나오지 않는 이유는 (즉, 안정적인 코드가 나오지 않는 이유는) 필요한 정보가 모두 제공되지 않았거나 모호한 요구사항들이 포함되어 있기 때문이다.

먼저 필요한 정보의 경우, 대표적으로 API 스펙이 있다. 해당 API 개발자 문서를 미리 인터넷에서 찾아서 스펙 문서에 포함하는 경우도 있지만, 커서에는 Docs 기능을 통해 필요할 때 원하는 문서를 인터넷을 통해 LLM 에 제공할 수 있다.

예를 들면, 아래처럼 문서를 등록하고 나면 커서는 해당 url 주소를 읽어 임베딩을 저장해둔다.

@Add new doc https://daisyui.com/components/card/

이후 해당 주소를 참조하면 자동으로 RAG 로 문서의 내용을 프롬프트로 전달할 수 있다.

`@DaisyUI Card API` 카드 컴포넌트를 사용해서 상품 목록 페이지를 구성해줘.

마지막으로 필요하다면 스펙 문서에 다음과 같은 내용을 추가할 수도 있다.

@SEC.md 에 DaisyUI 의 카드 컴포넌트를 사용해서 6.4 에 구현한다는 내용을 추가해줘.

구현 방식과 SPEC 템플릿 일치시키기

해당 방식으로 프로덕션 수준의 개발을 해보면 템플릿을 구성할 때 아래의 요소들이 반영되면 좀 더 안정적으로 개발 내용을 테스트할 수 있다.

1. 비즈니스 요구사항과 기술 요구사항을 일치시키는 방식으로 구성되어 있는 것이 좋다.
2. 기술 요구사항 섹션이 레이어 방식보다 버티컬하게 구성되어 있는 것이 좋다.
3. 기술 요구사항 섹션이 상세하게 나눠져 있는 편이 좋다. (예, 사용자 스토리 -> 작업 태스크)

즉, 구현을 에이전트가 대부분을 맡아서 하는 상황에서는, 에이전트의 결과물을 논리적인 단위로 쉽게 체크하고 확인할 수 있도록 문서가 구성되어 있어야 한다. 따라서 어떻게 구현할지 보다, 구현한 것을 어떻게 확인할 지를 먼저 고민하는 방식으로 전환하는 것이 중요하다.

4, 5. 인증 및 저장공간 연결하기

보통 인증과 저장공간을 모두 사용할 수 있는 Supabase 나 Firebase 를 많이 사용한다.

위의 두서비스가 아니더라도 대부분의 MVP 는 인증과 저장공간 둘다 API_KEY 를 이용하여 프로비전 과정이 없이 바로 사용할 수 있는 서비스를 선호하게 된다. (예, Airtable 등)

인증을 먼저 구현하는 것은 프론트엔드에서 인증 후 해당 Auth 정보를 이용해 뒤에 있는 저장공간 등의 인프라를 연결하는 것이 일반적이기 때문이다.

각 서비스의 콘솔에서 기본설정은 손으로 해야하지만, 코드 부분은 연동하는 문서를 RAG(커서의 docs) 로 프롬프트에 제공하여 에이전트가 직접 구현하게 하면 쉽게 연결할 수 있다.

6. (선택사항) V0 등의 특화된 서비스를 통해 UI/UX 를 개선한다

대부분 에이전틱 IDE 들은 멀티모달을 지원하기 때문에 이미지를 직접 에이전트에 주고 해당 UI 를 구현할 수 있다.

하지만 V0 등의 서비스들은 좀 더 UI 특화된 데이터셋으로 그냥 LLM 에 바로 요청하는 것 보다 훨씬 개선된 결과를 제공한다.

따라서 참조가 되는 웹사이트의 스크린샷을 V0 에 전달하여 해당 레이아웃, 룩앤필을 반영한 코드를 생성한 뒤 가져다 쓰거나 하는 과정도 적용할만하다.

또는 21st.dev 같은 사이트들을 통해서 프롬프트를 이용한 UI 컴포넌트 반영 방법도 연구되고 있는 추세이다.

7. 서비스를 배포한다

간단한 형태인 SPA MVP 같은 경우에는 Vercel 이나 Cloudflare 등의 서비스에 배포하면 간편하다.

하지만 백엔드를 포함한 서비스를 클라우드에 배포하는 것은 수동으로 할 수 밖에 없다. 그냥 수동으로 하자.

최근 이러한 부분을 개선하기 위한 시도도 있는데, 대표적인 것이 Google Project IDX⁷ 같은 것이다.

Google Project IDX 를 이용하면, VSCode 기반의 웹 IDE 에서 백엔드를 개발한 뒤 (옛날 AWS 의 Cloud9 같은 방식) 통합된 플러그인을 통해 클릭 몇번으로 서버를 GCP Cloud Run 으로 배포할 수 있다.

마치며

개인적으로 에이전트 주도 개발방법은 올해 계속 발전해나갈 것으로 생각하고 있다.

위에 소개한 각 프로세스는 아직 초기단계이고 개선될 여지가 많다.

LLM 도구호출 때문에 Tavily 나 Serpapi 같은 서비스들이 떠오르듯이, 에이전트가 쉽게 개발문서를 이해하고 접근할 수 있도록 하는 방법들이 발전될 것으로 생각된다. (벤더들이 LLM 친화적으로 API 문서를 만들든, 별도의 서비스가 나오든, IDE 에서 해당 기능이 개발되든.)