Google Developer Knowledge API 공개: AI 코딩 도구가 공식 문서를 직접 읽는 방식

Google이 Developer Knowledge API 생태계를 공개했다. Google Cloud, Firebase, Android 등 개발자 문서를 AI 에이전트와 개발 도구가 구조적으로 검색하고 가져올 수 있게 만든 공식 API다. 기존처럼 웹 문서를 긁거나 모델의 학습 시점 지식에 기대는 대신, 최신 문서를 Markdown 형태로 검색하고 요약 근거로 쓸 수 있게 하는 방향이다.

이 발표가 중요한 이유는 간단하다. 코딩 에이전트의 많은 실수는 모델이 멍청해서가 아니라 문서가 오래됐거나, 검색 결과에서 잘못된 버전의 문서를 읽거나, 필요한 API 제약을 놓쳐서 생긴다. Google은 이 문제를 검색 API, gcloud 명령, MCP 서버, 에이전트 skill, 클라이언트 라이브러리로 한꺼번에 풀려 한다.

Developer Knowledge API가 해결하려는 문제

AI 코딩 도구는 프레임워크와 클라우드 서비스를 빠르게 다룰수록 더 자주 틀린다. Firebase 보안 규칙, BigQuery 권한, Android API, Google Cloud 배포 옵션은 몇 달 사이에도 바뀐다. LLM의 학습 데이터가 그 변화를 따라오지 못하면 존재하지 않는 옵션을 추천하거나, 폐기된 명령을 그대로 쓰거나, 권한 설정을 빠뜨린다.

기존 해결책은 웹 검색이나 문서 스크래핑이었다. 하지만 검색 결과는 광고, 블로그, 오래된 Stack Overflow 답변, 지역화된 문서가 섞인다. 스크래핑은 HTML 구조 변경에 약하고, 필요한 문서 조각만 가져오지 못하면 토큰도 낭비된다. Google은 공식 문서 자체를 프로그램이 읽기 좋은 검색·조회 인터페이스로 제공해 이 비용을 줄이려 한다.

Developer Knowledge API는 의미 검색과 키워드 검색, 문서 청크 검색, 문서 조회, 근거 기반 Q&A를 제공한다. 문서가 자주 색인되어 최신성을 유지하고, AI 도구가 필요한 조각을 먼저 찾은 뒤 전체 문서를 가져오는 식으로 컨텍스트를 아낄 수 있다.

gcloud에서 바로 쓰는 문서 검색

가장 단순한 진입점은 gcloud CLI다. Google Cloud SDK 환경이나 Cloud Shell에서 gcloud developer-knowledge answer-query로 질문에 대한 근거 기반 답을 받을 수 있다. documents search-chunks는 문서 조각을 찾고, documents describe는 특정 문서의 메타데이터와 내용을 가져온다.

예를 들어 BigQuery 데이터셋 생성 방법을 확인하거나, Firestore 트랜잭션 관련 문서를 찾거나, 에러 로그 파일을 그대로 쿼리에 넣어 문제 해결 힌트를 받을 수 있다. 중요한 점은 답이 일반 웹 검색 결과가 아니라 Google 개발자 문서에 근거한다는 것이다.

실무에서는 이 CLI가 온콜과 CI 로그 분석에 유용하다. 빌드 실패 로그를 붙여 넣고 최신 문서 기준으로 원인을 확인하거나, 배포 스크립트가 실패했을 때 해당 명령의 현재 옵션을 빠르게 찾아볼 수 있다. 물론 답을 맹신하면 안 되지만, 출처가 분명한 문서 검색 레이어가 하나 생기는 셈이다.

MCP와 에이전트 skill이 더 중요한 이유

Google은 단순 API뿐 아니라 에이전트 skill도 제공한다. npx skills add google/skills --skill retrieving-developer-knowledge 방식으로 프로젝트에 추가하면 AI 코딩 어시스턴트가 Developer Knowledge MCP 서버 또는 REST API를 이용하는 방법을 배운다. 호환 대상으로 Google Antigravity, Claude Code, Cursor, GitHub Copilot, 커스텀 에이전트 프레임워크가 언급됐다.

이 구조의 장점은 모델 프롬프트에 “최신 문서를 찾아봐”라고 막연히 쓰는 것보다 명확하다는 데 있다. skill은 먼저 문서 청크를 검색하고, 필요한 경우 전체 Markdown 페이지를 가져오며, 답변에는 공식 문서 근거를 붙이라는 사용 패턴을 제공한다.

개발팀 입장에서는 내부 AGENTS.md나 작업 가이드에 “Google Cloud 관련 변경은 Developer Knowledge API로 문서를 확인한 뒤 실행한다”는 규칙을 둘 수 있다. 특히 인프라 코드, IAM 권한, 과금에 영향을 주는 리소스 변경은 오래된 기억으로 작업하면 사고가 난다. 공식 문서 검색을 도구 체인에 넣는 편이 낫다.

프로덕션 시스템에 넣을 수 있는 클라이언트 라이브러리

Developer Knowledge API는 Python, Node.js와 TypeScript, Go, Java, C#, PHP, Ruby 클라이언트 라이브러리를 제공한다. 기능은 AnswerQuery, SearchDocumentChunks, GetDocument, BatchGetDocuments 중심이다. BatchGetDocuments는 한 번에 최대 20개 문서를 가져올 수 있어, 제품 내부 지식 봇이나 CI/CD 검증 도구에 넣기 좋다.

예를 들어 사내 배포 봇이 Terraform 변경을 검토할 때, 사용된 Google Cloud 리소스의 최신 제한과 권한 문서를 자동으로 가져와 체크리스트를 붙일 수 있다. 또는 고객 지원 봇이 Firebase 오류 메시지에 대해 답할 때, 해당 제품의 최신 릴리스 노트와 문서를 검색한 뒤 답하게 만들 수 있다.

다만 모든 Q&A를 이 API로 대체할 필요는 없다. 내부 운영 절차, 회사별 네이밍 규칙, 보안 승인 기준은 Google 문서에 없다. 공식 문서 검색은 외부 제품 지식의 신뢰도를 높이는 레이어이고, 내부 정책 검색과 결합해야 실제 운영에 맞는다.

개발팀이 적용할 때의 주의점

첫째, 검색 결과를 곧바로 코드 변경으로 연결하지 말아야 한다. 문서 조각은 근거지만, 프로젝트의 버전, 리전, 권한, 기존 설정과 맞는지 확인해야 한다. 둘째, API 키와 Application Default Credentials를 어떻게 관리할지 정해야 한다. 에이전트가 문서를 읽는 권한과 클라우드 리소스를 변경하는 권한은 분리하는 편이 안전하다.

셋째, 문서 확인 로그를 남기면 좋다. 어떤 변경에서 어떤 문서를 근거로 사용했는지 PR 설명이나 배포 기록에 남기면, 나중에 문서가 바뀌어도 판단 당시의 근거를 추적할 수 있다.

실행 체크리스트는 다음과 같다.

• Google Cloud, Firebase, Android 관련 자동화가 오래된 문서나 모델 지식에 의존하고 있는가?
• 코딩 에이전트가 공식 문서 검색 도구를 호출할 수 있는가?
• 문서 읽기 권한과 리소스 변경 권한이 분리되어 있는가?
• PR이나 배포 로그에 참고 문서 링크가 남는가?
• 내부 정책 문서와 Google 공식 문서를 함께 검색하는 구조인가?

이번 발표는 화려한 모델 성능 뉴스는 아니다. 하지만 AI 코딩 도구를 실무에 붙이는 팀에게는 더 실용적이다. 에이전트가 모르는 것을 그럴듯하게 말하는 문제를 줄이려면, 최신 공식 문서를 읽는 통로부터 만들어야 한다.