Agentic Development Workflow

AI 에이전트를 활용한 개발에서 중요한 것은 코드를 생성하게 하는 것 자체가 아니라, 생성 이전의 사고 구조를 통제하는 것이다.

효율적인 에이전틱 개발은 다음과 같은 순차적 워크플로우를 따른다.

코드 리서치 → 계획 → 계획 리뷰 → 구현 → 피드백

 

핵심 원칙은 다음 두 가지다.

1. AI는 실행을 담당한다
2. 개발자는 의사결정을 담당한다

---

1. 분석 단계 (Code Research)

첫 단계는 코드베이스에 대한 충분한 이해다.

AI에게 바로 구현을 요청하지 말고, 먼저 코드 리서치 문서를 작성하도록 지시한다.

 

예시 프롬프트

이 폴더를 깊이 읽고 코드가 어떻게 동작하는지 완전히 이해해라.
구조, 데이터 흐름, 주요 컴포넌트, 의존성 등을 분석하고
모든 내용을 research.md 문서에 상세히 정리해라.

 

분석 단계의 목표

• 코드베이스 구조 이해
• 주요 모듈의 역할 파악
• 데이터 흐름 정리
• 구현 제약사항 식별

산출물

research.md

 

이 문서는 이후 계획 단계에서 참조되는 기반 컨텍스트가 된다.

---

2. 계획 단계 (Planning)

코드를 작성하기 전에 구현 계획 문서(plan.md)를 먼저 작성한다.

이 단계가 에이전틱 개발에서 가장 중요하다.

AI에게 단순한 계획이 아니라 구체적인 실행 설계 문서를 작성하도록 요구해야 한다.

---

계획 문서 작성 예시

코드 스니펫을 포함하여 로그인 기능을 구현하는 상세한 plan.md를 작성해라.

 

또는

현재 시스템은 오프셋 기반 페이징을 사용하고 있다.

이를 인풋 기반 페이징(Input-based pagination)으로 변경해야 한다.

소스코드를 분석하고 실제 코드베이스 구조를 기반으로
구체적인 구현 계획(plan.md)을 작성해라.

 

---

plan.md에 반드시 포함해야 할 요소

1. 접근 방식 설명

구현 전략을 서술한다.

Approach
- 현재 구조 분석
- 변경해야 할 컴포넌트 식별
- 단계적 변경 전략

 

---

2. 코드 스니펫

핵심 구현 코드를 포함한다.

function fetchItems(cursor?: string) {
    return db.query({
        where: { id: { gt: cursor } },
        limit: 20
    })
}

---

3. 수정될 파일 경로

src/features/auth/login-service.ts
src/entities/user/model.ts
src/api/auth/login.ts

---

4. 트레이드오프 분석

Option A: Cursor pagination
Option B: Offset pagination

Trade-off
- Cursor pagination: 성능 우수
- Offset pagination: 구현 단순

 

---

5. 완료 기준 체크리스트

계획 문서에는 완료 정의(Definition of Done)를 반드시 포함한다.

Checklist

[ ] 로그인 API 구현
[ ] 인증 토큰 발급
[ ] 세션 저장
[ ] 타입 체크 통과
[ ] 테스트 통과

 

이 체크리스트가 작업 완료의 기준이 된다.

---

3. 계획 리뷰 프로세스

계획 문서는 AI가 작성하지만 최종 결정은 개발자가 한다.

프로세스

1️⃣ AI에게 plan.md 작성 요청

2️⃣ 개발자가 계획 문서를 검토

3️⃣ 문서에 직접 주석을 추가

예시:

NOTE:
이 접근 방식은 성능 문제가 있을 수 있음

NOTE:
Redis를 사용해야 함

 

가능한 피드백

• 가정 수정
• 접근 방식 변경
• 기술 제약 추가
• 도메인 지식 전달

---

AI에게 다시 전달

문서에 몇 가지 메모를 추가했다.
모든 메모를 반영하여 plan.md를 업데이트해라.
아직 구현하지 마라.

 

AI는 계획 문서만 수정한다.

---

중요한 규칙

모든 모호함이 제거될 때까지 재귀적으로 질문하도록 지시한다.

계획에서 모호한 부분이 있다면
모든 불확실성이 제거될 때까지 질문해라.

 

---

4. 구현 단계 (Execution)

계획이 완성되면 구현은 기계적으로 수행한다.

구현 단계 지시 예시

plan.md의 계획에 따라 구현을 시작해라.

각 작업을 완료할 때마다
plan.md 체크리스트를 완료로 표시해라.

모든 체크리스트가 완료될 때까지 멈추지 마라.

마지막에 타입 체크를 실행하고
모든 타입 오류를 수정해라.

 

---

구현 단계의 특징

이 단계에서 AI의 역할은

설계 → 실행 변환기

즉,

plan.md → 코드

 

개발자의 역할은 감독자(supervisor)가 된다.

---

5. 잘못된 방향 수정 전략

AI가 잘못된 방향으로 구현을 진행할 경우 다음 전략을 사용한다.

❌ 잘못된 방법

• 기존 코드 위에 수정 누적
• 부분 패치 반복

✅ 권장 방법

git 변경을 통째로 되돌린다
→ 범위를 재설정한다
→ 새로운 plan.md 작성

 

범위를 좁히는 것이 점진적 수정보다 더 좋은 결과를 만든다.

---

6. 의사결정은 절대 위임하지 않는다

AI에게 실행은 맡기되 결정은 맡기지 않는다.

개발자가 유지해야 할 권한

• 기술 선택
• 라이브러리 선택
• 설계 방향
• 범위 정의

---

예시

그 모델 대신 이 모델을 사용해라

직접 구현하지 말고
이 라이브러리를 사용해라

 

또는

이 부분은 수정하지 마라

 

---

중요한 원칙

라이브러리가 호출자에게 맞추는 것이 아니라
호출자가 라이브러리에 맞춰야 한다

 

---

7. 하나의 긴 세션 운영

에이전틱 개발은 다음 흐름을 하나의 긴 작업 세션으로 운영한다.

1. 코드 분석
2. 계획 작성
3. 개발자 피드백
4. 계획 수정
5. 구현

 

핵심 목표는 다음과 같다.

AI가 코드를 작성하기 전에 무엇을 작성해야 하는지 명확히 정의하는 것

---

8. Shared Mutable State 전략

에이전틱 개발에서 가장 실용적인 인간-에이전트 협업 방법은 공유 문서 기반 루프다.

핵심 개념

shared mutable state

 

공유 문서:

plan.md

 

개발자는 다음 방식으로 개입한다.

plan.md의 특정 위치를 직접 수정

 

예시

src/features/auth/login.ts

NOTE:
이 부분은 OAuth를 지원해야 한다

 

AI는 이 문서를 기반으로 계속 수정 → 구현을 반복한다.

---

결론

효율적인 에이전틱 개발의 핵심은 다음 세 가지다.

1️⃣ 코드보다 계획이 먼저다

research → plan → code

 

---

2️⃣ AI는 실행 엔진이다

AI에게 맡겨야 할 것

• 코드 작성
• 반복 작업
• 구현

---

3️⃣ 개발자는 방향을 통제한다

개발자의 역할

• 기술 선택
• 아키텍처 결정
• 범위 관리
• 품질 감독