안녕하세요 — 저는 ConnectiveOne (AI 기반 커뮤니케이션 플랫폼)을 운영하고 있으며, 키이우(Kyiv)에 기반을 둔 개발 숍인 Evergreen의 공동 창립자인 Sergii입니다. 저는 우리가 어떻게 AI 에이전트(AI agents)를 중심으로 SDLC(소프트웨어 개발 생명 주기, Software Development Life Cycle)를 재구축했는지 실제 기술적 세부 사항을 통해 설명하고자 합니다. 단순히 "Copilot을 추가했다"는 식의 이야기가 아니라, 1년 이상의 시간이 걸렸고, 시행착오를 겪었으며, 결국 다른 엔지니어들이 실제로 가져다 쓸 만한 유용한 설정(setup)을 완성하게 된 과정에 대한 이야기입니다.

요약(TL;DR): 코딩 어시스턴트(coding assistant)에게 무제한의 범위를 주고 단순히 채팅만 하는 방식은 특정 지점을 넘어서면 확장성(scale)을 갖지 못합니다. 에이전트에게 좁은 역할(narrow role), 경계에 대한 서면 명세(written spec), 그리고 사람이 Diff(변경 사항)를 확인하기 전의 품질 게이트(quality gate)를 부여하는 방식은 확장 가능합니다. 이 포스트는 우리가 실제로 사용하는 구조를 담은 "방법론"에 관한 것입니다.

구체적인 문제점

Claude Code나 Cursor를 몇 주 이상 사용해 보셨다면 아마 이런 상황을 겪었을 것입니다: git clone을 하고, 에이전트에게 질문을 시작합니다 — "왜 에러가 나나요", "이 부분을 리팩터링(refactor)해 줄 수 있나요", "이걸 어떻게 연결하나요" — 처음 몇 번의 세션은 마법 같습니다. 하지만 곧 컨텍스트(context)가 누출되기 시작합니다. 매 세션마다 아키텍처(architecture)를 새로 도출합니다. 3일 전에 말해준 컨벤션(convention)을 기억하지 못합니다. 토큰(Token) 비용은 치솟습니다. 그리고 출력 품질은 코드베이스(codebase)나 프로세스의 특성이 아니라, 그날 아침 당신이 프롬프트(prompt)를 얼마나 잘 작성했느냐에 따라 결정됩니다.

이것은 모델(model)의 문제가 아닙니다. 아키텍처(architecture)의 문제입니다 — 당신은 시스템(system)이 아니라 채팅(chat)을 실행하고 있는 것입니다.

대신 우리가 구축한 것: 직무 기술서를 가진 에이전트

실제로 중요했던 사고 모델(mental model)의 전환은 다음과 같습니다: 에이전트를 협상해야 하는 챗봇(chatbot)으로 취급하는 것을 멈추고, 온보딩(onboarding)해야 하는 신입 사원으로 취급하기 시작하는 것입니다. 신입 사원에게 "여기 전체 코드베이스가 있으니 마음대로 해보세요"라고 하지 않습니다. 그들에게는 역할(role), 범위(scope), 읽어야 할 문서 세트, 그리고 건드릴 수 있는 범위에 대한 경계(boundaries)가 주어집니다.

우리는 이를 저장소(repo) 내에 존재하며 다른 모든 요소와 마찬가지로 버전 관리(versioned)되는 규칙 레이어(rules layer)로 공식화합니다. 만약 Cursor를 사용 중이라면 이는 말 그대로 .cursor/rules 및 .cursor/agents입니다. Claude Code나 다른 도구를 사용 중이라면 메커니즘은 다르겠지만 원칙은 동일합니다. 즉, 에이전트가 읽을 수 있는 어딘가에 관례(convention)가 기록되어 있지 않다면, 에이전트 입장에서는 그것이 존재하지 않는 것과 같습니다. 모델이 코드만 보고 팀의 패턴을 "그냥 알 것"이라고 기대하지 마세요.

우리의 역할(role) 파일 중 하나가 어떻게 생겼는지 간소화한 버전입니다:

role: backend-development-agent
scope:
  - services/orders/**
...

특별한 것은 없습니다. 가치는 단 한 줄의 코드에 있는 것이 아닙니다. 이 문서가 존재한다는 것, 버전 관리 시스템(version control)에 체크인되어 있다는 것, 그리고 긴 채팅 세션의 끝까지 살아남은 맥락(context)에 의존하는 대신 에이전트가 실제로 작동하는 계약(contract) 역할을 한다는 점에 가치가 있습니다.

실전에서의 세 가지 기둥

1. 신뢰할 수 있는 단일 원천(Source of Truth)으로서의 규칙. 위에서 이미 다루었듯이, 핵심은 이것이 시니어 개발자의 머릿속에 있는 암묵적 지식(tribal knowledge)이 아니라 버전 관리되는 산출물(artifact)이라는 점입니다.

2. 범용(general-purpose) 에이전트가 아닌 역할 기반(role-based) 에이전트. 우리는 백엔드, UI/UX, QA, 아키텍처 리뷰, 문서화를 위해 각각 별도의 에이전트를 운영하며, 각 에이전트는 위와 같은 고유의 범위(scope) 파일을 가집니다. 이는 관리 오버헤드처럼 들릴 수 있지만, 대안과 비교해 보면 다릅니다. 모든 것을 건드리는 하나의 어시스턴트는 창의적 자율성을 많이 줄수록 품질이 저하됩니다. LLM은 "무엇이든 도와줘"라는 요청보다 명확한 직무 기술서(job description)가 있을 때 더 잘 작동합니다. 이는 계약업체가 "집을 더 멋지게 만들어줘"라는 말보다 작업 범위(scope of work)를 전달받았을 때 더 일을 잘하는 것과 같습니다.

3. AI는 소프트웨어 개발 생명주기(SDLC)를 대체하는 것이 아니라 변형시킵니다. 우리의 실제 파이프라인은 다음과 같습니다: 요구사항(requirements) → 설계(design) → 개발(dev) → 테스트(test) → 배포(deploy). 각 단계마다 에이전트(또는 에이전트 쌍)가 배치되며, 단계 사이에는 복사해서 붙여넣은 Slack 메시지가 아닌 마크다운 명세서(markdown spec)와 같은 명시적인 인수인계 산출물(handoff artifact)이 존재합니다.

만약 팀 내에서 좋은 프롬프트(prompt)를 공유하는 방식이 "개발 채널에 붙여넣었어요"라면, 그것은 시스템이 아니라 구전(folklore)에 불과하며, 프롬프트를 작성한 사람이 휴가를 떠나는 순간 유지되지 않습니다.

실제로 효과가 있었던 배포 순서 (그리고 효과가 없었던 순서)

우리는 초기에 "코드베이스 전체에서 병렬로 실행되는 다중 에이전트(multiple agents)"로 바로 넘어가려고 시도했습니다. 결과는 예상했던 대로였습니다. 출력은 빠르고 자신감 있게 들렸지만, 사후에 잡아내기에는 비용이 많이 드는 방식으로 미묘하게 틀린 부분이 상당 부분 존재했습니다.

대신 효과가 있었던 방식 — 그리고 오늘 이 작업을 시작하는 모든 팀에게 제가 해주고 싶은 말은 다음과 같습니다:

• 하나의 좁고 지루한 프로세스를 선택하세요. PR 리뷰(PR review), 문서 생성(doc generation), 또는 특정 QA 패스(QA pass) 하나를 고르세요. "전체 소프트웨어 개발 생명주기(SDLC)"가 아닙니다. 딱 한 가지여야 합니다.
• 이를 위해 하나의 역할 범위가 지정된 에이전트(role-scoped agent)를 구축하세요. 다른 것에 적용하기 전에 장난스러운 예시(toy examples)가 아닌 실제 티켓(real tickets)을 통해 검증하세요.
• 역할을 하나씩 추가하세요. 각 새로운 에이전트는 자신만의 스코프 파일(scope file)을 가지며, 실제 업무를 통해 입증된 후에 영구적으로 자리 잡게 됩니다.
• 게이트(gates)가 안정된 후에만 병렬성(parallelism)을 추가하세요. 여러 에이전트가 동시에 실행되며 서로에게 컨텍스트(context)를 전달하는 방식 — 우리가 내부적으로 에이전트 스웜(agent swarm)이라고 부르는 것 — 은 이미 안정적인 규칙과 머지(merge) 전의 자동화된 품질 게이트(automated quality gate)를 갖춘 상태에서만 의미가 있습니다. 이 단계를 건너뛰는 것이 제가 팀들이 저지르는 가장 흔한 실수 중 하나로 보는 부분입니다.

인간이 실제로 위치하는 지점

이 부분은 사람들이 불안해하는 지점이므로, 모호하게 말하는 대신 구체적으로 말씀드리겠습니다.

저희는 1차 필터(first-pass filter)로서 자동화된 리뷰(저희의 경우 CodeRabbit)를 실행합니다. 스타일, 명백한 문제, 컨벤션 위반, 기본적인 보안 취약점(security smells) 등을 잡아내는 용도입니다. 그게 전부입니다. 그것이 잡아내는 범위는 딱 거기까지입니다. 이것은 의도 이탈(intent drift)을 잡아내지 못합니다. 즉, 에이전트가 생성한 코드가 깔끔하고, 테스트를 통과하며, 린트(lint)도 잘 통과하지만, 긴 세션 동안 컨텍스트(context)가 어긋났거나 상위 에이전트가 오래된 명세(spec)를 전달했기 때문에 실제 요청된 것과는 미묘하게 다른 문제를 해결하는 경우를 잡아내지 못한다는 뜻입니다. 이러한 종류의 실패는 예외 없이 매번 인간이 필요합니다. 아키텍처 결정과 비즈니스 로직의 정확성은 인간의 영역으로 남습니다. 최종 머지 승인(Final merge sign-off) 역시 인간의 몫입니다.

변화하는 것은 루프 안에 인간이 있느냐 없느냐가 아니라, 인간이 실제로 무엇을 리뷰하느냐 하는 점입니다. "이 코드 한 줄이 맞게 보이는가"라는 질문보다는 "이 디프(diff)가 의도와 일치하는가, 그리고 에이전트가 지정된 범위(scope file) 내에서 작업했는가"를 확인하는 비중이 커집니다. 이는 전통적인 코드 리뷰와는 다른 기술이며, 이것이 자동으로 전이될 것이라고 가정하기보다는 팀원들에게 명시적으로 교육할 가치가 있습니다.

아무도 말해주지 않는 도구의 격차: 출처(provenance)

이것은 저희를 가장 힘들게 했던 문제이자, 사람들이 잘 쓰지 않는 내용입니다. 에이전트가 생성한 변경 사항이 3주 후에 문제를 일으켰을 때, "왜 이렇게 했는가"라는 질문은 PR을 리뷰한 엔지니어에게 단순히 물어본다고 해결될 문제가 아닙니다. 왜냐하면 그들은 결정 과정(decision process)이 아니라 디프(diff)를 리뷰했기 때문입니다. 그리고 오래된 컨텍스트를 가지고 동일한 에이전트를 다시 실행하여 일관된 설명을 기대하는 것은 신뢰할 수 있는 디버깅 방법이 아닙니다.

우리는 이 문제를 해결하기 위해 특별히 내부 오케스트레이션 레이어 (orchestration layer, 우리가 C1Cursor라고 부르는 것)를 구축하게 되었습니다. 에이전트가 생성한 모든 차이점(diff)은 실행 시점에 다음과 같은 정보가 태그로 지정됩니다: 어떤 에이전트인지, 어떤 역할/범위(role/scope)인지, 실제로 어떤 컨텍스트(어떤 문서, 어떤 코드, 어떤 상위 에이전트의 출력물)에 접근할 수 있었는지, 그리고 어떤 게이트(gate)를 통과하거나 실패했는지에 대한 정보입니다. 이를 통해 "왜 이런 일이 발생했는가"라는 질문은 고고학적 발굴 작업이 아닌, 단순한 조회(lookup) 작업으로 변합니다. 만약 여러분이 직접 이를 도입하려 하는데 커스텀 도구를 만들 예산이 없다면, 최소한 이 메타데이터(metadata)를 쿼리 가능한 어딘가에 기록하십시오. 구조화된 커밋 메시지(commit message) 컨벤션이라도 있는 것이 아무것도 없는 것보다 훨씬 낫습니다.

수치, 그리고 제가 이를 먼저 내세우지 않는 이유

이 모든 과정을 통해 ConnectiveOne은 이전의 자체 기준(baseline) 대비 전년 대비 약 +300%의 개발 속도(development velocity) 향상을 달성했습니다. 사람들이 물어보기 때문에 언급하는 것이지, 기술적인 대화를 이 수치로 시작하지는 않을 것입니다. 왜냐하면 앞서 언급한 게이트(gating)와 출처(provenance) 레이어 없는 속도는 팀이 빠르게 배포만 하고 디버깅은 눈을 가린 채 하게 만드는 정확한 지름길이기 때문입니다. 이것이 지속 가능하다는 것을 실제로 알려준 지표는 속도가 아니었습니다. 그것은 더 많은 에이전트와 더 많은 병렬성(parallelism)을 추가함에도 불구하고 우리의 품질 게이트(quality-gate) 통과율이 일정하게 유지되었다는 점이었습니다. 속도는 그것이 제대로 유지됨에 따라 따라오는 결과물이지, 자랑하기 위한 별개의 성과가 아니었습니다.

만약 여러분이 다음 주에 이를 시작한다면

모델을 고르는 것부터 시작하지 마십시오. 그것은 잘못된 첫 번째 결정입니다. 에이전트가 실제로 읽을 수 있는 파일에, 하나의 좁은 프로세스가 무엇을 건드릴 수 있고 무엇을 건드릴 수 없는지를 적는 것부터 시작하십시오. 그 한 가지가 실제 티켓(ticket)에서 작동한다는 것을 증명하십시오. 그런 다음 다음 역할을 추가하십시오. 게이트가 지루할 정도로 안정적이기 전까지는 병렬화(parallelize)하고 싶은 충동을 억제하십시오. 지루함이 목표이지, 위로금이 아닙니다.

역할 파일 형식(role-file format), 출처 도구(provenance tooling), 또는 구체적인 QA 에이전트 설정 등 이 중 어떤 부분에 대해서든 댓글로 더 깊이 논의할 준비가 되어 있습니다. 이것은 우리에게 여전히 진화 중인 시스템이며, 우리는 모든 문제를 완전히 해결한 척하기보다는 같은 것을 만들고 있는 사람들과 의견을 나누고 싶습니다.