흔한 실수와 안티패턴

실수 1: 제어 흐름 과도한 설계

가장 흔하고 파괴적인 실수입니다. 에이전트의 모든 행동을 미리 예측하고 분기 처리하려는 충동입니다.

안티패턴

// ❌ 과도한 제어 흐름
async function runAgent(task: string) {
  if (task.includes('create')) {
    if (task.includes('component')) {
      return await handleComponentCreation(task)
    } else if (task.includes('test')) {
      return await handleTestCreation(task)
    } else if (task.includes('api')) {
      return await handleApiCreation(task)
    }
  } else if (task.includes('fix')) {
    if (task.includes('bug')) {
      return await handleBugFix(task)
    } else if (task.includes('type')) {
      return await handleTypeFix(task)
    }
  }
  // ... 분기가 기하급수적으로 증가
}

올바른 접근

// ✅ 모델에게 분류를 위임
async function runAgent(task: string) {
  // 분기 로직 대신 모델이 적절히 판단하도록 컨텍스트 제공
  return await agent.run({
    task,
    availableTools: TOOL_REGISTRY,
    constraints: AGENTS_MD_CONSTRAINTS
  })
}

실수 2: 정적 하네스 설계

한 번 만들고 영원히 변하지 않는 하네스는 점점 현실과 괴리됩니다.

증상

처음 설계 시 (2024):
  - 시스템 프롬프트에 상세한 단계별 지침 포함
  - 엄격한 출력 형식 파서
  - 모델의 한계를 보완하는 복잡한 scaffolding

현재 (2026):
  - 모델이 이미 단계별 지침 없이도 올바르게 작동
  - 출력 형식이 자연스럽게 일관됨
  - Scaffolding이 오히려 모델의 능력을 제한

올바른 접근: 피드백 루프 구축

interface HarnessMetrics {
  successRate: number
  avgTokensUsed: number
  avgLatencyMs: number
  errorPatterns: string[]
}

async function evaluateAndAdaptHarness(
  currentConfig: HarnessConfig,
  metrics: HarnessMetrics
): Promise<HarnessConfig> {
  // 성공률이 높으면 제약을 완화
  if (metrics.successRate > 0.9) {
    return {
      ...currentConfig,
      systemPromptLength: Math.max(500, currentConfig.systemPromptLength * 0.8),
      scaffoldingLevel: 'minimal'
    }
  }

  // 특정 에러 패턴이 반복되면 해당 부분만 강화
  if (metrics.errorPatterns.includes('missing_tests')) {
    return {
      ...currentConfig,
      constraints: [...currentConfig.constraints, 'ALWAYS write tests first']
    }
  }

  return currentConfig
}

실수 3: 약한 문서화 레이어

“에이전트가 알아서 이해하겠지”라는 가정으로 문서를 소홀히 하는 패턴입니다.

안티패턴 예시

<!-- ❌ 너무 추상적인 AGENTS.md -->
# 컨벤션
- 좋은 코드 작성
- 테스트 잊지 말기
- 보안에 신경 쓰기

올바른 접근

<!-- ✅ 구체적이고 검증 가능한 AGENTS.md -->
# 컨벤션

## 함수 작성 규칙
- 모든 함수는 50줄 이하
- 명시적 반환 타입 필수: `function foo(): string`
- 에러는 반드시 `throw new Error('메시지')` 또는 `Result<T>` 타입으로 처리

## 테스트 작성 규칙
- 새 함수 작성 시 `tests/` 폴더에 동일 경로 테스트 파일 생성 필수
- 각 테스트 파일에 최소 3개 테스트: 정상 케이스, 엣지 케이스, 에러 케이스
- `pnpm test` 로 전체 통과 확인 후 커밋

## 보안 규칙
- `.env` 파일 절대 읽지 않음 (process.env 사용)
- SQL 쿼리 직접 문자열 연결 금지 (parameterized query 사용)
- console.log에 사용자 데이터 포함 금지

실수 4: 피드백 루프 부재

에이전트가 무엇을 잘하고 못하는지 측정하지 않으면 개선이 불가능합니다.

안티패턴

에이전트 실행 → 결과 확인 → 수동으로 다시 실행
(무엇이 실패했는지, 왜 실패했는지 기록 없음)

올바른 접근

interface AgentRun {
  id: string
  task: string
  model: string
  success: boolean
  errorType?: string
  tokensUsed: number
  durationMs: number
  humanFeedback?: 'approved' | 'rejected' | 'modified'
}

class FeedbackCollector {
  private runs: AgentRun[] = []

  record(run: AgentRun): void {
    this.runs.push(run)
    this.persistToStorage(run)
  }

  getWeeklyReport(): Record<string, unknown> {
    const recent = this.runs.filter(
      r => Date.now() - r.id.timestamp < 7 * 24 * 60 * 60 * 1000
    )
    return {
      successRate: recent.filter(r => r.success).length / recent.length,
      topErrors: this.groupBy(recent.filter(r => !r.success), 'errorType'),
      avgTokens: recent.reduce((sum, r) => sum + r.tokensUsed, 0) / recent.length,
      humanApprovalRate: recent.filter(r => r.humanFeedback === 'approved').length / recent.length
    }
  }

  private groupBy<T>(arr: T[], key: keyof T): Record<string, number> {
    return arr.reduce((acc, item) => {
      const k = String(item[key] ?? 'unknown')
      acc[k] = (acc[k] ?? 0) + 1
      return acc
    }, {} as Record<string, number>)
  }

  private persistToStorage(run: AgentRun): void {
    // DB 또는 파일 시스템에 저장
  }
}

실수 5: 인간 전용 문서

Confluence, Notion, 이메일, Slack에만 존재하는 지식은 에이전트에게 없는 것과 같습니다.

문서 이전 체크리스트

팀에서 사용하는 문서 목록 작성
    ↓
각 문서에 대해 질문: "에이전트가 이 정보를 필요로 하는가?"
    ↓
필요하다면 → 레포지토리로 이전 (AGENTS.md, docs/, ADR)
필요 없다면 → 그대로 유지 (HR 정책, 회의록 등)

이전 우선순위

우선순위	문서 종류	이전 위치
최우선	코딩 컨벤션	`AGENTS.md`
높음	아키텍처 결정	`docs/adr/`
높음	API 스펙	`docs/api/`
중간	온보딩 가이드	`docs/setup.md`
낮음	프로세스 문서	`docs/process/`

추가 안티패턴 모음

안티패턴	증상	해결책
모든 도구 허용	에이전트가 예상치 못한 파일 수정	명시적 허용 목록으로 도구 제한
무한 루프 허용	에이전트가 무한히 재시도	최대 시도 횟수 + 타임아웃 설정
에러 무시	실패를 조용히 넘어감	모든 에러를 로깅하고 에스컬레이션
컨텍스트 과부하	토큰 한도 초과로 중요 정보 누락	컨텍스트 압축 전략 + 우선순위 설정
단일 에이전트 집중	병렬화 불가, 단일 실패 지점	작업 분해 + 병렬 에이전트 설계

요약

Agent Harness의 흔한 실수는 과도한 제어, 정적 설계, 약한 문서, 피드백 부재, 인간 전용 지식입니다. 이 다섯 가지를 피하는 핵심 원칙은 단순하고, 측정하고, 적응하라입니다. 모델의 발전 속도를 감안하면 복잡한 하네스보다 단순하고 교체하기 쉬운 하네스가 더 오래 가치를 유지합니다.