코딩 에이전트 실전 운영 다섯 원칙: 스펙 우선·권한 분리·완료 정의·질문 강제·컨텍스트 관리

핵심 메시지

• 45분 안에 무언가를 만들어 보이는 시범과, 그 코드를 프로덕션에서 유지할 책임은 전혀 다른 문제다. 바이브 코딩이 무너지는 지점이 바로 여기다.
• 이제 개발자가 관리하는 대상은 코드가 아니라 스펙이다. 탐색·제안·적용·보관 네 단계를 거치며 설계 논의 전체가 저장소에 남는다.
• 어떤 행위자도 자기 코드를 승인하지 않는다. 작업자와 검토자를 분리하고, 매번 빈 컨텍스트로 새로 띄우는 것이 요점이다.
• '완료'가 무엇인지 미리 정의해야 매번 다른 결과가 나오지 않는다. 빌드 무결점, 테스트 전체 통과, 커버리지 목표처럼 기계가 확인할 수 있는 형태여야 한다.
• 확실하지 않으면 멈추고 물으라고 지시하는 것이 토큰을 아낀다. 잘못 이해한 채 네 시간을 달려 4,500개의 초록색 테스트를 내놓는 것이 최악이다.

쉽게 이해하기

발표자는 1년 전까지 중괄호와 세미콜론을 한 줄씩 직접 타이핑하는 것을 좋아했고 그것을 놓고 싶지 않았다고 말한다. 지금은 여러 탭을 옮겨 다니며 어느 에이전트가 입력을 기다리는지 확인하는 방식으로 일한다. 이 강연은 그 변화 과정에서 정착시킨 작업 방식을, 특정 도구가 아니라 원칙의 형태로 정리한 것이다.

핵심 진단은 명확하다. 무대에서 45분 만에 무언가를 만들어 보이는 것은 어렵지 않지만, 그 코드가 프로덕션에 들어가고 앞으로도 계속 동작하리라는 데 시간을 걸어야 하는 자리에서는 이야기가 달라진다. 발표자는 이런 방식을 '마인드풀 엔지니어링'이라 부르며, 지금 무엇이 벌어지는지 인지하고 실제로 중요한 것에 집중한다는 점에서 바이브 코딩의 정반대라고 설명한다.

첫 번째 원칙은 코드보다 스펙이 먼저라는 것이다. 발표자는 여러 에이전트에서 함께 쓸 수 있는 플러그인을 통해 탐색·제안·적용·보관 네 단계로 작업한다. 탐색 단계에서는 코드를 쓰지 않고 에이전트가 오히려 사용자를 인터뷰하며, 이미 존재하는 소프트웨어라면 그냥 그것을 쓰라고 말해 달라는 지시까지 넣는다. 제안 단계에서 요구사항이 설계와 명세, 작업 목록으로 바뀌고, 적용 단계에서 코드와 테스트가 쓰이고 검토가 반복된다.

두 번째 원칙은 권한 분리다. 사용자가 대화하는 오케스트레이터가 커밋과 푸시, PR 생성을 맡고, 작업자는 코드를 쓰고, 검토자는 결과물이 스펙·설계·작업 목록과 맞는지만 본다. 검토자는 한 글자짜리 수정도 직접 하지 않고 작업자에게 되돌려 보낸다. 중요한 것은 역할 이름이 아니라 매번 새 컨텍스트로 시작한다는 점이다. 방금 코드를 쓴 쪽에게 검토를 맡기면 '내가 썼으니 동작한다'는 정보가 이미 컨텍스트에 있어 제대로 보지 않는다. 자기 PR을 자기가 승인하는 것과 같다.

나머지 세 원칙은 완료 정의, 질문 강제, 컨텍스트 관리다. 완료는 빌드가 깨끗한지, 테스트가 모두 통과하는지, 커버리지가 목표를 지키는지처럼 기계가 확인할 수 있게 정의한다. 질문 강제는 스펙이 모호하거나 범위가 의심될 때, 사람이 직접 실행해야 할 일이 있을 때 멈추고 묻게 하는 것이다. 컨텍스트 관리는 창이 100만 토큰이어도 20만을 넘기지 않는 쪽을 택하는 문제이며, 발표자는 코드베이스 지도와 출력 요약, 최신 문서 조회를 도구로 쓴다.

주요 인사이트

• 에이전트 정의에 붙이는 '당신은 시니어 엔지니어다' 같은 문장은 성격을 부여하는 장치가 아니다. 신입이라고 써도 결과는 비슷하다. 실제로 효과가 있는 것은 사용할 프레임워크와 패턴, 기술 이름 같은 사실 정보이며, 이는 자동완성의 후보를 좁히는 역할을 한다.
• 컨텍스트 창이 커진 것은 그것을 다 채워도 된다는 뜻이 아니다. 창을 가득 채우면 모순되는 내용이 함께 남아 모델이 혼란에 빠지므로, 창이 100만 토큰이어도 20만 아래를 유지하는 편이 낫다는 것이 발표자의 실무 기준이다.
• 커밋은 개별 작업이 아니라 작업 그룹 단위로 한다. 작업 하나하나는 너무 작을 수 있고, 반대로 한 그룹에 너무 많이 들어 있으면 목록을 다시 쪼개면 된다. 발표자는 PR 생성까지는 에이전트에 맡기되 병합은 사람이 직접 한다.
• 질문하게 만드는 지시는 안전장치이기도 하다. 그러지 않으면 에이전트는 사용자를 방해하지 않으려고 샌드박스의 가드레일을 우회할 방법을 몇 시간이고 찾는다. 발표자는 권한이 필요한 작업을 셸 스크립트 몇 줄로 내놓게 하고 자신이 직접 실행한다.
• 발표자는 이 방식이 사실은 오래전부터 소프트웨어를 만들어야 했던 방식과 같다고 인정한다. 스펙을 쓰고, 완료 기준을 정하고, 결정과 근거를 개발 일지로 남기고 저장소에 커밋하는 일 — 관리자들이 그토록 요청했던 것을 이제 에이전트가 대신 해 준다는 것이다.

자주 묻는 질문

관련 AI 소식