Google Developer Knowledge API 적용법: Claude Code·Cursor가 최신 문서를 보게 만드는 절차

AI 코딩 도구를 쓰다 보면 같은 문제가 반복된다. 모델이 예전 SDK 옵션을 쓰거나, 블로그 글 기준으로 설정을 만들거나, 실제 문서에는 없는 권한 이름을 자신 있게 제안한다. Google Developer Knowledge API는 이 문제를 줄이는 공식 문서 검색 레이어다. 이 글은 발표 요약이 아니라, Claude Code나 Cursor 같은 도구에 붙일 때 필요한 실무 절차를 정리한다.

목표는 단순하다. Google Cloud, Firebase, Android 관련 작업을 할 때 에이전트가 최신 공식 문서를 먼저 확인하고, 그 근거를 남기게 만드는 것이다. 이 작업을 해두면 코드 생성 품질도 좋아지지만, 리뷰와 장애 대응 때 “왜 이 옵션을 썼는지” 추적하기 쉬워진다.

1단계: 어떤 작업에 문서 확인을 강제할지 정한다

모든 질문마다 공식 문서를 검색하게 만들면 느리고 시끄럽다. 먼저 강제 대상 작업을 좁혀야 한다. 추천 범위는 다음과 같다.

• Google Cloud 리소스를 생성·수정·삭제하는 작업
• IAM, 서비스 계정, OAuth, API 키처럼 보안에 영향을 주는 작업
• Firebase 보안 규칙, Storage 규칙, Firestore 인덱스 변경
• Android 권한, Gradle, Play 정책처럼 버전 영향이 큰 작업
• 배포 실패나 런타임 에러를 공식 문서 기준으로 해석해야 하는 작업

반대로 일반 TypeScript 리팩터링, UI 문구 수정, 테스트 이름 변경 같은 작업은 매번 Google 문서를 볼 필요가 없다. 규칙이 넓으면 에이전트가 도구 호출만 하다가 작업 속도를 잃는다.

2단계: 프로젝트 지침에 문서 확인 규칙을 쓴다

Claude Code라면 AGENTS.md, Cursor라면 프로젝트 룰에 명시한다. 예시는 이렇게 쓸 수 있다.

“Google Cloud, Firebase, Android API를 변경할 때는 Developer Knowledge API 또는 공식 문서 검색 도구로 현재 문서를 확인한다. 문서에서 확인한 제약, 명령, 권한 이름을 PR 설명에 남긴다. 문서 근거 없이 오래된 모델 지식만으로 인프라 코드를 변경하지 않는다.”

이 문장은 생각보다 중요하다. 코딩 에이전트는 사용 가능한 도구가 있어도 언제 써야 하는지 모르면 안 쓴다. “중요하면 찾아봐”보다 “이 범주의 변경에서는 반드시 확인한다”가 훨씬 잘 작동한다.

3단계: MCP 또는 skill을 연결한다

Google은 Developer Knowledge agent skill을 제공한다. 프로젝트에서 npx skills add google/skills --skill retrieving-developer-knowledge 형태로 skill을 추가할 수 있고, 이 skill은 MCP 서버나 REST API를 이용해 문서 검색을 하도록 돕는다.

운영 환경에서는 인증 방식을 분리한다. 문서를 읽는 API 키 또는 Application Default Credentials와 실제 클라우드 리소스를 변경하는 권한을 같은 자격 증명에 몰아넣지 않는다. 문서 조회는 넓게 허용하더라도, 배포·삭제·IAM 변경은 별도 승인 흐름으로 남겨야 한다.

Cursor, Claude Code, GitHub Copilot 같은 도구에서 MCP를 붙일 때도 원칙은 같다. 문서 검색 도구는 읽기 전용으로 두고, 쓰기 권한이 있는 도구와 분리한다. 에이전트가 실수로 문서 확인 중 리소스를 건드릴 이유가 없어야 한다.

4단계: 검색 패턴을 표준화한다

문서 검색도 품질 차이가 난다. “Firestore 안됨” 같은 질문보다 “Firestore transaction retry behavior Node.js SDK latest documentation”처럼 제품, 기능, SDK, 버전, 증상을 함께 넣는 편이 낫다.

에이전트에게는 다음 패턴을 권장한다. 먼저 searchDocumentChunks로 관련 문서 조각을 찾는다. 그 다음 필요한 문서만 documents.get 또는 BatchGetDocuments로 가져온다. 마지막으로 답변이나 코드 변경에 사용한 문서 링크와 핵심 문장을 남긴다.

이 순서를 지키면 토큰 낭비가 줄고, 긴 문서를 통째로 넣다가 중요한 부분을 놓치는 문제도 줄어든다. 특히 CI에서 자동 검토를 돌릴 때는 검색 결과 개수를 제한하고, 문서 전체 조회는 상위 후보에만 사용해야 비용과 시간이 안정된다.

5단계: PR 템플릿에 근거 문서 칸을 만든다

AI 도구가 문서를 확인해도 리뷰어가 볼 수 없으면 효과가 반감된다. PR 템플릿에 아래 항목을 추가해두면 좋다.

• 확인한 공식 문서 링크
• 문서 기준으로 적용한 제약 또는 옵션
• 프로젝트에 맞게 다르게 적용한 부분
• 문서에서 확인하지 못해 가정한 부분

이렇게 남기면 리뷰어는 모델의 긴 대화 기록을 열지 않아도 판단할 수 있다. 또한 몇 달 뒤 문서가 바뀌었을 때, 당시 변경이 어떤 기준으로 이뤄졌는지 확인할 수 있다.

6단계: 실패 로그 분석에도 붙인다

Developer Knowledge API는 새 코드 작성뿐 아니라 장애 대응에도 쓸 수 있다. gcloud CLI의 answer-query에 에러 로그를 넣으면 공식 문서 기반으로 문제 해결 힌트를 받을 수 있다. 예를 들어 배포 실패, BigQuery 권한 오류, Cloud Run 설정 문제, Firebase 인덱스 오류를 문서 기준으로 빠르게 좁힐 수 있다.

다만 자동 수정까지 바로 연결하지는 말아야 한다. 장애 상황에서는 로그, 현재 리소스 상태, 최근 배포, 권한 변경 이력이 함께 필요하다. 공식 문서 답변은 후보 원인을 좁히는 도구이고, 최종 조치는 운영자가 확인해야 한다.

도입 후 점검할 지표

효과를 보려면 감으로 평가하지 말고 숫자를 남겨야 한다.

• 문서 근거가 포함된 PR 비율
• Google Cloud/Firebase 관련 리뷰 코멘트 감소량
• 오래된 옵션 사용으로 인한 실패 건수
• 배포 실패 원인 파악까지 걸린 시간
• 에이전트가 문서 검색 후에도 잘못 적용한 사례

마지막 지표가 중요하다. 공식 문서를 읽었다고 항상 맞는 코드를 쓰는 것은 아니다. 문서 해석 오류, 프로젝트 버전 불일치, 권한 맥락 누락은 여전히 발생한다. 그래서 문서 검색은 리뷰를 대체하는 기능이 아니라 리뷰 품질을 높이는 입력이다.

실행 체크리스트

• Google 관련 변경 범주를 문서 확인 필수 대상으로 지정한다.
• 프로젝트 지침에 “공식 문서 확인 후 변경” 규칙을 넣는다.
• Developer Knowledge MCP 또는 agent skill을 읽기 전용으로 연결한다.
• 검색 → 문서 조회 → 근거 기록 순서를 표준화한다.
• PR 템플릿에 공식 문서 근거 칸을 추가한다.
• 장애 대응 로그 분석에도 사용하되, 자동 수정은 승인 뒤 실행한다.

AI 코딩 도구의 생산성은 모델 성능만으로 결정되지 않는다. 최신 공식 문서를 언제, 어떻게, 어떤 권한으로 읽게 할지가 운영 품질을 가른다. Developer Knowledge API는 그 빈틈을 메우는 꽤 실용적인 부품이다.