코딩 에이전트 도입을 고민하는 팀들이 공통적으로 빠지는 함정이 있다. 도구를 설치하는 것 자체가 목표가 되는 순간이다. GitHub Copilot을 켜고, Claude Code를 붙이고, 에이전트 모드를 활성화한다. 그런데 막상 쓰다 보면 처음 며칠이 지나면서 자꾸 수동으로 돌아가게 된다. 왜냐하면 에이전트가 내 코드베이스를 모르기 때문이다. 최근 dev.to에서 공개된 세 편의 실전 사례는 이 문제를 정면으로 다룬다. 그리고 세 사례가 공통적으로 가리키는 답은 동일하다. 에이전트에게 맥락을 먼저 설계해줘야 한다.
에이전트가 처음부터 '제대로' 쓴 이유
첫 번째 사례는 풀스택 SaaS 폼 빌더인 Dculus Forms에 GitHub Copilot을 적용한 경험이다. 개발자는 기능 개발에 앞서 .github/instructions/ 디렉토리에 8개의 instruction 파일을 먼저 작성했다. 인증, 백엔드 레이어링, 데이터베이스 컨벤션, 프론트엔드 import 규칙, GraphQL 스키마 패턴, i18n, 공유 패키지 사용법, 테스트 패턴까지—각 파일은 applyTo 프론트매터로 해당 디렉토리에만 자동 적용된다.
효과는 즉각적이었다. Copilot에게 "GraphQL 쿼리 추가해줘"라고 요청했을 때, instruction 파일 없이는 import 경로를 고치고 auth guard를 빠뜨린 코드를 반복 수정해야 했다. 하지만 instruction 파일을 갖추고 나니 첫 번째 드래프트부터 팀 컨벤션을 정확히 따른 코드가 나왔다. 타밀어 번역까지 자동으로 포함해서. 이걸 두고 저자는 "스프린트 전체에서 레버리지가 가장 높았던 작업"이라고 평가했다. 기능 코드를 한 줄 쓰기 전에 에이전트에게 팀 문화를 가르치는 데 먼저 시간을 쓴 것이다.
더 나아가 멀티파일 피처 작업에는 feature-developer, field-type-developer라는 커스텀 에이전트를 별도로 정의했다. AI Field Insights 기능처럼 Prisma 스키마, 백엔드 서비스, GraphQL 리졸버 2개, 프론트엔드 컴포넌트 5개, 번역 파일까지 동시에 건드리는 작업에 feature-developer 에이전트와 상세 스펙을 함께 던졌더니, Copilot이 파일 맵과 단계별 태스크—각 태스크마다 실패 테스트 먼저—를 포함한 완전한 플랜을 생성했다. 저자의 표현을 빌리자면 "하루 치 컨텍스트 스위칭이 집중된 오후 한 나절로 줄었다."
40%에서 98%로: 에이전트가 막힌 곳을 뚫는 방식
두 번째 사례는 코파운더 매칭 플랫폼 FoundrGeeks다. 수개월째 GitHub에 방치되어 있던 40% 완성 프로젝트를 GitHub Copilot 도움으로 98%까지 끌어올린 경험이다. 기술적으로 가장 도전적인 부분은 NVIDIA Text Embeddings와 LangChain을 활용한 코사인 유사도 벡터 검색 기반 AI 매칭 엔진이었다. 저자는 Copilot이 아키텍처를 이해하도록 돕고, 적합한 LangChain 패턴을 제안하고, 혼자였다면 며칠이 걸렸을 엣지 케이스를 디버깅하는 데 결정적 역할을 했다고 평가한다.
이 사례에서 주목할 점은 따로 있다. 데이터베이스 시딩 스크립트처럼 "해야 하는데 계속 미루게 되는 tedious한 작업"을 Copilot이 처리해줬다는 것이다. 보일러플레이트를 빠르게 생성해주니 심리적 저항이 사라졌다. 실무에서 에이전트의 역할이 단순한 속도 향상을 넘어, 팀이 반복적으로 회피하던 작업들을 실제로 완료 가능한 상태로 만들어주는 데 있다는 걸 이 사례는 잘 보여준다.
에이전트를 직접 만들어보면 보이는 것
세 번째 사례는 한 단계 더 깊이 들어간다. TypeScript로 미니 Claude Code를 직접 구현한 경험이다. Vercel AI SDK와 Google Gemini 2.5 Flash를 기반으로, 파일 읽기·쓰기·편집, bash 명령 실행, git 조작, 웹 검색까지 수행하는 CLI 에이전트를 밑바닥부터 만들었다.
이 구현 과정에서 드러난 기술적 쟁점 두 가지가 특히 중요하다. 첫 번째는 Human-in-the-Loop 설계다. 파일 읽기나 명령 실행은 자동 실행해도 되지만, 파일 편집은 다르다. 에이전트가 잘못된 편집을 적용하면 되돌리기 어렵다. 이 개발자는 edit_file 도구에 isApproved 플래그를 스키마로 정의하고, Vercel AI SDK의 stopWhen 파라미터로 에이전트 루프 자체를 일시정지시킨 뒤, 사용자가 diff를 확인하고 승인하면 루프를 재개하는 구조를 설계했다. 도구와 루프 제어가 명확한 핸드셰이크를 이루는 방식이다.
두 번째는 플래너 서브에이전트다. "인증 백엔드 추가해줘" 같은 큰 태스크가 들어오면 단일 루프로는 처리가 불안정해진다. 이 문제를 플래너 서브에이전트로 분리해 태스크를 ID·설명·상태·우선순위가 있는 구조화된 할일 목록으로 분해하고, 메인 에이전트가 하나씩 순서대로 집어 실행하는 방식으로 해결했다. 모든 스키마는 Zod로 엄격하게 타입을 지정해 도구 입출력을 명확히 계약했다.
다음 단계로는 병렬 서브에이전트를 계획하고 있다. 여러 에이전트가 동시에 서로 다른 태스크를 실행할 때 파일 충돌을 막기 위해, 플래너 단계에서 각 태스크가 어떤 파일을 건드리는지를 메타데이터로 할당해두고, 동일 파일을 두 에이전트가 접근하지 않도록 구조적으로 예방하는 설계다. 실행 중 충돌 해결이 아니라 계획 단계에서 충돌을 원천 차단하는 방식이다.
세 사례가 팀 리드에게 전하는 메시지
세 사례를 관통하는 패턴은 하나다. 에이전트가 잘 작동한 팀은 에이전트에게 작동할 수 있는 구조를 먼저 만들어줬다. instruction 파일이든, 커스텀 에이전트 정의든, Human-in-the-Loop 승인 흐름이든, 플래너 서브에이전트든—모두 에이전트가 자율적으로 움직이기 전에 팀이 설계해놓은 경계와 계약이다.
반대로 보면, 이 구조가 없으면 에이전트는 그냥 똑똑한 자동완성에 머문다. 매번 컨벤션을 수정하고, 엣지 케이스에서 멈추고, 큰 태스크에서 맥락을 잃는다. 에이전트 도입 초기에 팀이 느끼는 실망의 대부분은 도구의 한계가 아니라 구조 설계를 건너뛴 결과다.
내일 당장 팀에 적용할 수 있는 것
세 사례에서 뽑을 수 있는 즉시 실행 가능한 액션은 명확하다. 첫째, 코딩 에이전트를 도입하기 전에 .github/instructions/ 또는 동등한 컨텍스트 파일부터 작성하라. 팀 컨벤션, 레이어링 규칙, 금지된 패턴을 에이전트가 읽을 수 있는 형태로 먼저 문서화하는 것이다. 이게 가장 ROI가 높은 작업이다.
둘째, 에이전트가 건드리는 작업의 위험도를 분류하라. 읽기·검색은 자동 실행, 편집·삭제는 Human-in-the-Loop—이 구분이 없으면 에이전트 신뢰도가 사건 한 번으로 무너진다. 셋째, 큰 피처 작업에는 플래너를 먼저 실행하라. "이 기능 구현해줘"가 아니라 "이 기능의 태스크 목록을 먼저 만들어줘"로 시작하면, 에이전트가 실행하는 동안 팀이 계획 단계에서 개입하고 수정할 여지가 생긴다.
에이전트는 팀의 실행 속도를 올려주는 도구가 맞다. 하지만 그 속도는 무조건 켜는다고 나오지 않는다. 팀이 에이전트에게 맥락을 주고, 경계를 설계하고, 위험한 작업에 승인 흐름을 넣은 만큼만 나온다. 지금 당신의 팀이 에이전트를 켜놓고도 자꾸 수동으로 돌아가고 있다면, 도구를 바꿀 게 아니라 구조를 먼저 점검할 때다.