Claude Code가 Kiro 언어를 사용하도록 가르친 방법

요약 (TL;DR) — Claude Code는 환경 변수가 가리키는 곳 어디로든 요청을 보냅니다. 이를 작은 로컬 번역기로 향하게 하면, 이미 결제 중인 Kiro 플랜에서 실행할 수 있습니다. 아래에 전체 설정 방법과 알아두어야 할 두 가지 문제점을 정리했습니다.

Claude Code와 Kiro는 재미있는 공통점이 하나 있습니다. 내부적으로 동일한 Claude 모델을 사용한다는 점입니다. 같은 두뇌를 가지고 있죠. 다만 서로 다른 방언을 사용하며 성장했기 때문에, 기본 상태로는 대화를 나눌 수 없습니다.

저는 Claude Code를 위한 두 번째 구독을 시작하려던 참에 이 사실을 깨달았습니다. 제 Kiro 플랜은 이미 매달 갱신되고 있었고, Claude Code가 저에게 다시 비용을 청구하려는 바로 그 모델들을 이미 제공하고 있었습니다. 똑같은 대상과 대화하기 위해 두 번 결제하는 것은 불합리하게 느껴졌습니다.

그래서 두 번째 계정을 구매하는 대신, 통역사를 고용했습니다. 두 서비스 사이에 위치하여 Claude Code의 말을 듣고, Kiro가 이해할 수 있는 방언으로 모든 것을 전달하는 작은 프로그램입니다. 어떻게 설정하는지, 그리고 이 과정에서 무엇을 배웠는지 소개합니다.

왜 그냥 대화할 수 없는가

Claude Code는 사람들이 생각하는 것보다 더 개방적입니다. 요청을 어디로 보낼지 하드코딩되어 있지 않습니다. 하나의 환경 변수인 ANTHROPIC_BASE_URL을 읽고, 모든 것을 해당 주소로 전송합니다. 보통은 공식 엔드포인트(endpoint)이지만, 당신이 지정하는 곳이라면 어디든 기꺼이 요청을 보냅니다.

그것이 바로 기회입니다. 이를 로컬(local) 어딘가로 지정하면 이 모든 것이 가능해집니다.

통역사 소개

문제는 Claude Code와 Kiro가 표현 방식이 다르다는 점입니다. 단순히 한쪽을 다른 쪽으로 리다이렉트(redirect)한다고 해서 서로 이해할 것이라고 기대할 수는 없습니다. 양쪽 모두에 능통한 번역기가 필요합니다.

그것이 바로 kiro-gateway-next입니다. 당신의 컴퓨터에서 실행되는 아주 작은 프록시(proxy)입니다. 요청이 한 가지 방식으로 도착하면 다른 방식으로 재구성되어 나갑니다.

Claude Code (Anthropic 방식으로 표현) ──▶ kiro-gateway (Kiro 방식으로 재표현) ──▶ 당신의 Kiro 계정

Claude Code는 자신이 기대하는 형식으로 답변을 받습니다. Kiro는 자신이 인식할 수 있는 요청을 받습니다. 그 중간에서 인터프리터 (Interpreter)가 재표현 (Rephrasing)을 수행하며, 대화는 자연스럽게 흘러갑니다.

단계별 설정 방법

6단계. 약 5분 소요. 그 어떤 것도 git clone보다 복잡하지 않습니다.

1단계 — Claude Code 설치 (버전 2.1.29 이상):

npm install -g @anthropic-ai/claude-code

2단계 — 인터프리터를 가져오고 깨끗한 작업 공간을 준비합니다:

git clone --depth=1 https://github.com/coderhisham/kiro-gateway-next ~/kiro-gateway
cd ~/kiro-gateway
python3 -m venv .venv
...

3단계 — 세부 정보를 입력합니다. ~/kiro-gateway/.env 파일을 생성하세요:

PROXY_API_KEY="kiro-local-proxy-key"
KIRO_CLI_DB_FILE="/Users/<YOUR_USER>/Library/Application Support/kiro-cli/data.sqlite3"
SERVER_HOST="127.0.0.1"
...

PROXY_API_KEY는 직접 선택하는 암호 (Passphrase)입니다. KIRO_CLI_DB_FILE은 macOS에서 kiro-cli가 로그인 정보를 보관하는 위치입니다.

4단계 — 실행합니다:

~/kiro-gateway/.venv/bin/python ~/kiro-gateway/main.py --port 9000 &

5단계 — 정상 작동하는지 확인합니다:

curl http://127.0.0.1:9000/health

6단계 — Claude Code에 전송 위치를 알려줍니다. ~/.claude/settings.json 파일을 생성하세요:

{
  "env": {
    "ANTHROPIC_BASE_URL": "http://127.0.0.1:9000",
...

해당 키는 3단계에서 설정한 암호와 일치하기만 하면 됩니다. 이는 로컬 (Local) 환경이며, 절대 사용자의 기기를 벗어나지 않습니다. claude를 실행하고, 키에 대한 질문이 나오면 'yes'라고 답하면 Kiro와 대화할 수 있습니다.

참고할 사항: 만약 사용 중인 Kiro 플랜에 포함되어 있다면, 모델을 claude-opus-4-8로 전환하여 **1M-토큰 컨텍스트 윈도우 (Context Window)**를 갖춘 Opus 4.8을 사용할 수 있습니다. 저는 평소라면 조각조각 나누어 설명해야 했을 코드베이스 (Codebase)를 통째로 주었습니다. 그것은 한 번에 전체를 읽어 들였습니다.

아무도 경고해주지 않는 두 가지 걸림돌

첫 시도에 완벽하게 진행되지는 않았습니다. 두 가지 문제가 저를 넘어뜨렸고, 두 가지 모두 실제 설정 시간보다 더 많은 시간을 잡아먹었습니다.

첫 번째 난관 — 너무 긴 이름들. MCP 중심의 플러그인을 몇 개 추가했더니, 아무런 설명도 없이 400 Improperly formed request라는 무미건조한 오류와 함께 모든 것이 멈춰버렸습니다. 마치 벽에 부딪힌 것 같았습니다.

이유는 이렇습니다: Kiro는 64자를 초과하는 도구(tool) 이름을 허용하지 않는데, MCP 서버들은 mcp__github__check_if_a_repository_is_starred_by_the_authenticated_user와 같이 입에 붙지도 않는 긴 이름을 생성하는 것을 매우 좋아합니다. 직접 세어보세요. 제한을 넘어섰습니다.

도구 이름은 짧게 유지하세요. 만약 단순히 도구의 개수가 너무 많아 요청(request)이 비대해지는 것이 문제라면, 게이트웨이(gateway)에 완화 장치가 있습니다:

AUTO_TRIM_PAYLOAD=true

두 번째 난관 — Apple Silicon과 충돌하는 Rust 빌드. 한 AWS 플러그인이 Rust 의존성(dependency)을 불러오는데, 이것이 제 M-시리즈 Mac에서 x86용 교차 컴파일(cross-compile)을 시도하다가 x86_64-apple-darwin 타겟이 없다는 오류와 함께 쓰러졌습니다. 한 줄이면 해결되며, 그 후 Claude Code를 재시작하면 됩니다:

rustup target add x86_64-apple-darwin

두 난관 모두 게이트웨이의 잘못은 아닙니다. 두 생태계가 협력하는 과정에서 발생하는 일반적인 마찰일 뿐입니다. 튜토리얼들은 이러한 오류들을 생략하곤 하므로, 저처럼 미리 알았더라면 좋았을 이 정보를 주의 사항으로 삼으시기 바랍니다.

유일하고 솔직한 트레이드오프 (trade-off)

공짜라고 거짓말하지는 않겠습니다. 약간의 지연 시간(latency)이 발생합니다. 요청이 로컬 프로세스를 거쳐 우회하고 그 과정에서 재구성되기 때문에, 직접 연결하는 것보다 약간 느리게 도착합니다. 하지만 두 시간 정도 지나니 저는 더 이상 느끼지 못하게 되었습니다. 만약 작업이 시간에 민감하다면, 의존하기 전에 직접 테스트를 해보세요.

그리고 만약 무언가 제대로 작동하지 않는다면, 로그를 켜세요:

DEBUG_MODE="errors"

이 설정은 모든 실패한 호출에 대해 전체 요청과 응답을 캡처합니다. 제가 추측하는 대신 긴 이름 문제를 찾아낼 수 있었던 것도 바로 이 방법 덕분이었습니다.

저녁 시간 한 번을 투자할 가치가 있었을까?

결정을 내리게 한 계산법은 다음과 같습니다. 매달 무기한으로 하나의 모델 세트를 위해 두 개의 구독료를 내는 것인가? 아니면 단 한 번의 조용한 저녁 시간과 Rust를 향한 약간의 투덜거림인가?

저는 저녁 시간을 선택했습니다. 그 이후로 인터프리터(interpreter)는 백그라운드에서 계속 실행되고 있고, 제 청구 금액은 변함이 없으며, Claude Code는 차이를 전혀 인지하지 못한 채 Kiro와 아주 즐겁게 대화하고 있습니다.

이미 Kiro를 유료로 사용 중이면서 Claude Code를 눈여겨보고 있었다면, 이것은 가장 쉽게 선택할 수 있는 옵션입니다. 최악의 경우, 이름이 세 글자 너무 긴 도구 때문에 하룻밤을 허비하는 정도일 것입니다. 최선의 경우, 게이트웨이가 거기 있다는 사실조차 잊어버리고 동일한 Claude에 대해 이중으로 비용을 지불하지 않는 즐거움을 누리게 될 것입니다.

두 번째 구독이 필요한 것이 아닙니다. 당신에게 필요한 것은 번역기(translator)입니다.

이 인터프리터(interpreter)는 jwadow의 kiro-gateway를 기반으로 구축되었습니다. AWS 플러그인(plugins)은 awslabs에서 가져왔습니다.