전체 사례No. 040
Freshworks 요구사항 하나를 오케스트레이터와 전문 하위 에이전트가 PR로 만드는 Freshdesk의 개발 방식
- 사례 번호
- 040
- 1차 출처
- Freshworks Engineering Blog (Medium)
- 원문 게시
- 2026-05-28
1. 왜 이 사례인가
보통 코딩 에이전트는 엔지니어 한 명이 에이전트 하나와 대화하며 코드를 작성하는 방식으로 활용됩니다. Freshworks의 고객 지원 제품인 Freshdesk 엔지니어링 조직은 여기서 한 걸음 더 나아간 구조를 소개합니다. 요구사항을 전달받은 오케스트레이터 에이전트가 업무를 나누고, 역할이 명확히 나뉜 하위 에이전트들이 계획 수립, 코딩, 테스트, PR 작성을 나누어 맡습니다. 엔지니어는 아키텍처 설계, 코드 리뷰, 가드레일 설정, 최종 판단에 집중합니다.
Freshworks 엔지니어링 블로그에서 Ajay Ravichandran은 이를 두고 “엔지니어링 팀은 무엇을, 왜 할지 정하고, 에이전트는 어떻게 할지를 맡는다”고 요약합니다. 이 글은 프레임워크의 구조와 설계 판단을 설명하며, 실제로 이 프레임워크를 통해 프로덕션 수준의 정리(cleanup) 크론 시스템을 구축한 사례를 보여 줍니다.
이 사례를 눈여겨볼 이유는 가드레일을 저장소 안의 파일과 전담 에이전트로 구현한 방식이 구체적이기 때문입니다. 회사 규칙을 모든 에이전트가 코드를 작성하기 전에 먼저 읽는 파일로 두고, 위험한 데이터베이스 작업을 차단하는 에이전트와 부하 안전성을 강제하는 에이전트를 따로 두었습니다. 아울러 Claude가 작성한 코드를 다른 회사의 모델인 OpenAI Codex가 리뷰하도록 설계했습니다. 수백만 건의 고객 요청을 처리하는 대규모 서비스에서 자율 에이전트를 어디까지, 어떤 안전장치로 신뢰할 수 있는지 보여 주는 사례입니다.
2. Problem
해당 글은 소프트웨어 산업이 중대한 전환점에 다가가고 있다고 진단합니다. 수십 년 동안 엔지니어링 생산성을 평가하는 기준은 충분히 검증되고 리뷰된 코드를 팀이 얼마나 빠르게 배포하느냐였으며, 그 코드는 당연히 사람이 작성한다고 전제했습니다. 글은 이러한 전제가 더 이상 유효하지 않다고 말합니다.
글에서 드는 예시는 개발 현장에서 흔히 마주치는 요구사항입니다. 오래된 데이터베이스 레코드를 지우는 자동 실행 정리 크론 프레임워크를 구축하고, 작업 조율과 상태 추적에는 Redis를 활용하는 일입니다. 상세한 명세서도, 사전에 잘게 쪼개 둔 티켓도 없습니다. 기존 방식대로라면 이 요구사항은 기획 회의를 거쳐 한 스프린트 분량의 티켓으로 나뉘고, 여러 엔지니어가 몇 주 동안 맥락을 전환해가며 작업해야 하는 일입니다.
동시에 Freshdesk는 수백만 건의 고객 요청을 처리하는 서비스이므로 안전성과 신뢰성, 엔지니어링 표준 준수를 결코 포기할 수 없습니다. 글에서는 가드레일 없는 자율 에이전트는 혁신이 아니라 부담일 뿐이라고 짚습니다. 글의 예시처럼 WHERE 절이 누락된 삭제 작업은 데이터를 통째로 날려버리고, LIMIT-OFFSET 방식의 대량 삭제는 동일한 연결 풀을 공유하는 쿼리 전체를 느려지게 만듭니다. 요구사항을 에이전트에 안심하고 맡기려면 작업 속도와 더불어 이런 잠재적 위험을 원천 차단하는 장치가 필수적이었습니다.
확인된 사실: 사람이 코드를 쓴다는 전제에 대한 글의 문제 제기, 정리 크론 프레임워크 요구사항(오래된 레코드 삭제, Redis 기반 조율·상태 추적, 상세 명세·티켓 없음), 기존 방식의 기획 회의·스프린트 티켓·수 주의 맥락 전환, 수백만 건의 고객 요청을 처리하는 Freshdesk의 안전성·신뢰성 요구, 가드레일 없는 자율 에이전트는 부담이라는 판단.
3. Solution
3.1 저장소 안의 .ai/ 디렉터리
프레임워크는 대상 저장소 안에 .ai/ 디렉터리를 두고 다음 세 가지 범주의 파일을 관리합니다.
| 위치 | 역할 | 예시 파일 |
|---|---|---|
rules/ | 항상 적용되고 덮어쓸 수 없는 전사 표준 | 엔지니어링 가이드라인(코드 품질, 테스트, PR 기준), 언어별 스타일, 데이터베이스 표준(이름, 인덱스, 마이그레이션 정책), 보안 가이드라인(인증, 비밀 정보, 데이터 처리) |
skills/ | 에이전트가 필요할 때 불러 쓰는 재사용 플레이북 | 백그라운드 작업(크론 규칙, 재시도, 멱등성), 스키마 마이그레이션(안전한 패턴, 롤백 전략), 캐싱 패턴(무효화, TTL, 캐시 스탬피드 방지) |
agents/ | 역할이 하나씩 정해진 실행 단위 | 오케스트레이터(planner, delegator), 실행(worker, database, pr), 검증(safety, reliability, reviewer) |
에이전트가 생성한 코드는 모두 동일한 저장소의 src/ 경로에 저장됩니다.
3.2 오케스트레이터와 하위 에이전트
요구사항이 들어오면 곧바로 시스템의 두뇌 역할을 하는 오케스트레이터 에이전트에 전달됩니다. 오케스트레이터는 문제를 세부 단위로 나누어 실행 계획을 세운 뒤, Cursor 같은 도구 환경에서 작동하는 전문 하위 에이전트들에게 작업을 분배합니다. 하위 에이전트는 각자 단일 책임만 맡아, 회사가 정의한 엄격한 가드레일 안에서 자율적으로 작업을 수행합니다.
정리 크론 개발 사례에서 오케스트레이터는 전체 작업을 병렬 워크플로로 나누었습니다. 데이터베이스 에이전트는 스키마 마이그레이션과 삭제 쿼리를 맡고, 워커 에이전트는 Redis 기반 조율과 배치 처리 로직이 포함된 크론 작업을 맡아 비동기로 동시에 진행했습니다. 오케스트레이터는 작업 사이의 의존 관계를 계산해 꼭 필요한 지점에서만 순차적으로 실행되도록 제어했습니다. 커밋 에이전트는 하위 에이전트의 작업 단위에 맞춰 팀 규칙에 부합하는 원자적 커밋을 생성했고, 마지막에는 PR 에이전트가 작업 내용과 상세 설명이 포함된 풀 리퀘스트 하나로 묶어냈습니다.
3.3 가드레일
글에서는 프로덕션 환경에 배포 가능한 수준을 보장하는 장치들을 다음과 같이 설명합니다.
- 규칙(Rules): 모든 에이전트는 코드 작성을 시작하기 전에 반드시
.ai/rules/를 읽어야 합니다. 여기에는 데이터베이스 명명 규칙, 멀티테넌트 데이터 격리 패턴, 테스트 커버리지 기준, 보안 정책처럼 타협할 수 없는 사내 표준이 정의되어 있으며, 에이전트가 이를 임의로 수정할 수 없습니다. 글에서는 이를 두고 Freshdesk의 엔지니어링 문화를 기계가 읽을 수 있는 형태의 가드레일로 구현한 것이라고 설명합니다. - 스킬(Skills): 조직에 누적된 지식을 정리한 도메인별 실행 가이드입니다. 예를 들어 Redis 패턴 스킬은 Freshdesk 코드베이스에서 TTL 전략을 어떻게 설정하는지, 대량 작업 시 안전한 패턴이 무엇인지, 캐시 무효화 시 발생하는 몰림 현상(thundering herd)을 어떻게 방지하는지 알려 줍니다. 글에서는 이러한 스킬 덕분에 범용 AI 모델도 오랜 경험을 쌓은 Freshdesk 엔지니어처럼 작업할 수 있다고 설명합니다.
- 샌드박스 에이전트: 개발 환경의 보안 계층으로, 모든 에이전트의 동작을 실행 직전에 가로채 검사합니다. WHERE 절이 없는 파괴적 데이터베이스 작업, 프로덕션 접근 정보 열람, Redis 네임스페이스 전체 삭제(flush) 같은 명령은 실행되기 전에 차단됩니다. 디렉터리 구성 예시에서는
safety-agent로 명시되어 있습니다. - 신뢰성 에이전트: CPU, Redis, 데이터베이스 연결 풀, 하위 소비자를 급격한 부하로부터 보호하는 설계 패턴을 강제합니다. 대표적인 예가 대량 배치 삭제입니다. LIMIT-OFFSET 방식은 구현이 단순하지만, 오프셋 값이 커질수록 데이터베이스가 건너뛸 행을 찾기 위해 방대한 결과 집합을 스캔하므로 동일한 연결 풀을 공유하는 모든 쿼리의 성능을 떨어뜨립니다. 신뢰성 에이전트는 이를 방지하기 위해 커서 기반 페이지네이션을 강제합니다. 마지막으로 처리한 id 이후부터
LIMIT 1000단위로 삭제하는 방식이어서 첫 번째 배치부터 백만 번째 배치까지 일관된 성능을 유지합니다. 아울러 배치 사이에 대기 시간을 설정해, 트래픽이 몰리는 시간대에도 공유 자원을 독점하지 않고 백그라운드에서 안전하게 나누어 삭제하도록 합니다. 글은 평소 시니어 엔지니어의 숙련도에 의존하던 운영 규율이 에이전트 프레임워크에서는 기본값으로 강제된다고 설명합니다. - TDD 에이전트: 각 하위 에이전트가 테스트 코드를 먼저 작성하고, 해당 테스트를 통과하는 데 필요한 최소한의 코드만 작성하도록 유도합니다. 글은 이것이 코드의 정확성을 담보할 뿐만 아니라 컨텍스트 창을 의도적으로 관리하는 전략이라고 설명합니다. 에이전트가 자신에게 할당된 테스트 케이스와 공통 규칙만 참고하도록 제한하면 작업 맥락이 작고 명확해져 환각 현상을 줄일 수 있으며, 테스트 자체가 명세서 구실을 하게 됩니다.
- 리뷰어 에이전트의 교차 모델 리뷰: 코드는 Claude가 작성하고, 코드 리뷰는 의도적으로 다른 모델인 OpenAI Codex에 맡깁니다. 글에 따르면 모델이 자신이 생성한 결과물을 직접 평가할 경우, 자체적인 전제를 무비판적으로 수용하고 평소 자주 범하는 실수를 그대로 지나치는 경향이 있습니다. 학습 데이터와 구조적 편향이 서로 다른 별도의 모델을 배치함으로써 견제와 균형을 갖춘 리뷰 루프가 만들어지며, Codex는 Claude가 놓치기 쉬운 미세한 성능 안티패턴, 예외 처리 누락, 기존 사내 규칙과의 불일치 등을 효과적으로 잡아냅니다.
3.4 사람의 리뷰와 스테이징 검증
리뷰어 에이전트가 검토를 마치고 승인하면, PR 에이전트가 구현 내용, 핵심 설계 판단의 이유, 각 컴포넌트 간의 연계 방식을 정리해 풀 리퀘스트를 생성합니다. 인간 엔지니어는 이 시점에 개입하여 코드를 리뷰합니다. 에이전트가 작성한 코드는 실제 프로덕션에 반영되기 전에 사람이 작성한 코드와 동일하게 사전 운영(staging) 환경에서 필수 스테이징 검증 단계를 통과해야 합니다. 글은 이 최종 관문이 존재함으로써 “자율”이 결코 “검증 없음”을 뜻하지 않게 된다고 강조합니다.
확인된 사실: .ai/의 rules·skills·agents 구성과 예시 파일, Cursor 같은 도구 안에서 돌아가는 하위 에이전트, 정리 크론 예의 작업 분할(데이터베이스·워커 에이전트 병렬, 필요한 곳만 순차, 커밋 에이전트의 원자적 커밋, PR 에이전트), 규칙 선독과 그 내용, Redis 패턴 스킬, 샌드박스 에이전트가 막는 작업, 커서 기반 페이지네이션과 배치 간 대기, TDD와 컨텍스트 관리, Claude 작성·OpenAI Codex 리뷰, 사람 리뷰, 필수 스테이징 검증.
4. Impact
이 글은 도입 규모나 개발 속도, 결함률 같은 정량 지표를 제시하지 않습니다. 그 대신 프레임워크를 통해 얻은 구체적인 산출물과 업무 방식의 근본적인 변화를 중점적으로 설명합니다.
글이 제시하는 실제 결과물은 이 프레임워크를 통해 구축된 프로덕션 수준의 정리 크론 시스템입니다. 기존 방식대로라면 기획 회의와 한 스프린트 분량의 티켓, 몇 주에 걸친 맥락 전환이 불가피했을 요구사항이었습니다. 하지만 이번 사례에서는 별도의 상세 명세나 티켓 없이도 오케스트레이터에 전달되어 병렬 작업, 원자적 커밋, 상세한 설명이 포함된 PR로 완성되었습니다. 결과물에는 커서 기반 배치 삭제와 배치 간 대기 시간 설정 등 신뢰성 에이전트가 요구하는 엄격한 운영 패턴이 충실히 반영되었습니다.
글은 개발 조직의 역할 구분이 다음과 같이 재편된다고 정리합니다.
| 주체 | 새 역할 |
|---|---|
| 엔지니어 | 규칙, 스킬, 에이전트 동작을 정의하는 설계자 |
| 오케스트레이터 | 문제를 나누고 실행을 맡기는 테크 리드 |
| 하위 에이전트 | 전문 작업을 병렬로 실행하는 엔지니어링 팀 |
| 리뷰 에이전트 | 사람이 보기 전에 문제를 잡는 품질 관문 |
글은 이러한 변화가 개발자를 대체하는 흐름이 아니라, 개발자가 가치를 더하는 영역을 한 단계 끌어올리는 과정이라고 평가합니다. 앞으로 이 같은 전환을 이끌 엔지니어는 단순한 타이핑 속도가 아니라, 정교한 에이전트 시스템을 설계하는 역량, 실효성 있는 규칙을 수립하는 능력, 나아가 기계에 위임할 영역과 사람이 직접 검토해야 할 영역을 명확히 구분해 내는 판단력으로 평가받게 될 것이라고 전망합니다.
확인된 사실: 정량 지표 없음, 프로덕션 수준 정리 크론 시스템이라는 적용 예, 기존 방식과의 작업 흐름 비교, 역할 변화 네 가지, 개발자 대체가 아니라는 글의 입장.
5. Insight
가드레일은 프롬프트가 아니라 저장소의 파일과 전담 에이전트로 둡니다. Freshworks는 사내 표준을 .ai/rules/ 디렉터리에 정의해 두고 모든 에이전트가 코드 작성을 시작하기 전에 이를 필독하도록 했습니다. 규칙이 코드 저장소 내에 위치하면 소스 코드와 함께 버전 관리가 가능하고, 사람이 직접 리뷰할 수 있으며, 어떤 에이전트가 투입되든 동일한 기준이 일관되게 적용됩니다. 여기에 파괴적인 작업을 실행 전에 차단하는 샌드박스 에이전트를 별도로 배치하여, 규칙을 인지하는 단계와 규칙 위반을 물리적으로 막는 단계를 깔끔하게 분리했습니다.
시니어 엔지니어의 경험을 기본값으로 바꿉니다. 커서 기반 페이지네이션이나 배치 간 대기 시간 적용 같은 기법은 통상 시니어 엔지니어의 오랜 경험과 감각에 의존하던 부분입니다. Freshworks는 이러한 노하우를 신뢰성 에이전트와 스킬 파일에 명문화하여, 누가 어떤 요구사항을 입력하든 결과물에 해당 패턴이 기본적으로 포함되도록 강제했습니다.
테스트를 먼저 쓰게 하는 것은 컨텍스트 관리이기도 합니다. 하위 에이전트가 자신에게 주어진 테스트 케이스와 공통 규칙만 확인하도록 한정하면 참조해야 할 맥락이 좁혀지고 집중됩니다. 테스트 자체가 구체적인 명세서 역할을 대신하므로, 에이전트는 맡은 범위에 필요한 정보만 파악한 채 효율적으로 코드를 작성할 수 있습니다.
작성한 모델과 다른 모델이 리뷰합니다. 동일한 모델이 자신이 짠 코드를 직접 리뷰하면 본래 가졌던 전제와 맹점을 그대로 답습하기 마련입니다. Claude가 코드를 작성하고 Codex가 이를 리뷰하는 이원화 구조는 모델 간의 차이를 검증 필터로 활용하는 영리한 접근입니다. 그럼에도 최종 승인은 반드시 사람 엔지니어가 내리며, 사람이 짠 코드와 동일한 스테이징 검증을 통과해야만 배포됩니다.
복제 조건과 한계. 이 방식은 사내 엔지니어링 표준이 명문화된 규칙 파일로 정리될 수 있을 만큼 명료하고, 도메인 지식을 스킬 파일로 체계화할 시니어 엔지니어가 확보된 조직에서 온전한 효과를 발휘합니다. 아울러 규칙, 스킬, 에이전트 정의를 지속해서 유지 보수하는 일 역시 엔지니어에게 주어지는 새로운 업무가 됩니다. 또한 해당 글은 프레임워크의 아키텍처와 단일 적용 사례를 다루고 있을 뿐 정량적인 성과 수치는 제공하지 않으므로, 작업 속도나 품질 향상의 폭을 이 자료만으로 단정하기는 어렵습니다.
한 줄 요약: 자율 코딩 에이전트를 프로덕션에 쓰려면 회사 규칙을 저장소 파일로 옮기고, 위험 작업 차단·부하 안전성·교차 모델 리뷰를 각각 전담 에이전트에 맡긴 뒤, 마지막 판단과 스테이징 검증은 사람이 쓴 코드와 똑같이 거치게 해야 합니다.
6. 원문에 없는 추정 (구현 가설)
6.1 오케스트레이터가 만드는 작업 계획과 의존 관계
근거: 글은 오케스트레이터가 문제를 나누고 실행 계획을 세워 하위 에이전트에게 맡기며, 정리 크론 예에서 데이터베이스 에이전트와 워커 에이전트를 비동기로 병렬 실행하고 의존 관계를 파악해 꼭 필요한 곳에서만 순서를 지켰다고 설명합니다. 오케스트레이터는 planner와 delegator로 나뉘어 있습니다.
planner는 요구사항을 하위 작업 목록으로 변환하면서 작업별 담당 에이전트, 입출력 정의, 선행 작업이 기술된 계획 파일을 생성했을 가능성이 높습니다. 정리 크론 시스템을 예로 들면 “삭제 대상 조건과 인덱스를 정하는 마이그레이션”이 “배치 삭제 쿼리”보다 먼저 구현되어야 하며, 크론 작업의 Redis 조율 로직은 쿼리 인터페이스 규격만 확정되면 병렬로 제작할 수 있습니다. delegator는 이 계획서에서 선행 조건이 충족된 작업만 추려 하위 에이전트에 전달했을 것으로 보입니다. 여러 하위 에이전트가 동일한 파일을 동시에 수정하여 충돌을 일으키지 않도록 작업별로 수정 가능한 파일 경로를 계획 단계에서 명시했을 가능성도 큽니다. 커밋 에이전트가 각 하위 에이전트의 작업 단위에 맞추어 원자적 커밋을 남겼다는 점을 감안하면, 커밋의 단위 역시 이러한 세부 작업 단위와 일대일로 대응되도록 설계되었을 것으로 추정됩니다.
6.2 샌드박스 에이전트의 사전 차단 방식
근거: 글은 샌드박스 에이전트가 개발 환경의 보안 계층으로서 모든 에이전트 동작을 실행 전에 가로채며, WHERE 절 없는 파괴적 데이터베이스 작업, 프로덕션 자격 증명 접근, Redis 네임스페이스 flush를 막는다고 설명합니다. 하위 에이전트는 Cursor 같은 도구 안에서 돌아갑니다.
“실행 전에 가로챈다”는 표현으로 미루어 볼 때, 샌드박스 에이전트는 에이전트가 셸 명령어 실행이나 데이터베이스 쿼리 호출을 시도하는 시점에 개입하는 프리 프로세싱 훅(pre-execution hook) 형태로 연동되어 있었을 가능성이 큽니다. 검증은 2단계로 진행되었을 것으로 보입니다. 1단계로 SQL 구문 파싱이나 명령어 정규식 검사를 통해 WHERE 절 없는 DELETE·UPDATE, DROP 문, Redis의 FLUSHDB·FLUSHALL, 프로덕션 접속 정보가 담긴 환경 변수 및 설정 파일 접근 같은 명백한 위험 동작을 즉각 차단하고, 2단계로 모호하거나 맥락 파악이 필요한 동작에 한해 모델이 사내 규칙 파일과 대조해 허용 여부를 판단하는 구조입니다. 차단된 명령은 그 사유와 함께 담당 하위 에이전트에 반환되어 대안을 찾도록 재시도를 유도하고, 동일한 위반이 거듭되면 오케스트레이터가 작업을 중단하고 사람에게 알림을 보냈을 것으로 추정됩니다. 아울러 개발 환경 자체에 애초부터 프로덕션 자격 증명을 배치하지 않는 격리 정책이 병행되었을 가능성도 큽니다.
6.3 교차 모델 리뷰의 입력과 반려 처리
근거: 글은 리뷰어 에이전트가 규칙에 비춰 결과물을 감사하고, Claude가 쓴 코드를 OpenAI Codex가 리뷰하며, 리뷰어가 승인한 뒤에야 PR 에이전트가 PR을 올린다고 설명합니다. 리뷰 항목으로는 성능 안티패턴, 오류 처리의 예외 상황, 기존 규칙과의 불일치를 듭니다.
Codex 모델에는 작성 에이전트가 주고받은 전체 대화 내역 대신, 최종 변경 diff와 .ai/rules/의 내용, 해당 작업에 참조된 스킬 파일, 그리고 오케스트레이터가 정의한 작업 목표 설명서만 전달되었을 가능성이 큽니다. 코드 작성 과정의 프롬프트와 부가 설명을 함께 제공하면 리뷰어가 작성자 모델의 편향이나 전제를 그대로 답습할 우려가 있어 모델을 분리한 실익이 반감되기 때문입니다. 코드 리뷰 결과는 “규칙 위반”, “성능 위험”, “오류 처리 누락” 같은 구조화된 항목별 피드백 형태로 반환되었을 것이며, 지적 사항이 발생하면 담당 하위 에이전트가 코드를 수정한 후 테스트와 리뷰 절차를 재수행했을 것입니다. 무한 수정 및 재리뷰 루프에 빠지는 것을 방지하기 위해 재시도 횟수 제한을 두고, 임계치를 초과할 경우 잔여 지적 사항을 PR 설명란에 기록하여 최종 인간 리뷰어가 판단하도록 위임했을 것으로 추정됩니다.
7. 출처
- Freshworks Engineering (Medium) — Pivoting to Autonomous Agentic Development
https://medium.com/freshworks-engineering-blog/pivoting-to-autonomous-agentic-development-ad9ba8408fe3
발행일: 2026-05-28 (Ajay Ravichandran)