에이전틱 엔지니어링 — 구현 체크리스트
목차
1. 규칙 파일 설정
- 저장소 루트에
CLAUDE.md/AGENTS.md를 생성합니다. 10줄로 시작하세요. - 다음 네 가지 항목을 반드시 포함합니다.
- 스택 및 버전
- 컨벤션 (폴더 구조, 네이밍, 실제 사용 패턴)
- 에이전트가 절대 어겨서는 안 되는 규칙 (금지된 패키지, 시크릿 처리 방식, 레이어링)
- 코드 생성 전에 따라야 할 워크플로
- 에이전트가 원하지 않는 동작을 할 때마다 새로운 규칙을 추가합니다.
- 에이전트가 호출할 수 있는 도구와 각 도구의 사용 시점을 명시합니다 (API, 스크립트, DB 스키마).
- 아키텍처 결정은 직접 내리고, 에이전트가 선택하는 것이 아닌 구현하도록 합니다.
2. 컨텍스트 엔지니어링
- 정적 컨텍스트(항상 로드)와 동적 컨텍스트(필요 시 로드)를 구분합니다.
- 정적: 규칙 파일, 시스템 지침, 글로벌 메모리
- 동적: 스킬, 도구 실행 결과, 검색된 문서, 최근 히스토리
- 정적 컨텍스트는 간결하고 신호 밀도를 높게 유지합니다. 매 호출마다 필요하지 않은 내용은 제거합니다.
- 반복 가능한 노하우는 해당 태스크에 해당할 때만 로드되는 스킬로 분리합니다.
- 저장소 전체를 프롬프트에 붙여넣지 마세요. 관련된 내용만 검색하여 활용합니다.
3. 검증 체계 구축
- 기능 생성 전에 테스트를 먼저 작성합니다. 테스트는 곧 명세입니다.
- 비결정론적 부분에 대한 평가(eval)를 작성합니다.
- 에이전트가 합리적인 경로를 선택했는가?
- 올바른 도구를 선택했는가?
- 출력물이 품질 기준을 충족하는가?
- 결과(컴파일 성공, 테스트 통과)와 궤적(도달 과정) 모두를 확인합니다.
- 피드백 루프를 구성합니다.
- 벤치마크 스위트에 대해 실행
- 근본 원인별로 실패 사례 클러스터링
- 원인이 된 프롬프트 또는 도구를 수정
- 회귀 테스트 스위트 재실행
- 프로덕션에서 새로운 실패 모니터링
4. 작업 실행
- 태스크별로 적절한 모드를 선택합니다.
- 지휘자(Conductor) (실시간, IDE 내) — 복잡한 로직, 디버깅, 낯선 코드
- 오케스트레이터(Orchestrator) (비동기, 위임 후 리뷰) — 버그 수정, 마이그레이션, 테스트 생성
- 태스크별로 에이전트 위치를 선택합니다.
- 에디터 에이전트 — 인라인 편집 및 제안
- 터미널 에이전트 — 다중 파일 작업, 실행-반응 사이클
- 백그라운드 에이전트 — 자리를 비워도 되는 단락 단위 명세 태스크
- 승인된 도구만 사용하여 샌드박스 내에서 코드 생성을 실행합니다.
- 마지막 20%는 직접 처리합니다. 엣지 케이스, 에러 처리, 통합 지점, 비즈니스 로직. "올바르게 보이는" 코드에 버그가 숨어 있습니다.
5. 리뷰 및 배포
- 에이전트를 1차 리뷰어로 활용합니다 (버그, 스타일, 보안, 성능).
- 배포되는 모든 코드 라인을 직접 검토합니다.
- 영리해 보이는 코드는 의심합니다
- 임포트한 패키지가 실제로 존재하는지 확인합니다
- 현실적인 실패 시나리오에 대한 에러 처리를 점검합니다
- 커밋/편집 시점에 훅을 추가합니다 (예: 하드코딩된 시크릿이 포함된 커밋 차단).
- 관찰 가능성을 활성화합니다. 트레이스, 평가 결과, 토큰/레이턴시/비용, 드리프트.
- 미뤄왔던 레거시 작업에 에이전트를 투입합니다. 리팩터링, 마이그레이션, 더 이상 사용되지 않는 API.
6. 비용 제어
- 속도만이 아닌 총 소유 비용을 측정합니다.
- 타이트한 규칙 파일로 1차 성공률을 높여 재시도 루프를 방지합니다.
- 태스크별로 모델을 라우팅합니다.
- 프론티어 모델 — 아키텍처 설계 및 어려운 구현
- 저비용 모델 — 테스트 생성, 리뷰, CI 모니터링
- 동적 컨텍스트와 스킬을 활용하여 필요한 토큰에 대해서만 비용을 지불합니다.
7. 프로덕션 에이전트 배포
- 무엇을 구축하는지 명확히 합니다.
- 스크립트 — 에이전트 자체가 엔드포인트인 경우
- 실제 사용자를 위한 제품 — 에이전트에 기반 인프라(substrate)가 필요한 경우
- 제품이라면 다음을 추가합니다. 영구 메모리, 범위가 제한된 권한, CI의 평가 커버리지, 전체 실행 트레이싱.
- 스킬 번들을 사용하여 기존 코딩 에이전트가 빌드 → 평가 → 배포 → 관찰을 처리하도록 합니다.
- 멀티 에이전트 구성의 경우, 공유 상태로 조율하고, 도구에는 MCP를, 위임에는 A2A를 활용합니다.
8. 팀 표준으로 정착
- 규칙 파일, 프롬프트, 평가 스위트, 스킬을 버전 관리합니다. PR에서 리뷰하고 소유자를 지정합니다.
- 작동하는 데모가 아닌, 명확한 루브릭을 갖춘 평가 스위트 통과를 배포 기준으로 삼습니다.
- 생성된 코드가 어떻게 실패하는지 리뷰어를 대상으로 교육합니다.
- 프로토타입과 프로덕션의 경계를 명확히 합니다 (어떤 저장소, 브랜치, 환경인지).
- 하네스는 한 번 구축하고 지속적으로 개선합니다.
- 판단력을 기준으로 채용하고 승진시킵니다. 명세 작성, 평가, 아키텍처 설계 역량.
참고 자료
The New SDLC With Vibe Coding (Google)을 기반으로 작성: https://www.kaggle.com/whitepaper-the-new-SDLC-with-vibe-coding