코딩 오케스트레이션
repo-aware coding agent를 이슈 수집부터 계획, 코드 수정, 테스트, PR 초안까지 연결하는 운영 체계를 정리합니다.
핵심 요약
- 코딩 오케스트레이션은 단일 super-agent가 아니라
plan -> implement -> test -> draft PR -> approval체인으로 분리합니다. - Next.js 16.2.0부터
create-next-app이 생성하는AGENTS.md에 push 금지·typecheck 필수 같은 규칙을 적으면 Planning/Dev Agent가 이를 따릅니다. - repo-aware context는 Sandbox와 branch isolation으로 다뤄 main을 보호합니다.
- lint/test/typecheck를 deterministic gate로 붙여 hallucinated success를 차단합니다.
- merge 권한은 항상 human approval 뒤에 두고, PR은 draft 상태로만 생성합니다.
코딩 오케스트레이션은 "코드를 잘 쓰는 모델"의 문제가 아니라 코딩 작업 체인을 어떻게 분리하고 통제하느냐의 문제입니다.
이 시나리오에서는 코드 생성 자체보다 repo context, test gate, PR 품질, human approval이 더 중요합니다.
AGENTS.md와 에이전트 DevTools
Next.js 16.2.0부터 create-next-app이 AGENTS.md 파일을 기본으로 만듭니다. 코딩 에이전트 운영에 미치는 영향은 다음과 같습니다.
| 기능 | 코딩 오케스트레이션 영향 |
|---|---|
| AGENTS.md 기본 생성 | 프로젝트별 코딩 규칙, 테스트 게이트, 금지 패턴을 에이전트에 자동 전달 |
| 에이전트 DevTools (next-browser) | 코딩 에이전트가 브라우저 렌더링 결과를 시각적으로 검증 가능 |
| next-devtools-mcp | DevTools를 MCP 서버로 노출 — 에이전트가 빌드 오류, 라우트 구조, 컴포넌트 트리를 프로그래밍 방식으로 조회 |
실무 활용
AGENTS.md에 main 브랜치 직접 push 금지, typecheck 통과 필수, PR은 draft로 생성 같은 규칙을 적어 두면 Planning Agent와 Dev Agent가 그대로 따릅니다. sandbox 안에서 next-devtools-mcp를 붙이면 에이전트가 빌드 상태를 직접 확인하면서 수정 루프를 돌립니다.
언제 이 패턴을 쓰는가
| 조건 | 적합도 | 이유 |
|---|---|---|
| 이슈 → 계획 → 구현 → 테스트 → PR 초안을 자동화하고 싶음 | 높음 | 체인 분리가 필요 |
| repo-aware context가 중요함 | 높음 | subagent + sandbox 조합이 적합 |
| 무인 머지를 목표로 함 | 낮음 | human approval 필요 |
권장 아키텍처
계층별 책임
| 계층 | 책임 | 구현 포인트 |
|---|---|---|
| Intake | 이슈/티켓 수집 | Git provider webhook |
| Plan Agent | 작업 분해, acceptance criteria | AI SDK subagent |
| Dev Agent | 코드 수정 | repo-aware loop |
| Runtime | git, shell, tests | Sandbox |
| Approval | PR 검토와 merge 판단 | human gate |
작업 흐름
| 단계 | 동작 | 핵심 통제 |
|---|---|---|
| 1 | issue 수신 | repo / branch scope |
| 2 | 계획 생성 | acceptance criteria 고정 |
| 3 | sandbox에서 코드 수정 | branch isolation |
| 4 | lint / test / typecheck 실행 | deterministic gate |
| 5 | PR 초안 생성 | summary / risk list |
| 6 | human approval 후 merge queue | 최종 승인 |
최소 구현 스켈레톤
import { ToolLoopAgent } from 'ai'
export async function codingWorkflow(issueId: string) {
'use workflow'
const issue = await loadIssueStep(issueId)
const plan = await planTaskStep(issue)
const result = await implementInSandboxStep({ issue, plan })
const checks = await runRepoChecksStep(result.branch)
return { result, checks }
}
async function loadIssueStep(issueId: string) {
'use step'
return loadIssue(issueId)
}
async function planTaskStep(issue: Issue) {
'use step'
return planningAgent.generate({ prompt: issue.body })
}
async function implementInSandboxStep(input: { issue: Issue; plan: unknown }) {
'use step'
return runCodingTaskInSandbox(input)
}
async function runRepoChecksStep(branch: string) {
'use step'
return runRepoChecks(branch)
}
const planningAgent = new ToolLoopAgent({
model: 'anthropic/claude-sonnet-4.6',
instructions: 'Plan a small, reviewable repository change with acceptance criteria.',
})보안·거버넌스 포인트
| 통제 | 이유 |
|---|---|
| branch isolation | main 보호 |
| sandboxed git/shell | 실행 격리 |
| deterministic checks | hallucinated success 차단 |
| human approval before merge | 코드 품질 최종 보증 |
실패 모드와 fallback
| 실패 모드 | 대응 |
|---|---|
| 잘못된 계획 수립 | planning step 재실행 |
| 코드 수정 실패 | sandbox rollback / branch discard |
| 테스트 실패 | fix loop 제한 후 human handoff |
| PR 설명 부정확 | draft PR 상태로만 생성 |
운영 지표
| 지표 | 목표 예시 |
|---|---|
| issue-to-draft-PR 시간 | 수시간 이내 |
| check pass rate | 점진 상승 |
| rework loop count | 3회 이하 |
| human rejection rate | 모델/플랜 품질 지표 |
ADR 스타일 결론
Decision
코딩 오케스트레이션은 단일 super-agent가 아니라 plan -> implement -> test -> draft PR -> approval
체인으로 분리합니다. repo-aware context는 sandbox와 브랜치 격리로 다루고, merge 권한은 인간 승인 뒤에 둡니다.
실무 체크리스트
- main을 직접 수정하지 않고 branch isolation을 사용하는가
- 테스트와 타입체크가 deterministic gate로 붙어 있는가
- PR이 draft 상태로 생성되는가
- human approval 없이 merge되지 않는가