코딩 오케스트레이션
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 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-5.5',
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되지 않는가