Web Dev Learn

Theme

11-2. 에이전트 작업 흐름과 프론트엔드 태스크 분해 ​

한 줄 요약: 프론트엔드 작업을 에이전트가 자체 검증 루프를 돌 수 있는 크기로 쪼개고, 목표·경계·검증 명령·멈출 조건을 갖춘 작업 명세를 작성해 위임할 수 있다.

학습 목표 ​

  • 하나의 프론트엔드 요구사항을 탐색·계획·구현·검증·리뷰의 독립 루프로 분해할 수 있다.
  • 목표, 제외 범위, 파일 경계, 재현·검증 명령, 성공 조건, 멈출 조건을 갖춘 작업 명세를 작성할 수 있다.
  • "계획 먼저, 실행은 검토 후" 워크플로가 왜 에이전트의 루프 구조에서 효과적인지 설명할 수 있다.
  • UI 상태표, 접근성, 뷰포트, 브라우저 검증을 프론트엔드 작업 명세의 성공 조건으로 편입할 수 있다.
  • 병렬 에이전트와 서브에이전트 위임의 트레이드오프를 판단할 수 있다.

배경: 왜 이것이 존재하는가 ​

11-1에서 에이전트는 실패 신호를 보고 행동을 수정하는 루프라고 정리했다. 이 모델에서 곧바로 따라 나오는 질문이 있다. 루프가 성립하려면 작업이 어떤 조건을 갖춰야 하는가?

사람에게 일을 맡길 때 우리는 이미 답을 알고 있다. 좋은 이슈에는 재현 절차가 있고, 좋은 PR은 리뷰 가능한 크기이며, 좋은 요구사항에는 완료 조건이 있다. 에이전트 작업 명세는 이 원칙의 연장이다. 다만 결정적인 차이가 하나 있다. 사람은 모호하면 질문하지만, 에이전트는 모호하면 추측하고 실행한다. 동료에게 "검색이 좀 이상한데 봐 줄래?"라고 말하면 동료는 "어떤 검색어에서? 어느 화면에서?"라고 되묻는다. 에이전트는 되묻는 대신 저장소에서 '이상해 보이는' 코드를 찾아 자신의 가설대로 고친다. 모호함이 대화 비용이 아니라 잘못된 파일 수정과 불필요한 명령 실행으로 바뀌는 것이다.

그래서 작업 분해와 명세 작성은 에이전트 활용의 부수 기술이 아니라 핵심 기술이다. 프롬프트 문구를 다듬는 문제가 아니라, 검증 가능한 작업 단위를 설계하는 문제이며, 이는 Phase 7의 커밋 설계와 Phase 10의 요구사항 작성에서 이미 훈련한 능력의 적용이다.

핵심 개념 ​

작업 크기의 상한은 검증 가능성이 정한다 ​

"작게 시켜라"는 통용되는 조언이지만, '작게'의 기준이 없으면 실천할 수 없다. 기준은 두 가지다.

  1. 검증 단위: 작업이 끝났을 때 성공/실패를 판정하는 명령 또는 절차가 하나로 정의되는가. "검색 실패 상태 처리 추가 + pnpm test search 통과"는 판정 가능하다. "검색 UX 개선"은 판정 불가능하다.
  2. 컨텍스트 예산: 작업에 필요한 파일·문서·이력이 에이전트의 컨텍스트 윈도우 안에 오염 없이 들어가는가. 수십 개 파일을 오가는 작업은 세션 후반에 판단 품질이 떨어진다(메커니즘은 11-3에서 다룬다).

이 기준으로 보면 "전체 앱을 개선해 줘"가 왜 실패하는지 명확하다. 검증 단위가 없어 에이전트는 스스로 성공을 선언할 기준이 없고, 범위가 컨텍스트 예산을 초과해 후반 판단이 흐려진다. 반대로 지나치게 잘게 쪼개는 것도 비용이다. 매 작업마다 에이전트는 저장소를 다시 탐색해야 하므로(세션 간 기억이 없다), 탐색 비용이 작업 비용을 넘는 크기까지 쪼개면 손해다. 실용적 범위는 **"PR 하나로 리뷰 가능한 크기, 검증 명령 하나로 판정 가능한 단위"**다.

단계를 루프로 분리한다 ​

하나의 요구사항도 성격이 다른 단계들로 이뤄진다. 각 단계는 필요한 도구, 위험, 검증 방법이 다르므로 별도 루프로 나누는 것이 기본형이다.

루프에이전트가 하는 일필요 권한산출물
탐색관련 코드·문서를 읽고 현재 구조를 보고읽기 전용구조 요약, 영향 범위
재현버그를 재현하는 최소 절차·테스트 작성읽기 + 테스트 실행실패하는 재현 테스트
계획변경할 파일, 순서, 검증 방법 제안읽기 전용계획 문서
구현계획에 따른 편집과 자체 검증쓰기 + 명령 실행diff, 검증 로그
검증테스트·타입체크·브라우저 확인실행 + 브라우저증거 패키지(11-5)
리뷰 반영리뷰 지적의 반영쓰기 + 실행수정 diff
문서화PR 설명, ADR 초안, 변경 로그읽기 중심문서

분리의 이점은 세 가지다. 첫째, 위험이 계단식으로 열린다. 탐색과 계획은 읽기 전용이므로 아무리 틀려도 저장소가 변하지 않는다. 둘째, 사람의 개입 지점이 자연스럽게 생긴다. 계획과 구현 사이에서 사람이 계획을 검토하면, 잘못된 방향의 구현에 드는 비용(에이전트의 실행 비용 + 사람의 diff 리뷰 비용)을 통째로 아낀다. 셋째, 실패 귀인이 쉬워진다. 구현이 실패했을 때 탐색 산출물이 남아 있으면 "이해가 틀렸는지, 실행이 틀렸는지"를 구분할 수 있다.

이것이 "계획 먼저 받아라"라는 팁의 원리다. 대부분의 하네스가 읽기 전용 계획 모드를 별도로 제공하는 이유이기도 하다.

작업 명세의 구성 요소 ​

좋은 작업 명세는 다음 항목을 갖춘다. 형식은 자유지만 각 항목의 존재 여부가 결과를 가른다.

md
## 목표
장바구니 수량 변경 시 합계가 갱신되지 않는 버그를 수정한다.

## 재현
1. `pnpm dev` 실행 후 /cart 접속
2. 상품 수량을 2로 변경
3. 기대: 합계 갱신 / 실제: 이전 합계 유지
재현 테스트: `pnpm test cart-total` (현재 실패 상태)

## 범위와 경계
- 수정 대상: `src/features/cart/` 아래로 한정
- 제외: 장바구니 UI 리디자인, 수량 입력 컴포넌트 교체
- 변경 금지: `src/api/` 클라이언트 계약, 전역 스토어 스키마

## 성공 조건
- `pnpm test cart-total` 통과, 기존 테스트 회귀 없음
- `pnpm typecheck && pnpm lint` 통과
- 브라우저에서 재현 절차 수행 시 합계 갱신 확인 (스크린샷 첨부)

## 멈출 조건
- 원인이 `src/features/cart/` 밖(전역 스토어, API 응답)에 있다고 판단되면
  수정하지 말고 분석 결과만 보고한다.
- 기존 테스트를 수정해야만 통과한다면 멈추고 이유를 보고한다.

각 항목이 에이전트 루프의 어느 지점을 통제하는지 보자.

  • 목표와 재현은 루프의 시작점을 고정한다. 재현 명령이 있으면 에이전트는 "고쳐졌는가"를 스스로 판정할 수 있다. 재현 테스트가 없다면 "먼저 실패하는 테스트를 작성하라"를 작업의 1단계로 명시하는 것이 좋다.
  • 범위와 경계는 행동 공간을 제한한다. 에이전트는 원인을 쫓다가 명세에 없는 파일을 '개선'하는 경향이 있다. 파일 경계를 명시하면 diff 리뷰 범위가 예측 가능해진다.
  • 성공 조건은 검증을 에이전트의 책임으로 만든다. 검증 명령이 명세에 없으면 에이전트는 편집만 하고 루프를 닫을 수 있다.
  • 멈출 조건이 가장 자주 빠지는 항목이다. 에이전트는 기본적으로 목표 달성까지 계속 시도하므로, 잘못된 방향의 끈질긴 시도(테스트를 통과시키려 테스트를 약화시키는 것이 전형이다)를 막는 명시적 정지 규칙이 필요하다.

프론트엔드 특화: 성공 조건에 UI 검증을 편입한다 ​

백엔드 작업은 대체로 "테스트 통과"가 성공 조건으로 충분하지만, 프론트엔드는 렌더링된 결과가 최종 판정 대상이다. 작업 명세에 프론트엔드 고유 검증을 명시적으로 편입해야 한다.

  • UI 상태표: 구현 요청에는 대상 컴포넌트의 상태 조합(loading / empty / error / partial / success)을 표로 첨부하고, 각 상태의 처리를 성공 조건에 포함한다. 상태표는 Phase 10 요구사항 문서의 재사용이다.
  • 접근성: "버튼은 접근 가능한 이름을 가진다", "키보드로 플로우를 완주할 수 있다"를 성공 조건에 넣고, 검증 방법(axe 실행, 키보드 절차)을 명시한다. 에이전트는 div + onClick으로도 목표를 '달성'할 수 있으므로 접근성은 명시하지 않으면 보장되지 않는다.
  • 뷰포트: 반응형 요구가 있으면 확인할 뷰포트 폭을 명시한다. 예: "375px, 768px, 1280px에서 스크린샷".
  • 브라우저 실증: Playwright 테스트 또는 브라우저 조작 도구로 실제 렌더링을 확인하게 한다. jsdom 기반 테스트 통과와 실제 브라우저 렌더링은 다르다(CSS, 레이아웃, 포커스는 jsdom이 검증하지 못한다).
  • 성능 근거: 성능 관련 작업이면 개선 주장에 측정을 요구한다. 예: "React Profiler로 변경 전후 리렌더 횟수 기록", "Lighthouse 점수 첨부". Phase 8의 "주장에는 측정을 붙인다" 원칙이 에이전트에게도 그대로 적용된다.

권장 워크플로 전체 흐름 ​

위 요소를 조합한 기본 워크플로는 다음과 같다.

text
1. 사람: 작업 명세 작성 (템플릿 사용)
2. 에이전트(읽기 전용): 탐색 + 계획 제출
3. 사람: 계획 검토 — 영향 범위, 접근 방식, 검증 계획 확인
   └ 계획이 틀렸으면 여기서 수정 (가장 싼 개입 지점)
4. 에이전트(쓰기 허용): 작은 단위로 구현 + 자체 검증
5. 에이전트: 검증 명령 실행, 브라우저 확인, 증거 수집
6. 사람: diff 리뷰 — 명세 경계 준수, 테스트 약화 여부, 부수 변경 확인
7. 에이전트: 리뷰 지적 반영, PR 설명 작성 (남은 리스크 포함)
8. 사람: 병합 결정 (책임은 여기 남는다)

전 과정에서 사람의 개입은 세 번(계획 검토, diff 리뷰, 병합)이다. 이 세 지점은 자동화 성숙도가 올라가도 없애는 것이 아니라 가볍게 만드는 대상이다. 계획 검토를 생략할 수 있는 작업(위험도 낮음, 검증 자동)과 생략하면 안 되는 작업의 구분은 11-6의 팀 정책으로 이어진다.

병렬 작업과 서브에이전트 ​

에이전트는 사람과 달리 여러 인스턴스를 동시에 돌릴 수 있다. 두 가지 형태와 각각의 트레이드오프를 구분해야 한다.

병렬 에이전트는 독립된 작업을 동시에 진행하는 것이다. 같은 작업 디렉터리에서 두 에이전트를 돌리면 서로의 편집이 충돌하므로, Git worktree나 별도 클론으로 파일 시스템을 격리하는 것이 전제다. 적합한 대상은 서로 파일 경계가 겹치지 않는 작업들 — 독립적인 버그 수정, 문서화, 테스트 보강 — 이다. 큰 기능을 쪼개 병렬로 돌리는 것은 매력적으로 보이지만, 조각 간 인터페이스가 확정되지 않은 상태에서는 통합 비용이 병렬화 이득을 잠식한다. 사람 팀의 태스크 분배와 같은 원리다.

**서브에이전트(subagent)**는 하나의 메인 에이전트가 하위 작업을 별도 컨텍스트의 에이전트에게 위임하는 것이다. 핵심 효용은 병렬성보다 컨텍스트 격리다. 예컨대 "저장소 전체에서 deprecated API 사용처 탐색"을 메인 루프에서 수행하면 수십 개 파일의 내용이 메인 컨텍스트에 쌓여 이후 판단을 오염시킨다. 서브에이전트에 위임하면 메인 컨텍스트에는 요약 결과만 돌아온다. 대신 비용도 있다: 서브에이전트는 메인의 맥락을 모르는 채 시작하므로 위임 지시문에 맥락을 다시 담아야 하고, 잘못 요약하면 메인이 원본을 다시 탐색해야 한다. 읽기 중심의 대량 탐색·독립 리뷰에는 이득이 크고, 맥락 의존도가 높은 구현 작업에는 손해라는 것이 기본 판단선이다.

실무 관점 ​

안티패턴 카탈로그 ​

안티패턴무엇이 잘못되는가교정
"전체 앱을 개선해 줘"검증 단위 없음, 컨텍스트 초과, diff 리뷰 불가개선 후보 목록화(탐색 루프) → 항목별 작업 명세
"알아서 테스트해 줘"'테스트했다'의 기준이 없어 형식적 테스트로 종료검증 명령과 커버해야 할 상태·경계를 명세에 명시
검증 명령 없는 구현 요청에이전트가 편집만 하고 종료, 검증은 사람 몫으로 전가성공 조건에 실행 가능한 명령 포함
리팩터링 + 기능 추가 동시 위임diff에서 동작 변경과 구조 변경이 섞여 리뷰 불능별도 작업·별도 PR로 분리 (7-3 커밋 설계와 동일 원리)
실패를 숨긴 재시도같은 세션에서 "다시 해 봐"를 반복하면 실패 이력이 컨텍스트를 오염시키고, 무엇이 문제였는지 기록이 안 남음실패 원인을 귀인하고, 명세를 고쳐 새 세션에서 재시도
테스트 약화로 통과에이전트가 단언을 느슨하게 바꾸거나 skip 처리해 성공 조건을 '달성'멈출 조건에 "기존 테스트 수정 시 보고" 명시, diff에서 테스트 파일 우선 확인

마지막 항목은 특히 중요하다. 에이전트는 명세에 적힌 성공 조건을 문자 그대로 최적화하므로, 성공 조건이 조작 가능하면 조작된다. 이는 악의가 아니라 목표 명세와 실제 의도의 괴리이며, 사람이 만든 지표 기반 조직에서 벌어지는 굿하트의 법칙(Goodhart's law)과 같은 현상이다.

명세 작성 비용은 언제 회수되는가 ​

작업 명세를 쓰는 데 10분이 든다면, 5분짜리 수정 작업에는 배보다 배꼽이 크다. 판단 기준을 명시하면:

  • 일회성 + 사소한 작업: 명세 없이 대화형으로 진행하되, 검증 명령만은 지시에 포함한다.
  • 반복되는 작업 유형(버그 수정, 테스트 보강, 컴포넌트 추가): 유형별 템플릿을 만들어 두면 회당 명세 비용이 수 분으로 떨어진다. 템플릿은 실습 과제 A의 산출물이다.
  • 위험하거나 큰 작업: 명세 없이 시작하지 않는다. 명세 작성 중 발견하는 모호함("성공 조건을 뭐라고 쓰지?")이 그 자체로 작업이 아직 위임 가능한 상태가 아니라는 신호다.

마지막 문장은 뒤집어도 성립한다. 작업 명세가 써지지 않는 작업은 사람에게도 아직 명확하지 않은 작업이다. 에이전트 위임 준비가 요구사항 정리를 강제하는 부수 효과는 실무에서 무시할 수 없는 이득이다.

대화형 보정 vs 명세 수정 ​

작업 중간에 방향이 틀렸음을 발견했을 때 두 선택지가 있다. 같은 세션에서 대화로 보정하거나("아니, 그 파일 말고 이쪽을 봐"), 세션을 버리고 명세를 고쳐 새로 시작하거나. 보정 한두 번은 대화가 싸다. 그러나 보정이 누적되면 컨텍스트에 폐기된 접근, 실패 로그, 모순된 지시가 쌓여 판단 품질이 떨어진다(11-3의 컨텍스트 오염). 경험적 기준: 같은 오해를 두 번 교정하고 있다면, 그 오해를 만든 것은 명세다. 명세를 고쳐 새 세션에서 시작하는 것이 결과적으로 빠르다.

더 깊이 ​

왜 에이전트는 질문하지 않는가 ​

"모호하면 질문하라"고 지시문에 적어도 에이전트는 잘 질문하지 않는다. 구조적 이유가 있다. 모델은 대화 데이터와 강화학습으로 "주어진 목표를 완수하는" 방향으로 훈련되며, 하네스의 루프도 목표 완료를 종료 조건으로 설계된다. 질문은 루프를 중단하고 사람을 기다리는 행동이라 훈련 신호와 루프 설계 양쪽에서 선택되기 어렵다. 또한 모델의 관점에서 자신의 가설과 사실의 구분은 명확하지 않다 — 그럴듯한 해석이 곧 작업 가설이 된다.

실무 함의는 두 가지다. 첫째, 질문을 원하면 질문을 작업의 산출물로 요구해야 한다. "구현하기 전에, 이 명세에서 불명확한 점과 네가 세운 가정을 먼저 목록으로 보고하라"는 지시는 잘 작동한다. 질문이 루프 중단이 아니라 완료해야 할 단계가 되기 때문이다. 둘째, 계획 검토 단계가 질문의 대체재다. 에이전트가 묻지 않은 것을 계획에서 사람이 발견한다.

작업 명세와 형식 명세의 거리 ​

작업 명세의 "성공 조건 = 실행 가능한 검증 명령" 원칙을 끝까지 밀면 테스트 주도 개발(TDD)과 만난다. 실패하는 테스트를 먼저 작성하게 하고 통과를 목표로 주는 방식은 에이전트에서 특히 잘 작동하는데, 성공 판정이 완전히 기계화되어 루프가 자체 완결되기 때문이다. 다만 한계도 같다: 테스트가 명세의 전부가 되는 순간, 테스트에 없는 속성(성능, 접근성, 코드 구조)은 보장 범위 밖이다. 형식 명세가 불완전할 때 에이전트는 명세의 빈틈을 최적화한다. 그래서 검증 계층을 다층으로 두는 것이며, 이 설계는 11-5의 주제다.

관찰된 협업 데이터가 말하는 것 ​

The Rise of AI Teammates 연구(참고 자료)는 GitHub의 실제 PR 데이터에서 에이전트 협업의 현재 상태를 관찰한다. 요지는 에이전트 PR이 이미 무시할 수 없는 규모로 존재하고 생산 속도는 빠르지만, 병합률과 리뷰 신뢰에서 사람 PR과 격차가 있다는 것이다. Agentic Refactoring 연구는 에이전트가 수행하는 리팩터링이 사람 대비 특정 유형(기계적, 지역적 변경)에 몰리고 넓은 설계 변경에서는 품질이 떨어짐을 보고한다. 실무 번역: 현재 세대 에이전트에게 작업을 맡길 때 "기계적이고 지역적이며 검증 가능한" 방향으로 분해하는 이 문서의 원칙은 관찰 데이터와 부합하며, 넓은 설계 변경의 분해와 검토는 여전히 사람의 부가가치가 큰 지점이다.

정리 ​

  • 작업 크기의 상한은 검증 가능성이 정한다: 검증 명령 하나로 판정 가능하고, PR 하나로 리뷰 가능한 단위가 실용적 기준이다.
  • 탐색·계획은 읽기 전용 루프로 분리하고 사람이 계획을 검토한 뒤 구현을 허용하는 것이, 가장 싼 지점에서 방향 오류를 잡는 워크플로다.
  • 작업 명세는 목표, 재현, 범위와 경계, 성공 조건, 멈출 조건을 갖춘다. 특히 멈출 조건이 없으면 에이전트는 테스트 약화 같은 방식으로 성공 조건을 조작할 수 있다.
  • 프론트엔드 작업의 성공 조건에는 테스트 외에 UI 상태표, 접근성, 뷰포트, 브라우저 실증, 성능 측정을 명시해야 한다. 명시하지 않은 속성은 보장되지 않는다.
  • 병렬 에이전트는 파일 경계가 독립일 때만, 서브에이전트는 컨텍스트 격리 이득이 맥락 전달 비용을 넘을 때(대량 탐색, 독립 리뷰) 사용한다.

확인 문제 ​

  1. 동료가 에이전트에게 "주문 페이지가 느리니 성능을 개선해 줘"라고 요청했고, 에이전트는 12개 파일에 useMemo를 추가한 diff를 제출했다. 이 워크플로의 문제를 세 가지 이상 짚고, 작업 명세를 어떻게 다시 쓸지 개요를 제시하라.
정답과 해설

문제: ① 성공 조건이 없다 — "느리다"의 측정 근거도, "개선됐다"의 판정 기준도 없어 에이전트는 성능 개선처럼 보이는 패턴(useMemo 살포)을 적용하는 것으로 목표를 '달성'했다. ② 탐색·측정 단계 없이 구현으로 직행했다 — 병목이 리렌더인지, 번들 크기인지, 네트워크인지 진단이 없다. ③ 파일 경계가 없어 12개 파일 diff가 됐고 리뷰가 어렵다. ④ 측정 없는 useMemo 살포는 5-5에서 다뤘듯 역효과일 수 있다. 재작성 개요: 1단계(읽기 전용) — "주문 페이지를 React Profiler와 DevTools Performance로 계측해 병목 후보를 근거와 함께 보고하라". 사람이 병목을 확인하고 개선 대상을 선정. 2단계 — 선정된 병목 하나에 대해 "대상 파일 경계, 변경 전후 측정치 첨부(Profiler 리렌더 횟수 또는 LCP/INP), 기존 테스트 회귀 없음"을 성공 조건으로 하는 구현 명세를 작성한다.

  1. 에이전트가 버그 수정 작업 중 "기존 테스트 3개가 새 동작과 맞지 않아 수정했다"고 보고하며 모든 검증 통과를 제시했다. 이 상황에서 무엇을 의심하고 어떤 순서로 확인해야 하는가?
정답과 해설

의심할 것: 테스트 약화로 성공 조건을 '달성'했을 가능성. 에이전트는 명세의 성공 조건(테스트 통과)을 문자 그대로 최적화하므로, 코드를 고치는 대신 테스트를 고치는 경로도 선택할 수 있다. 확인 순서: ① diff에서 테스트 파일 변경을 먼저 본다 — 단언이 느슨해졌는지(값 검증 → 존재 검증), 케이스가 삭제·skip됐는지. ② 수정된 테스트가 검증하던 원래 동작이 실제로 '의도가 바뀐 동작'인지 요구사항과 대조한다. 버그 수정이라면 기존 의도는 대체로 유효해야 하므로 3개나 수정된 것은 이상 신호다. ③ 정당한 수정이라면 그 이유가 PR 설명에 남아야 한다. 예방책: 작업 명세의 멈출 조건에 "기존 테스트를 수정해야 통과한다면 멈추고 보고하라"를 명시하는 것이다.

  1. 세 가지 작업이 있다: (a) 저장소 전체에서 접근성 label 누락 후보 조사, (b) 조사 결과 중 상위 10건 수정, (c) 결제 플로우 컴포넌트 구조 리팩터링. 병렬 에이전트/서브에이전트/단일 세션 중 각각에 적합한 실행 형태와 근거를 제시하라.
정답과 해설

(a) 서브에이전트 적합. 읽기 전용 대량 탐색이라 위험이 없고, 수십 파일의 내용이 메인 컨텍스트에 쌓이는 오염을 격리할 수 있다. 산출물은 요약된 후보 목록만 메인으로 돌아온다. (b) 병렬 에이전트 후보. 각 수정이 서로 다른 컴포넌트 파일에 국한되면 파일 경계가 독립이므로 worktree 격리 하에 병렬화할 수 있다. 단, 공통 컴포넌트(예: 공용 Input)를 여러 건이 건드리면 경계가 겹치므로 그 건들은 직렬화한다. (c) 단일 세션(+ 계획 검토) 적합. 결제 플로우는 위험도가 높고 변경 간 맥락 의존이 강해 병렬 분해 시 통합 비용이 이득을 잠식한다. 리팩터링이므로 동작 보존 검증(기존 테스트, 필요시 특성화 테스트 추가)을 성공 조건으로 하고, 기능 변경과 절대 섞지 않는다.

참고 자료 ​