최근의 코딩 에이전트(coding agent)는 이제 단순히 "에디터에서 똑똑하게 보완해 주는 것"에 그치지 않습니다.

이슈(issue)를 전달한다. 에이전트(agent)가 브랜치(branch)를 생성한다. 구현한다. PR(Pull Request)을 올린다. 인간은 디프(diff)와 테스트 결과를 확인한다.

이러한 흐름이 되면 확인해야 할 대상이 달라집니다. 모델이 얼마나 똑똑한가보다, 어느 정도의 입도(granularity)로 업무를 던져야 리뷰(review) 가능한 PR이 될 것인가가 훨씬 더 중요합니다.

대충 던지면, 에이전트의 작업 시간보다 인간의 리뷰 시간이 더 많이 들게 됩니다.

사용량 기반 과금(usage-based billing) 이야기가 나오면, 무심코 "토큰(token)을 얼마나 썼나", "비용이 얼마나 들었나"에 눈길이 갑니다. 물론 그것도 중요합니다.

하지만 프론트엔드 레포지토리(frontend repo)에서 실제로 힘든 점은 대개 그 이후입니다.

• PR이 너무 커서 읽을 의욕이 사라진다
• 목적과 상관없는 컴포넌트(component)까지 변경되어 있다
• UI는 그럴싸하게 동작하지만, 어디를 확인해야 할지 모르겠다
• 재작업을 요청할 때마다 디프(diff)가 다른 방향으로 넓어진다
• 결국 인간이 직접 떠맡아서 수정한다

이것은 과금과는 별개의 비용입니다. 리뷰 큐(review queue)의 정체, 재실행, 롤백(rollback), 동작 확인. 거기까지 포함해서 에이전트 태스크(agent task)의 비용이라고 생각하는 것이 좋습니다.

에이전트에게는 작은 업무를 전달하는 것이 안전하다는 감각이 있습니다. 절반은 맞습니다. 변경 범위가 좁으면 리뷰는 편해집니다.

하지만 너무 작은 태스크(task)는 고정비에 패배합니다.

예를 들어 다음과 같습니다.

button의 margin을 4px만 줄여줘

인간이라면 30초 만에 고칠 수 있을지도 모릅니다. 하지만 에이전트에게 맡기면 매번 이런 고정비가 발생합니다.

• 레포지토리(repo)를 읽는다
• 해당 파일(file)을 찾는다
• 브랜치(branch) / 디프(diff)를 만든다
• 필요에 따라 테스트(test)나 린트(lint)를 돌린다
• PR 설명(description)을 작성한다
• 인간이 디프(diff)를 확인한다

이러한 고정비가 있기 때문에, 1px 수정, 문구 1개, import 정리만을 전부 에이전트 큐(agent queue)에 쌓아두면 오히려 느려집니다.

작은 태스크(task)가 적합한 경우는 성공 조건이 명확하고, 동일한 패턴을 반복하는 경우입니다.

모든 폼(form)의 submit button에 disabled 상태 중의 aria-busy를 추가할 것.
대상은 app 하위의 form component로 한정.
copy, routing, validation schema는 변경하지 말 것.

이것은 작지만 에이전트에게 맡길 가치가 있습니다. 탐색과 반복이 있기 때문입니다.

반대로, 다음과 같은 의뢰는 상당히 위험합니다.

dashboard를 사용하기 편하게 만들어줘

에이전트는 아마 무언가를 만들어낼 것입니다. 레이아웃(layout)을 바꾸거나, 카드(card)를 나누거나, 색상을 조정할 것입니다. 상태(state)를 관리하는 방식까지 바꿀지도 모릅니다.

문제는 PR이 나온 이후입니다.

프론트엔드(frontend)의 변경은 확산되기 쉽습니다.

• component
• route
• state
• CSS
• copy
• test
• mock data
• asset

이것들이 하나의 PR에 섞이면, 리뷰하는 인간은 "맞는지"가 아니라 "무슨 일이 일어났는지"부터 파악해야 합니다. 이것은 비용이 많이 듭니다.

큰 태스크(task)를 던지고 싶다면, 구현까지 한꺼번에 시키기보다 처음에 분해하도록 시키는 것이 다루기 쉽습니다.

먼저 dashboard 개선을 위한 조사만 해주세요.
구현은 하지 마세요.
현재의 component 구성, 상태 관리, 시각적으로 막혀 있는 부분, 분할 가능한 작업 단위를 정리해 주세요.

그 후에, 1 PR씩 끊어서 진행합니다.

Task 1: KPI cards의 mobile overflow만 수정
Task 2: chart tooltip의 currency format만 수정
Task 3: empty state copy와 icon만 교체

에이전트에게 맡기는 단위는 에이전트가 이해할 수 있는 단위가 아니라, 인간이 짧은 시간 안에 확인하고 피드백을 줄 수 있는 단위로 하는 것이 좋습니다.

저라면 에이전트에게 던지는 태스크(task)를 볼 때 다음 조건들을 확인합니다.

• 목적을 한 문장으로 말할 수 있다
• 수정해도 되는 파일(file)과 수정하면 안 되는 파일이 대략적으로 정해져 있다
• 성공 조건(success condition)을 커맨드(command)나 스크린샷(screenshot)으로 확인할 수 있다
• 실패했을 때 브랜치(branch)째로 버릴 수 있다
• 리뷰 코멘트(review comment)가 두 번 왕복해도 논점이 너무 많아지지 않는다

예를 들어, 프론트엔드(frontend) 레포지토리(repo)라면 이 정도가 다루기 쉽습니다.

Task:
- Fix the mobile header overflow on `/pricing`.
- Touch only header/navigation components and related CSS.
...

포인트는 "무엇을 하는가"만이 아닙니다.

"무엇을 하지 않는가"와 "어떻게 확인하는가"까지 쓰는 것입니다.

에이전트(agent)는 좋든 나쁘든 친절합니다. 여백을 수정해 달라고 하면, 덤으로 외관을 정돈하기도 합니다. 인간이라면 분위기를 파악하고 멈출 지점에서, 에이전트는 레포지토리(repo) 전체의 개선으로 해석할 수 있습니다.

그래서 금지 사항을 명시합니다.

Do not:
- change package.json
- change route structure
...

이것을 쓰는 것만으로도 리뷰(review)의 초점을 상당히 좁힐 수 있습니다.

UI 태스크(task)라도, 처음에 보는 것은 화면보다 디프(diff)면 충분하다고 생각합니다.

git diff --stat
git diff -- app components
git diff -- package.json pnpm-lock.yaml

header overflow 수정인데 package.json이 바뀌어 있다면, 우선 중단합니다. 의존성(dependency)이 정말로 필요하다면 설명할 수 있어야 합니다. 설명할 수 없다면, 아마 불필요한 변경일 것입니다.

git diff --stat은 대충 보는 것 같아도 유용합니다.

app/components/Header.tsx | 18 ++++++---
app/components/NavMenu.tsx | 12 ++++--
app/styles/navigation.css | 24 ++++++++++--
...

이 디프(diff)라면, 우선 락파일(lockfile)을 의심합니다.

반대로, 이런 디프(diff)라면 리뷰(review)에 들어가기 쉽습니다.

app/components/Header.tsx | 18 ++++++++++----
app/components/NavMenu.tsx | 12 ++++++---
app/styles/navigation.css | 24 +++++++++++++-----

범위가 태스크 계약(task contract)과 일치하기 때문입니다.

프론트엔드(frontend) 태스크(task)는 테스트(test)가 통과해도 UI가 깨져 있을 수 있습니다.

그러므로 UI 변경을 에이전트(agent)에게 맡긴다면 뷰포트(viewport)를 지정하는 것이 좋습니다.

Validate:
- /pricing at 390x844
- /pricing at 1280x800
...

Playwright가 있다면, 최소한 이 정도의 스펙(spec)은 추가하도록 해도 좋습니다.

import { expect, test } from "@playwright/test";
test("pricing header does not overflow on mobile", async ({ page }) => {
await page.setViewportSize({ width: 390, height: 844 });
...

실제로는 overflow-x 검출은 프로젝트(project)마다 조정이 필요합니다. 그 부분은 대충 해도 됩니다. 중요한 것은 에이전트(agent)와 인간이 같은 화면을 볼 수 있는 상태로 만드는 것입니다.

다음 의뢰도 편해집니다.

지난번에 추가한 pricing header의 mobile check가 통과하는 범위 내에서,
menu button의 tap target만 44px로 해주세요.

이렇게 되면 에이전트(agent)는 작업하기 쉽고, 인간도 제어하기 쉽습니다.

에이전트 태스크(agent task)의 좋고 나쁨은 성공했을 때보다 실패했을 때 드러납니다.

좋은 태스크(task)는 실패했을 때 브랜치(branch)째로 버릴 수 있습니다.

git switch main
git branch -D agent/pricing-header-overflow

이 정도로 끝날 수 있다면 저렴한 편입니다.

나쁜 task는 실패한 branch에서 쓸만한 변경 사항만 골라내게 됩니다.

• 이 CSS는 쓸 수 있다
• 하지만 component 분할은 되돌리고 싶다
• test는 참고가 된다
• copy(문구)가 멋대로 바뀌어 있다
• lockfile은 필요 없다

이렇게 되면 agent에게 맡긴 의미가 퇴색됩니다. 사람이 merge conflict와 선별 작업을 하고 있는 셈입니다.

따라서 task는 "구현할 수 있는가"보다 "버릴 수 있는가"를 기준으로 나누는 것이 실무적입니다.

Copilot, Codex, Claude Code의 비교는 흥미롭습니다. 어떤 것이 빠른지, 어떤 것이 repo를 읽을 수 있는지, 어떤 것이 자연스러운 diff를 내는지 말이죠.

하지만 비동기 agent의 본질은 IDE 비교만으로는 보이지 않습니다.

실제로 운용해 보면 문제는 queue(대기열)가 됩니다.

• 어떤 task를 먼저 던질 것인가
• 어떤 PR부터 review 할 것인가
• 어디서 stop(중단)할 것인가
• 실패한 task를 재실행할 것인가, 버릴 것인가
• 동일한 area에 여러 agent를 투입하지 않을 것인가

이 부분을 결정하지 않으면, agent는 움직이고 있는데 사람은 막히게 됩니다.

저라면 frontend repo의 agent queue를 다음과 같이 나눕니다.

Good:
- scoped bug fix with known route
- repeated mechanical migration
...

특히 dependency upgrade plus UI fix는 분리하는 것이 좋습니다. 실패했을 때 원인을 파악하기 어려워지기 때문입니다.

마지막으로, 제가 직접 사용한다면 이런 형식을 취하겠습니다.

Goal:
- Fix mobile overflow in the pricing header.
Allowed scope:
...

이 Stop if가 꽤 효과적입니다.

agent에게도 "여기서부터는 멋대로 진행하지 않아도 된다"라고 전달하는 것이 좋습니다. 인간의 개발에서도 마찬가지입니다. 조사해 보니 생각보다 큰 문제였다는 일은 흔히 발생합니다.

그럴 때 억지로 PR을 완성시키기보다, 멈춰서 보고해 주는 편이 도움이 됩니다.

agent에게 맡기는 일이 작을수록 안전하다는 뜻은 아닙니다.

너무 작은 task는 고정비에 밀립니다. 너무 큰 task는 review queue를 망가뜨립니다.

적절한 입도(granularity)는 agent가 구현할 수 있는 단위가 아니라, 사람이 짧은 시간 안에 확인하고, 안 된다면 branch째로 버릴 수 있는 단위입니다.

AI coding agent를 개발 흐름에 도입하려면 prompt를 잘 쓰는 것만으로는 부족합니다. task contract, diff를 보는 법, screenshot 성공 조건, stop rule. 여기까지 포함하여 설계해야 아마 더 오래 사용할 수 있을 것입니다.

• GitHub Copilot coding agent docs: issue에서 branch / PR까지 진행되는 비동기 agent workflow의 전제 조건 확인.
• GitHub Copilot usage-based billing note: agent 이용을 "무료 보완"이 아니라, 사용량과 운용 비용을 가진 작업으로 바라보기 위한 배경.
• OpenAI Codex and Claude Code docs: repo, task, diff, validation을 아우르는 coding agent의 작업 측면을 파악하기 위한 보조선.