80개 마이크로서비스용 Claude Code 시스템 운영기

4월에 저는 Claude Code 위에 만든 시스템에 대해 글을 썼습니다. 이 시스템은 에픽 하나를 80개 이상의 마이크로서비스에서 PR 가능한 코드로 바꿉니다. 그 글을 읽었다면, 저는 마치 뭔가를 끝낸 사람처럼 들렸을 겁니다.

사실은 끝내지 못했습니다. 이건 제가 쓸 계획이 없었던 후속 글입니다. 여기에는 무엇이 잘못되었는지, 제가 무엇을 잘못 보았는지, 그리고 제 자신을 위해 만든 도구가 결국 기술팀 전체, 새로 합류한 모든 사람, 그리고 아예 코드를 쓰지 않는 사람들까지 사용하게 된 이야기가 담겨 있습니다.

한 파일에 "DO NOT"를 여덟 번이나 써 두었습니다

몇 달쯤 지나자, 저는 제 규칙을 더는 믿지 않게 되었습니다.

가장 찜찜했던 건 커밋이었습니다. 제 프롬프트에는 시스템이 절대로 git commit을 실행하면 안 된다고 대문자로 써 두었습니다. 저는 모든 diff를 읽고 나서야 그것이 기록이 되길 바라기 때문에, 이것은 제가 가장 중요하게 여기는 규칙입니다. 어느 날 왜 그 규칙이 불안하게 느껴지는지 살펴보러 갔더니, 두 가지를 발견했습니다. 제 설정 파일 자체가 git 명령을 명시적으로 허용하고 있었고, 제 참조 문서 하나에는 git add && git commit 스니펫이 이미 들어 있었습니다. 저는 모델에게는 열여덟 군데에서 NEVER라고 말하면서, 다른 두 군데에서는 허가와 예시를 함께 건네고 있었던 겁니다.

그때까지는 무슨 문제가 생기든 제 해결책은 늘 같았습니다. 프롬프트 파일을 열고 대문자로 한 줄을 더 쓰는 것. MANDATORY. NEVER. 혹시 모르니 경고 이모지까지.

그래서 어느 주말에는 앉아서 제가 만든 것 전부를 감사했습니다. 같은 규칙 세트(커밋하지 말 것, lint를 돌리지 말 것, 단계를 건너뛰지 말 것)가 18개의 서로 다른 파일에 복붙되어 있었습니다. 그중 한 파일에는 "DO NOT run"이 여덟 번이나 적혀 있었습니다. 메인 오케스트레이터 프롬프트는 1,464줄이었고, 그 전부가 한 번에 로드되고 있었습니다.

조금 우스웠습니다. 이건 제가 남의 pull request에서 바로 지적하는 부분이기 때문입니다. 중복된 로직, 단일 진실 공급원의 부재. 저는 절대 승인하지 않았을 겁니다. 그런데 제가 직접, 답답함을 한 줄씩 쌓아가며 써 놓은 것이었습니다.

그 피해는, 규칙이 복사·붙여넣기된 코드베이스라면 누구나 예상할 수 있는 종류였습니다.

• 드리프트. 한 파일에서 규칙을 바꾸면 나머지 17개가 조용히 그와 어긋났습니다. 모델은 어느 복사본이 진짜인지 추측해야 했습니다.

• 희석. 모든 것이 MANDATORY라면, 아무것도 MANDATORY가 아닙니다. 모델은 대출 계산을 보호하는 규칙과 괄호를 어디에 두는지에 대한 규칙을 구분할 수 없었습니다.

• 비용. 매 턴마다, 같은 금지 사항들을 다시 읽느라 시간을 썼습니다. 사실은 제 코드를 읽어야 했는데 말입니다.

요청하는 것과 막는 것은 같은 일이 아닙니다

해결책은 두 부분이었습니다.

첫 번째는 지루하지만 필요했습니다. 바로 단일 규칙집이었습니다. 모든 규칙에 GIT-1처럼 짧은 ID를 붙인 하나의 파일입니다. 예를 들어 GIT-1은 "절대 커밋하지 말 것", ISO-1은 "격리된 작업 공간 안에서만 쓸 것"입니다. 이제 다른 모든 파일은 "GIT-1과 ISO-1을 따르라"라고만 적고 그 이상은 없습니다. 제 메인 지시 파일은 370줄에서 약 145줄로 줄었습니다.

두 번째는 제가 이 도구들을 생각하는 방식을 바꿔 놓았습니다.

저는 규칙을 두 종류로 나누었습니다. 하나는 판단이 필요한 것들입니다. 예를 들면 어떤 서비스의 기존 코드 스타일에 맞추는 것 같은 것입니다. 모델은 이런 것들을 재량껏 적용하고, 그건 괜찮습니다. 다른 하나는 불변 조건입니다. 절대 커밋하지 말 것. 작업 공간 밖에 쓰지 말 것. 이것들은 매번 반드시 지켜져야 합니다.

불변 조건에 대해서는 더 이상 요청하지 않기로 했습니다. Claude Code에는 권한 시스템이 있고, 저는 그런 규칙들을 거기로 옮겼습니다. 이제 그 명령은 실행되기 전에 거부됩니다. 그에 대한 모델의 의견은 더 이상 중요하지 않습니다.

프롬프트는 요청입니다. 거부 규칙은 벽입니다. 저는 몇 달 동안 같은 요청을 점점 더 큰 목소리로 외치고만 있었던 셈입니다. 필요한 건 벽이었는데 말입니다.

완벽한 벽은 아닙니다. 다른 명령 안에 감싸진 명령은 여전히 매처를 빠져나갈 수 있어서, 저는 문서화한 규칙도 그대로 유지했고 권한 파일도 주기적으로 확인합니다. 하지만 일상적인 동작에서의 차이는 즉시 체감됐습니다.

계획하지 않았던 디버깅까지 하게 되었습니다

4월 버전이 하던 일은 하나뿐이었습니다. 에픽을 코드로 바꾸는 것.

하지만 새로운 기능이 내 일주일의 대부분을 차지하는 건 아닙니다. 그중 상당 부분은 지원 업무입니다. 운영 환경에서 무언가가 실패했거나, 숫자가 잘못 나왔거나, 누군가는 영업일이 끝나기 전에 그 이유를 알아야 합니다.

그래서 시스템에 읽기 전용 에이전트를 넣었습니다. 하나는 로그를 검색합니다. 하나는 MongoDB를 조회합니다. 하나는 SQL을 실행합니다. 하나는 메트릭을 읽습니다. 어느 것도 아무것도 쓸 수는 없습니다.

로그 에이전트의 첫 번째 버전은 저에게 한 가지를 가르쳐 주었습니다. 저는 문제를 설명하면, 그 에이전트는 제가 상상한 로그 메시지가 어떻게 생겼을지 검색했습니다. 아무것도 찾지 못했고, 완전히 확신에 찬 태도로 아무것도 없다고 보고했습니다.

해결책은 놀랄 만큼 단순해서 민망할 정도입니다. 로그를 검색하기 전에, 먼저 코드에서 실제 로그 문자열을 검색하세요. 디버깅할 때 제가 직접 하던 일이 바로 이것입니다. 다만 그때는 그것이 하나의 단계라는 생각을 한 번도 하지 못해서, 기록해 두지 않았을 뿐입니다.

이제 우리가 해결하는 모든 사고는 런북이 됩니다. 그런 런북이 29개 있습니다. 다음에 같은 문제가 다시 발생하면, 시스템은 처음부터가 아니라 런북에서 시작하고, 그 주의 지원 담당자도 마찬가지입니다.

팀원이 풀 리퀘스트를 열었던 날

5월에 한 동료가 프레임워크에 대한 풀 리퀘스트를 열었습니다. 그건 디버깅을 위해 우리 서비스들의 로컬 클러스터를 띄워 주는 스킬이었습니다. 제가 요청한 적은 없었습니다.

몇 주 뒤에 또 다른 사람이 제가 방금 설명한 데이터베이스와 로그 에이전트를 추가했습니다. 지금까지 세 명의 팀원이 기여했습니다.

이건 토큰 숫자보다 저에게 훨씬 더 큰 의미가 있었습니다. 4월에 저는 이것이 "그저 팀에 필요한 무언가"라고 썼습니다. 솔직히 말하면, 그때 그것은 사실 제가 필요로 하던 것이었고, 팀도 그러길 바랐습니다. 다른 사람의 풀 리퀘스트는 처음으로 얻은 진짜 증거였습니다.

그 diff를 두 번 읽었던 기억이 납니다. 복잡해서가 아니었습니다. 누군가가 제 프롬프트 파일을 충분히 꼼꼼히 살펴보고 확장해 주었고, 그게 자기 자신의 저녁 시간을 들일 가치가 있다고 판단했다는 사실 때문에 두 번 읽었습니다. 그때까지만 해도 저는 무엇이 어디에 있는지 아는 유일한 사람이었습니다.

그리고 제가 만들 생각조차 하지 않았던 사람들이 사용하기 시작했습니다

지금은 전체 기술팀이 이 저장소를 사용하고 있습니다. 제가 그걸 공지하거나 밀어붙인 건 아닙니다. 한 번에 한 사람씩 퍼져 나갔습니다. 보통은 누군가 동료가 반나절 걸렸을 답을 2분 만에 얻는 걸 본 뒤였습니다.

새로 합류한 사람들도 이제 여기서 시작합니다. 80개가 넘는 서비스를 가진 회사에 들어온 사람이라면 첫 달이 어떤지 알 것입니다. 어떤 서비스가 무엇을 담당하는지 모르고, 무언가를 물을 때마다 시니어 엔지니어의 일을 방해하는 것처럼 느껴집니다. 이제는 새로 온 사람이 먼저 시스템에 묻습니다. 시스템은 서비스 맵과 코드 자체를 바탕으로 답하고, 절대 한숨 쉬지 않습니다.

새로 온 사람에게 예전의 첫 질문은 대개 "도대체 어디서부터 읽어야 하나요?"라는 식이었습니다. 저는 그 질문에 제대로 답한 적이 없었습니다. 90여 개의 서비스는 읽는 대상이 아닙니다. 이제는 저장소를 열고, 대출이 신청에서 실행으로 어떻게 이동하는지 물어보라고 합니다. 그런 다음 시스템이 가리키는 곳을 따라가면 됩니다. 그러면 더 나은 질문을 들고 돌아오고, 더 빨리 돌아옵니다.

제가 가장 놀랐던 부분은 제품 팀입니다. 그들은 코드를 작성하지 않고, 저는 그들이 이 저장소를 열 것이라고는 전혀 생각하지 않았습니다. 그런데 그들은 우리가 어떤 외부 벤더에 의존하는지, 그리고 각 벤더가 어떤 흐름 뒤에 있는지 같은 평범한 질문을 하기 위해 이걸 사용합니다. 예전에는 엔지니어에게 메시지를 보내고 시간이 나는 사람을 기다려야 했습니다. 이제는 직접 묻고, 실제 코드에 근거한 답을 바로 얻습니다.

저는 코드를 배포하는 파이프라인을 만들었습니다. 그런데 사람들이 가장 자주 찾는 것은 더 단순합니다. 시스템이 어떻게 동작하는지 묻고, 곧바로 답을 받는 방법입니다.

누적되며 큰 변화를 만든 더 작은 변화들

리뷰어. 이제 계획서나 diff를 제가 보기 전에 읽는 리뷰 에이전트가 있습니다. 그중 하나는 특히 핀테크 리스크를 점검하고, 작업을 차단할 수도 있습니다. 그 차단은 예전에는 프롬프트 한 줄이었습니다. 이제는 워크플로가 확인하는 상태값이 되었기 때문에, 말로 얼버무려 넘길 수 없습니다. 제가 정한 한 가지 원칙은: 리뷰어는 작성자만큼은 최소한 같은 수준의 모델이어야 한다는 것입니다.

작업에 맞는 올바른 모델. 로그를 가져오는 데는 가장 비싼 모델이 필요하지 않습니다. 깊이 있는 코드 분석과 테스트 주도 구현에는 필요합니다. 이제 각 에이전트는 자기 작업에 맞는 모델에서 실행됩니다.

두 번째 코드베이스. 이제 시스템은 서로 분리된 두 개의 저장소 집합 전반에서 동작한다. 이전에는 하나만 알고 있었다.

4월의 나에게 해주고 싶은 말

1. 같은 규칙을 세 번째로 쓰고 있다면, 구조에 문제가 있는 것이다. 문제는 모델이 아니다.

2. 어떤 규칙이 불변식인지 정하고, 그 규칙은 프롬프트 바깥에서 강제하라.

3. 실제로 하는 일에 맞춰 만들어라. 나에게는 디버깅이 그 일이었다. 코드 생성이 더 좋은 시연이 되더라도 말이다.

4. 준비된 느낌이 들기 전에 먼저 공유하라. 이 시스템의 가장 좋은 부분들은 내가 쓰지 않았다.

5. 실제로 누가 쓰는지 보라. 나는 이것을 에픽을 배포하는 엔지니어들을 위해 만들었다. 그런데 신규 입사자와 제품 팀도 이걸로 많은 가치를 얻었고, 내가 부차적인 기능이라고 여겼던 것을 위해 사용했다.

수치

깔끔한 도입 전후 벤치마크는 없다. 그리고 굳이 만들어내고 싶지도 않다. 대신 내가 셀 수 있는 것은 다음과 같다.

• 92개 서비스가 현재 매핑되어 있으며, 4월에 썼던 80개 이상에서 늘어난 수치다.

• 31개 기능이 프레임워크 안에서 자체 작업 공간을 갖고 있다.

• 29개 실행 가이드가 실제 운영 장애에서 나왔다.

• 3명의 팀원이 이 코드에 기여했으며, 기술팀 전체가 이를 사용하고 있다.

• 첫 번째 글의 토큰 수치는 여전히 유효하다. 에픽당 대략 75,000개에서 15,000개로 줄었다. 무거운 읽기는 별도의 에이전트에서 이루어지기 때문이다.

전체 구조가 맞물리는 방식

위 내용을 모두 건너뛰었다면, 이것이 한 장으로 본 전체 시스템이다. 세 종류의 요청이 들어간다: 질문, 에픽, 또는 장애. 세 가지 모두 같은 공유 지식을 읽고 같은 가드레일 안에서 실행되며, 각자가 만들어낸 결과는 다음 사람이 쓸 수 있도록 다시 들어간다.

변하지 않은 것도 있다. 나는 여전히 모든 단계를 승인한다. 나는 여전히 모든 diff를 읽는다. 나는 여전히 모든 pull request를 직접 올린다. 그 점이 바뀔 거라고 기대하지도 않고, 바뀌길 원하지도 않는다.

흥미로운 지점은 엔지니어를 루프에서 제거하는 데 있지 않았다. 엔지니어가 머릿속에 담아야 하는 문맥의 양을 줄이는 데 있었다.

비슷한 것을 만들고 있다면, 딱 한 가지가 궁금하다. 당신의 규칙 중 무엇이 벽이 되었고, 무엇이 사실상 요청에 불과했는가?

출처

• 원문: https://dev.to/akash_singh_9936/i-built-an-ai-system-for-80-microservices-six-months-later-my-whole-team-uses-it-4j14 (2026-10-02 · akash singh)