AI 코딩 에이전트를 팀에 도입하면 코드 생성량은 늘지만, 저장소가 규칙을 알려주고 결과를 검사하지 않으면 리뷰 부담과 품질 편차도 함께 커질 수 있습니다. 30명 이상 팀을 운영하는 Sarah Fim은 에이전트의 모델이나 하니스보다 저장소를 어떻게 설계하고 CI에서 무엇을 강제하는지가 중요하다는 경험을 공유했습니다.
그의 글은 여덟 가지 실천을 제안합니다. 코드를 가까이 두고, 타입으로 계약을 표현하고, 작은 중복은 허용하며, 규칙을 lint로 고정하고, 실제 흐름을 테스트합니다. 결정론적 검사가 놓치는 복잡한 문제에는 bugbot을 보조적으로 쓰고, CI 피드백을 빠르게 만든 뒤, 클라우드 에이전트에 업무 맥락을 연결합니다. Sarah의 X Article 원문과 소개 영상 게시물을 함께 참고하세요.
출처: X sarahfim
1. Co-location: 관련 코드를 가까이 둔다
기능을 바꾸려면 구현, 스타일, 테스트와 보조 코드를 한 경계 안에서 찾을 수 있어야 합니다. Next.js App Router에서는 라우트 폴더 안에 컴포넌트·스타일·테스트를 함께 둘 수 있으며, `page`나 `route` 파일만 경로로 공개됩니다. 이렇게 두면 에이전트가 기능에 필요한 맥락을 따라가기 쉽고, 전역 공용 폴더를 무심코 수정할 가능성도 줄어듭니다.
폴더가 URL 경로가 되는 구조와 정리 목적의 route group은 구분하세요. Next.js 문서
2. Type safety: 경계에서 타입을 강제한다
타입은 함수와 컴포넌트가 기대하는 입력·출력을 코드에 드러내고, 에이전트가 계약을 어긴 변경을 만들었을 때 편집기와 빌드가 일찍 알려줍니다. React의 TypeScript 지원을 활용하고, TypeScript 서비스에서는 tRPC처럼 서버 라우터 타입을 클라이언트에서 추론할 수 있습니다. 외부 API는 OpenAPI 스키마를 계약으로 삼아 타입을 생성하는 방법도 있습니다.
타입은 런타임 입력 검증을 대신하지 않습니다. 신뢰할 수 없는 요청 데이터는 별도 검증을 거치게 하세요. React TypeScript 안내 · tRPC · OpenAPI TypeScript
3. Duplication is OK: 작은 중복은 허용한다
서로 다른 기능에서 비슷한 코드가 보인다는 이유만으로 곧바로 공통 추상화로 옮기면, 각 기능의 변화가 하나의 모듈에 얽힐 수 있습니다. 맥락이 다른 코드는 당분간 반복되게 두는 편이 읽고 수정하기 쉬울 수 있습니다.
다만 인증·권한, 금액·날짜처럼 여러 기능이 공유하는 전역 primitive는 예외로 살펴야 합니다. 여러 구현이 서로 다른 불변식을 갖게 되면 보안이나 데이터 일관성 문제가 생길 수 있으므로, 소유권과 계약을 명확히 하고 중복 여부를 판단하세요. 이 구분은 Sarah가 제시한 설계 기준입니다.
4. Lint rules: 팀 규칙을 실행 가능한 검사로 만든다
에이전트에게 규칙을 문장으로 알려주는 것만으로는 매번 같은 결과를 기대하기 어렵습니다. 예를 들어 사용하지 않는 변수, 금지된 API 호출, 팀이 정한 코드 패턴을 lint 규칙으로 만들고 로컬과 CI에서 똑같이 실행하세요. 규칙에는 금지 패턴뿐 아니라 정당한 예외도 담아야 합니다.
Sarah가 공유한 경험에는 `lib/utils` 같은 범용 폴더를 만들지 못하게 하는 규칙, `useState`와 `useEffect` 사용을 제한하는 규칙 등이 포함됩니다. 이런 금지는 모든 React 프로젝트의 보편 규칙이 아니라, 해당 팀의 구조와 선택을 에이전트가 임의로 흔들지 않게 하는 저장소별 정책입니다. 규칙을 실제 ESLint로 구현하면 설명 파일이나 프롬프트를 반복해서 갱신하는 것보다 일관되게 적용할 수 있습니다. typescript-eslint 사용자 정의 규칙
5. End-to-end tests: 사용자 흐름을 실제로 검증한다
단위 테스트가 각 함수의 동작을 확인한다면, E2E 테스트는 사용자가 화면과 서비스를 통과하는 흐름이 유지되는지 확인합니다. 에이전트가 만든 변경과 함께 중요한 사용자 경로를 검사하면, 컴파일은 성공했지만 실제 화면에서 깨지는 문제를 발견할 수 있습니다.
Meticulous는 실제 브라우저 상호작용을 기록하고 변경 전후 UI를 재생·비교하는 접근을 제공합니다. MCPJam은 MCP 서버의 도구 동작과 여러 호스트 환경의 호환성을 테스트하고 CI 평가 게이트에 연결하는 데 초점을 둡니다. 두 도구는 각기 다른 테스트 영역을 지원하므로 제품 흐름에 맞춰 선택하세요. Meticulous 문서 · MCPJam CI/CD 평가 게이트 · 교차 클라이언트 테스트
6. Bugbots: 복잡한 버그를 찾는 보조 검토로 쓴다
포맷, 타입, lint와 재현 가능한 테스트는 먼저 결정론적 검사로 잡는 편이 좋습니다. bugbot은 그런 규칙을 대체하는 게 아니라, 코드 경로와 변경 맥락을 함께 읽어야 보이는 복잡한 버그를 추가로 찾아보는 역할을 합니다.
Cursor Bugbot은 PR 변경을 분석해 잠재적 버그·보안 문제를 제안하고 저장소 규칙을 담은 `BUGBOT.md`로 맥락을 제공할 수 있습니다. AI 검토에는 오탐과 누락이 있으므로 결과를 검토 대상으로 남기고 CI의 통과 조건이나 사람의 책임을 넘기지 마세요. Cursor Bugbot 문서
7. Fast CI: 피드백을 빠르게 돌려준다
CI가 느리면 개발자와 에이전트 모두 실패 원인을 늦게 받고, 수정과 재검사의 반복도 길어집니다. 먼저 job별 대기·실행 시간과 캐시 적중률을 측정한 뒤, 병렬화·캐시·적절한 runner로 병목을 줄이세요.
Sarah는 Blacksmith를 쓰며 CI 시간이 50% 줄고 비용은 70% 이상 감소했다고 소개했습니다. 이는 그의 팀에서 보고한 결과입니다. Blacksmith도 자사 비교에서 CPU 작업이 GitHub-hosted runner보다 40–60% 빠르고 분당 비용이 절반이라 전체 지출을 약 70% 줄일 수 있다고 설명합니다. workload와 가격 조건에 따라 달라지는 Sarah 및 공급자 측 수치이므로 모든 저장소의 결과로 일반화하지 마세요. Blacksmith 비용 절감 설명
8. Cloud agents: 필요한 업무 맥락을 연결한다
클라우드 에이전트가 이슈, PR, 제품·업무 도구의 정보를 읽을 수 있으면 저장소 밖 맥락까지 반영한 작업을 맡길 수 있습니다. Composio는 세션에 사용자 식별자, 사용 가능한 도구와 연결된 인증 정보를 묶어 에이전트가 필요한 연동 도구를 찾고 실행하도록 지원합니다. 접근 범위는 사용자와 작업에 필요한 수준으로 제한하고, 결과는 PR과 CI를 거쳐 검토할 수 있게 하세요.
Sarah는 Composio의 대시보드 맥락 접근을 활용한 내부 에이전트 Zen이 2월 이후 1,300건이 넘는 PR을 만들었고 9월에 245건을 처리했다고 소개했습니다. 이 숫자는 Sarah가 공유한 팀 사례입니다. Composio 세션 개념 · Composio 에이전트 설정
에이전트가 따를 수 있는 저장소를 만든다
여덟 항목은 특정 프롬프트나 에이전트 하니스 하나를 고르는 처방이 아닙니다. 구현과 테스트를 가까이 두고, 타입·lint·E2E로 저장소 규칙을 실행하며, 빠른 CI와 필요한 업무 맥락을 갖추는 운영 방식입니다. 어떤 항목부터 적용할지는 팀의 현재 실패와 병목을 기준으로 정하고, 규칙은 에이전트가 실제로 수정하는 코드와 같은 저장소에서 관리하세요.
함께 읽기: jevgrep으로 AI 코딩 에이전트에 필요한 코드만 찾기 · OpenAI Codex 하네스와 사내 도구 통합 · Unreal Labs의 에이전트 운영 사례
