AI에게 Go 코드를 읽히기 전에 RPC 요약본을 전달하기

Go의 gRPC 코드베이스를 AI에게 읽힐 때, AI가 매번 grep을 반복하는 것이 번거로워 rpcatlas라는 작은 CLI 도구를 만들었습니다. RPC별 처리 흐름을 Markdown으로 출력하는 도구입니다.

요약

rpcatlas는 Go의 gRPC handler를 기점으로 "해당 RPC가 어디를 통과하는지"를 Markdown으로 출력하는 CLI입니다.
build도 DB도 서버도 필요 없으며, go install을 통해 명령어를 실행하기만 하면 됩니다.
AI에게 코드를 읽히기 전의 사전 준비로서, grep의 반복이나 함수 호출 등의 확인 누락을 줄이기 위해 만들었습니다.

go install github.com/usuginus/go-rpcatlas/cmd/rpcatlas@latest

문제 의식

PR 리뷰나 장애 조사, 사양 확인, 영향 범위 확인 등 AI에게 코드를 읽히는 상황이 늘어났습니다.

그때 은근히 어려운 점이 "어떤 파일을 어떤 순서로 읽게 할 것인가"입니다.

Go의 gRPC / Clean Architecture 스타일의 코드베이스라면, 하나의 RPC 처리가 여러 계층(layer)에 흩어져 있습니다.

handler
usecase
repository
model
interface 구현
DI / constructor
...

AI Agent는 조사 대상 코드를 찾을 때 grep을 반복합니다.

grep handler...
grep usecase...
grep repository...
...

리뷰나 장애 조사에서 가장 먼저 알고 싶은 것은 "대상 RPC가 결국 어디를 통과하는가"입니다.

PR의 차이점(diff)에 handler가 나타나더라도, 그것만으로는 전체상을 볼 수 없습니다. 그 handler가 어떤 usecase를 호출하고, 어떤 repository를 건드리며, 어떤 외부 서비스로 나가는지. interface나 DI, map dispatch, 조건 분기(conditional branch)에 의해 처리가 어디서 전환되는지.

이것들은 grep을 반복하면 알 수 있지만, 매번 하면 시간이 걸립니다. AI에게 시키면 관련 있어 보이는 파일들을 넓게 읽으려 하기 때문에, token을 불필요하게 사용하게 되고, 중요한 분기나 interface 구현을 읽어 넘기는 경우도 있습니다.

실행 경로를 엄밀하게 재현하고 싶은 것은 아닙니다. 리뷰나 조사의 시작 단계에서 "일단 이 부근을 읽으면 되겠구나"라고 파악할 수 있으면 충분합니다.

사용법

설치했다면 대상 리포지토리에서 명령어를 실행하기만 하면 됩니다. 우선 --list로 검출 가능한 RPC를 목록으로 확인합니다.

rpcatlas ./... --list

| kind | rpc | handler | request | response |
| --- | --- | --- | --- | --- |
| grpc | `CreateFoo` | `fooService.CreateFoo` | `*foov1.CreateFooRequest` | `*foov1.Foo` |
...

조사하고 싶은 RPC가 결정되면 --rpc로 call tree를 출력합니다. 장애 조사 등에서는 대상 RPC가 쉽게 결정되는 경우가 많을 것입니다.

rpcatlas ./... --rpc CreateFoo --depth 5 --format markdown

## CreateFoo
### execution summary
- kind: `grpc`
...

이것을 AI에게 실행하게 하거나, 이 출력을 AI 리뷰 전에 전달해 두면 어떤 흐름부터 보면 좋을지 파악하기 쉬워집니다. 로컬에서 Claude Code나 Codex에게 조사를 시킬 때도 처음에 grep 하는 횟수가 크게 줄었습니다.

출력에 포함되는 4가지 정보

출력은 크게 다음 4가지로 구성되어 있습니다.

1. execution summary

RPC의 입구, request / response, 검출된 layer의 개수 등의 요약입니다. AI에게 "이 RPC가 어느 정도 복잡한가"를 미리 전달하기 위한 목적입니다.

2. call tree

handler에서 호출되는 함수를 tree 형태로 표시합니다. 단순한 call graph와 다른 점은, 리뷰 시 읽기 편하도록 layer 이름을 붙였다는 점입니다.

[handler]
[usecase]
[repository]
...

3. function index

call tree에 등장한 함수를 layer별로 목록화합니다. "repository만 보고 싶다", "external client만 보고 싶다"와 같은 상황에서 유용하게 사용할 수 있습니다.

4. decision points

리뷰나 장애 조사에서 중요해지기 쉬운 분기(branch) 정보를 별도로 정리합니다. 개인적으로 가장 만들고 싶었던 부분입니다.

interface calls: interface를 통한 호출과 그 후보 구현체들. DI(Dependency Injection)나 constructor(생성자)를 따라가지 않으면 구현 내용을 파악하기 어려운 부분입니다.
function values: 함수를 변수나 인자로 전달하는 부분. callback이나 workflow의 일부로서 처리가 삽입되는 케이스를 포착합니다.
conditional paths: if, switch, type switch 등 조건에 따라 실행 경로가 바뀌는 부분. 특정 조건에서만 발생하는 부작용(side effect)이나 외부 호출을 찾기 쉽게 해줍니다.
keyed dispatches: map[key]나 registry를 통해 구현을 선택하는 부분. 이벤트 종류나 설정값에 따라 다른 handler가 호출되는 코드를 목록으로 볼 수 있습니다.

map이나 registry를 통해 구현이 전환되는 코드는 grep으로 찾기 쉽지 않으므로, call tree에 포함시키지 않고 decision point로서 독립적으로 출력하도록 했습니다.

설계 방침

가장 먼저 결정한 것은 "완전한 분석기를 지향하지 않는다"는 것이었습니다. runtime의 경로를 증명하려는 것이 아니라, 리뷰나 조사의 입구에서 사용할 수 있는 대략적인 조감도를 빠르게 제공할 수 있다면 충분하다고 생각했기 때문입니다.

따라서 다음과 같은 점을 중시했습니다.

간편함: go install만으로 설치 가능. DB도 서버도 필요 없음. 명령어를 실행하기만 하면 됨.
가벼움과 속도: source-only, stateless, build 불필요, runtime tracing 불필요. 대부분의 경우 1초 이내에 완료.
AI와의 궁합: Markdown / JSON으로 출력. CI나 Slack bot에 올리기 쉬움. third-party module에 대한 의존성도 없음.

CodeGraph 계열 도구와의 차이

AI에게 코드를 읽히기 위한 CodeGraph 계열 도구들도 늘어나고 있습니다. repository를 index하고, graph DB나 MCP를 통해 코드를 추출하는 접근 방식은 강력합니다.

하지만 CI 상의 AI 리뷰나 Slack bot처럼 "그 자리에서 즉시 동작하기를 원하는" 상황에서는, 사전 준비가 필요한 도구는 사용하기 조금 까다롭습니다. rpcatlas는 이 점을 명확히 구분하여 설계했습니다.

구분	CodeGraph 계열	rpcatlas
사전 준비	index 구축, DB / 서버 필요	불필요 (`go install`만 수행)
...

왜 AST만으로 수행하는가

Go의 call graph를 만드는 방법은 go/packages, SSA, gopls, LSP 등 다양합니다. 그럼에도 rpcatlas는 AST 기반에 가깝게 설계되었습니다.

목적이 "완전한 분석"이 아니라 "리뷰 전의 사전 준비"이기 때문입니다. AST만 사용하면 의존성 download나 build tags, 환경 변수, 생성물, 외부 서비스 등에 휘둘리지 않으며, 다음과 같이 사용하기 용이합니다.

build나 service 실행 없이 동작
CI에서도 Slack bot에서도 가볍게 호출
private repo에서도 다루기 쉬움
"우선 읽는 순서만 알면 충분하다"는 상황에서 사용
명령어를 실행하면 즉시 결과 반환

동작 원리

처리 흐름은 대략 다음과 같습니다.

handler 검출

gRPC handler는 대개 다음과 같은 형태를 띱니다.

func (s *fooService) CreateFoo(
ctx context.Context,
req *foov1.CreateFooRequest,
...

rpcatlas는 이 signature와 package / file path 규칙으로 handler를 검출합니다. 규칙은 .rpcatlas.yaml에서 조정할 수 있습니다.

version: 1
handlers:
  match:
    ...

layer의 분류

함수 호출은 설정한 rule에 따라 layer로 분류합니다. layer 이름은 임의로 지정할 수 있으므로, 팀의 아키텍처 용어(application, persistence, gateway 등)에 맞출 수 있습니다.

layers:
  - name: usecase
    match:
      ...

interface / DI / dispatch를 별도로 분리한 이유

비즈니스 로직 코드에서는 함수 호출만 추적해서는 흐름이 보이지 않을 때가 있습니다. 예를 들어 usecase가 interface에 의존하고 있는 경우, 실제 구현체는 constructor나 DI(Dependency Injection)를 확인하지 않으면 알 수 없습니다.

map이나 registry를 통해 처리가 전환되는 경우도 있습니다.

handler := handlers[event.Type]
return handler.Handle(ctx, event)

이러한 부분은 call tree에 포함시키지 않고, decision point로서 별도로 분리함으로써 놓치기 쉬운 포인트를 가시화했습니다.

한계와 사용법

AST(Abstract Syntax Tree) 기반의 정적 분석이므로 한계도 있습니다. 출력 결과는 실행 시의 경로를 엄격하게 재현하는 것이 아니며, 다음과 같은 케이스에서는 누락이나 오검출이 발생할 수 있습니다.

reflection (리플렉션)
복잡한 factory (팩토리)
동적으로 구성되는 function value (함수 값)
build tag나 generated code (생성된 코드)에 강하게 의존하는 구성
runtime config (런타임 설정)에 의해 처리가 크게 변하는 코드

rpcatlas는 어디까지나 리뷰나 조사를 위한 사전 준비 도구이며, 소스 코드를 읽음으로써 최종 판단을 내리는 방식으로 사용하는 것을 상정하고 있습니다. rpcatlas의 출력만으로 판단하게 하는 것이 아니라, 개요를 파악한 뒤 중요한 부분은 반드시 source (소스)를 읽는다는 전제가 필요합니다.

Go의 작성 방식은 팀이나 코드베이스에 따라 상당히 다르기 때문에, 아직 추적하지 못하는 패턴이 남아 있을 것입니다. "이 호출을 추적할 수 없다", "이 DI 패턴을 잡지 못한다"와 같은 케이스가 있다면 issue나 PR을 보내주시면 큰 도움이 됩니다. 작은 재현 코드가 있다면 특히 더 좋습니다.

CI / AI 리뷰에 통합하기

rpcatlas는 CLI 도구이므로, 쉘을 실행할 수 있는 AI 에이전트(Claude Code나 Codex, CI 상의 리뷰 bot 등)에게는 출력을 미리 준비해 주는 대신, 필요할 때 직접 실행하게 하는 것이 간편합니다.

이미지 상으로는 prompt (프롬프트)에 도구 사용법을 적어두고, AI 스스로 실행하게 하는 방식입니다.

## rpcatlas
코드를 탐색하기 전에 rpcatlas를 이용하여 RPC 처리 흐름의 개요를 확인하십시오.
1. 먼저 `rpcatlas ./... --list`를 실행하여 RPC 목록을 확인한다
...

포인트는 목록이나 call tree를 처음부터 전부 context (컨텍스트)에 집어넣지 않는 것입니다. AI가 필요한 RPC를 선택해서 실행할 수 있으므로, 관련 없는 RPC의 출력을 읽게 하지 않아도 되어 token (토큰) 절약에도 도움이 됩니다.

CI의 리뷰 bot에 통합할 때도 마찬가지로, bot에게 쉘 실행을 허용해 두면 차이점(diff)으로부터 대상 RPC를 찾아 rpcatlas를 실행하는 단계까지 맡길 수 있습니다.

마치며

AI에게 코드를 읽히는 기회는 늘어났지만, 전달할 context를 어떻게 만들지는 아직 탐색 단계에 있습니다.

rpcatlas는 그중에서도 Go gRPC의 처리 흐름에 집중하여, 가볍게 전체상을 보여주기 위한 도구입니다.

grep 반복을 줄이고, RPC 단위로 context를 좁힘
AI에게 전달하는 token을 절약하고, 리뷰나 장애 조사의 진입점을 단축함
source-only / stateless 방식으로, go install만으로 명령어 하나로 call tree를 출력

아직 완전한 파서 (Parser)는 아니지만, 처음에 전체적인 모습을 파악할 수 있는 것만으로도 코드 읽기를 시작할 때 훨씬 수월해집니다. 개인적으로 사용하는 용도로는 실용적인 수준에 도달했기에, 앞으로는 실제 코드베이스에서 추적할 수 없는 케이스들을 조금씩 해결해 나갈 계획입니다.

유용하다고 생각되신다면 꼭 한번 시도해 보세요.

go install github.com/usuginus/go-rpcatlas/cmd/rpcatlas@latest
rpcatlas ./... --list
rpcatlas ./... --rpc CreateFoo --depth 5 --format markdown