본문으로 바로가기
리옵트 핸드북
리옵트 핸드북
Vercel 엔터프라이즈 AI 플랫폼

플랫폼 기초

플랫폼 아키텍처AI SDK 런타임AI Gateway 제어면

실행 런타임

Workflow 장기 실행Sandbox 실행 격리MCP 데이터 계층Queues & 비동기 작업 관리

프롬프트 & 품질

프롬프트 엔지니어링 & 가드레일RAG & 검색 증강 생성관측성·평가

운영 체계

보안·거버넌스비용·안정성배포 전략 & AI CI/CD

실전 시나리오

고객지원 에이전트 아키텍처내부 리서치 에이전트 아키텍처승인형 백오피스 자동화코딩 오케스트레이션

오케스트레이션 패턴

그래프 중심 오케스트레이션실무 오케스트레이션 플레이북멀티 에이전트 아키텍처

부록

마이그레이션 가이드레퍼런스검증 리포트업데이트 내역
핸드북›Vercel 엔터프라이즈 AI›코딩 오케스트레이션
한국어KOEnglishEN

코딩 오케스트레이션

repo-aware coding agent를 이슈 수집부터 계획, 코드 수정, 테스트, PR 초안까지 연결하는 운영 체계를 정리합니다.

핵심 요약

  • 코딩 오케스트레이션은 단일 super-agent가 아니라 plan -> implement -> test -> draft PR -> approval 체인으로 분리합니다.
  • Next.js 16.2는 로컬 문서를 포함하며 16.3+는 AGENTS.md의 문서 지침을 관리합니다. 팀 규칙은 관리 블록 밖에 적고 CI에서도 검증합니다.
  • 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는 설치 버전의 문서를 node_modules/next/dist/docs/에 포함합니다. **16.3+**는 새 프로젝트 생성 또는 에이전트가 감지된 next dev 실행 시 managed instructions를 생성·갱신합니다. 팀의 코딩·배포 규칙은 관리 블록 밖에 유지합니다.

기능코딩 오케스트레이션 영향
버전별 문서와 managed instructions설치 버전에 맞는 API를 먼저 확인하도록 안내
nextjs_index·nextjs_call실행 중인 개발 서버를 발견하고 오류·로그·라우트 등의 도구 호출
browser_eval 안내agent-browser CLI로 실제 페이지를 확인하는 절차 연결

AGENTS.md는 에이전트 지침이며 권한 시스템을 대신하지 않습니다. branch protection과 CI에서 필수 검사·merge 정책을 집행하고, 실행 결과를 PR에 남깁니다.

Next.js AI agents · Next.js MCP.

언제 이 패턴을 쓰는가

조건적합도이유
이슈 → 계획 → 구현 → 테스트 → PR 초안을 자동화하고 싶음높음체인 분리가 필요
repo-aware context가 중요함높음subagent + sandbox 조합이 적합
무인 머지를 목표로 함낮음human approval 필요

권장 아키텍처

계층별 책임

계층책임구현 포인트
Intake이슈/티켓 수집Git provider webhook
Plan Agent작업 분해, acceptance criteriaAI SDK subagent
Dev Agent코드 수정repo-aware loop
Runtimegit, shell, testsSandbox
ApprovalPR 검토와 merge 판단human gate

작업 흐름

단계동작핵심 통제
1issue 수신repo / branch scope
2계획 생성acceptance criteria 고정
3sandbox에서 코드 수정branch isolation
4lint / test / typecheck 실행deterministic gate
5PR 초안 생성summary / risk list
6human 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-5.5',
  instructions: 'Plan a small, reviewable repository change with acceptance criteria.',
})

보안·거버넌스 포인트

통제이유
branch isolationmain 보호
sandboxed git/shell실행 격리
deterministic checkshallucinated 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 count3회 이하
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되지 않는가

관련 문서

  • Agents: Subagents
  • Agents: Loop Control
  • Sandbox SDK Reference
  • AI Agents on Vercel

관련 문서

그래프 중심 오케스트레이션

LangGraph 스타일의 graph/state-machine 사고방식을 Vercel의 code-first orchestration으로 매핑하는 방법을 정리합니다.

실전 아키텍처 사례

AI 에이전트 오케스트레이션 패턴 · 고객 지원, 코드 생성, 리서치, 데이터 파이프라인 — 4가지 사례를 패턴 조합으로 분석

실무 오케스트레이션 플레이북

ticket triage, alert triage, approval queue, scheduled reporting 같은 실무 runbook형 오케스트레이션 예제를 정리합니다.

에러 처리와 복구 전략

AI 에이전트 오케스트레이션 패턴 · 재시도/폴백/서킷브레이커, 에이전트 실패 격리, Human-in-the-Loop, 부분 실패 복구

Next.js AI 세팅

Windows 바이브코딩 초기 세팅 · Next.js 16.4.2에서 설치 버전 문서·AGENTS.md·개발 서버·MCP를 연결합니다.

On this page

AGENTS.md와 에이전트 DevTools언제 이 패턴을 쓰는가권장 아키텍처계층별 책임작업 흐름최소 구현 스켈레톤보안·거버넌스 포인트실패 모드와 fallback운영 지표ADR 스타일 결론실무 체크리스트관련 문서