API 저장소의 Claude는 문서에서 Retry-After를 따르라고 읽었지만, 코드는 해당 값을 설정하지 않는다는 점도 찾아냈다. 다른 저장소에서 질문을 보낸 Claude는 이 차이를 반영해 수정 방향을 제안하고, 파일을 고치기 전 사용자에게 허락을 구했다.
Phonebook은 실행 중인 Claude Code 세션을 연결하는 도구다. 한 프로젝트에서 다른 프로젝트에 질문을 보내고 답을 받을 수 있다. 여러 프로젝트를 오가는 사람이나 승인된 팀원이 프로젝트 간 정보를 확인할 때 쓸 수 있다.
Phonebook은 어떻게 연결하나?
Phonebook은 세션 사이에 질문과 답변을 전달하는 중계 창구를 떠올리면 쉽다. 답변 세션이 자기 저장소를 살펴보고 응답을 보내면, 질문한 세션에 결과가 돌아온다. 답변을 받으려면 해당 세션이 실행 중이어야 한다.
시연에서는 웹 클라이언트 저장소의 세션이 작업 API의 재시도와 중복 요청 처리를 물었다. API 세션은 저장소의 문서와 코드를 확인해 답했고, 클라이언트 세션은 그 내용을 바탕으로 변경안을 제안했다. 녹화된 시연은 로그인, 채널 확인, 응답 세션 등록을 마친 뒤 진행됐다. 도구 호출은 모두 사람이 승인했다.
답변에 따르면 API는 모든 요청에 Idempotency-Key 헤더를 요구하며, 없으면 400을 반환한다. 키는 프로세스 메모리에 24시간 보관된다. 같은 키와 같은 본문을 다시 보내면 기존 201 응답과 Idempotent-Replayed: true를 돌려준다. 같은 키에 다른 본문을 보내면 409 idempotency_key_reused가 반환된다. 재시도는 네트워크 오류, 429, 503에 한정하고, Retry-After를 따르거나 없으면 500밀리초에서 8초까지 대기 시간을 늘려 최대 5회 시도하라는 내용도 확인했다. 다만 코드에는 Retry-After 설정이 없었다.
설치와 사용 전에 확인할 점은?
Claude Code와 Node.js 24가 필요하다. macOS에서 테스트했고 Linux는 자동화 테스트 대상이며, Windows는 지원하지 않는다. 이메일로 로그인하며 GitHub 연결은 필요하지 않다. 현재 신규 가입은 일시 중단됐지만 기존 설치는 계속 작동한다.
각 프로젝트 디렉터리에서 다음 명령을 실행해 설정한다. 첫 시연에서는 두 프로젝트에 같은 이메일을 사용한다.
npx agent-phonebook@0.4.1 setup
설정 과정은 변경 사항을 보여주고 브라우저에서 이메일 로그인을 연다. 브라우저와 터미널에 같은 확인 코드가 표시되는지 확인해야 한다. 설정은 해당 프로젝트에만 적용되며, 이 단계에서 세션을 응답자로 등록하지는 않는다.
두 프로젝트에서 다음 명령으로 Claude를 실행한다.
npx agent-phonebook@0.4.1 claude
Phonebook 채널 확인 때 “I am using this for local development.”를 선택하고 set_availability 준비 확인을 승인한다. 일반적인 도구 승인과 조직 정책은 그대로 적용된다. 상태는 Claude에게 “Check my Phonebook status.”라고 물어 확인할 수 있다.
응답할 프로젝트의 Claude 세션에 다음과 같이 요청해 등록한다.
Register this session as api-helper. Answer questions about this project's retry and idempotency behavior under the job-retries topic. Accept questions only from my other Phonebook sessions.
프로젝트가 실제로 답할 수 있는 주제를 골라야 한다. 등록 이름, 설명, 주제는 계정 하나만 쓰더라도 공개된다. 주제는 사용 의도를 설명할 뿐, 응답 세션이 볼 수 있는 맥락이나 사용할 수 있는 도구를 제한하지 않는다.
다른 프로젝트의 세션에서는 다음처럼 질문한다.
Ask the Phonebook agent for job-retries how this API handles duplicate job submissions and which retry behavior my client should use.
질문하는 세션은 답변자로 등록할 필요가 없다. 팀원이 쓰려면 팀원이 자기 이메일로 한 번 설정한 뒤, 응답 세션에서 해당 이메일 주소를 발신자로 승인해야 한다. 승인할 이메일은 이미 인증된 Phonebook 계정에 등록돼 있어야 한다. 승인은 해당 등록에만 유효하므로 연결이 끊긴 뒤에는 다시 등록하고 승인해야 한다. 등록 하나에 최대 10개 주소를 승인할 수 있으며, 승인된 이메일은 디렉터리에 표시되지 않는다.
저장소에서 보낸 질문과 답변에는 저장소 정보가 포함될 수 있으며, 내용은 Phonebook을 거친다. 질문과 답변은 종단 간 암호화되지 않고, 처리가 끝난 뒤 최대 7일간 보관된다. 응답 세션은 명시적으로 등록하고 승인된 발신자만 받도록 해야 한다. 신뢰할 수 있는 사람과 민감하지 않은 프로젝트에서 사용하는 편이 적절하다. 세션을 닫아도 등록 정보는 최대 24시간 오프라인 상태로 목록에 남는다.
신규 가입이 중단된 기간과 지원 환경은 사용 전에 확인해야 한다. 원문은 가입 재개 시점과 요금, 질문·답변 보관 기간의 구체적인 기준을 밝히지 않는다.
댓글 (0)
로그인하면 이 기사에 내 생각을 남길 수 있어요