Claude Code에게 Google Workspace 열쇠 넘겨주기 — AI 비서 만든 후기

📝 한줄 요약

Claude Code가 내 Google 캘린더·메일·드라이브·문서를 직접 다룰 수 있도록 OAuth부터 슬래시 커맨드까지 한 번에 셋업해서, 자연어 한 줄로 "오늘 일기에 첨부된 doc 있나?"까지 묻는 AI 비서를 1시간 만에 완성했습니다.

바쁘시면 이것만 읽어도 돼요:

• 사용한 도구: Claude Code (Opus 4.7, 1M context) + Google Workspace CLI(gws) + 자동 스킬 설치

• 한 번의 설치 명령으로 /gws-calendar, /gws-gmail, /gws-docs 등 30+ 슬래시 커맨드가 한꺼번에 활성화됨

• 가장 깜짝 놀란 순간: "오늘 일기에 doc 있지않나?" 한 마디로 캘린더 이벤트의 첨부 Google Docs까지 자동 추적

• 가장 헤맨 부분: gws auth setup이 OAuth 클라이언트 ID까지는 자동으로 안 만들어줘서 GCP Console에서 수동 발급 필요

• 작업이 끝나고 같은 AI가 본 세션의 대화 로그를 파싱해서 개발 로그(DEVLOG)와 Google Docs까지 자동 생성

• 교훈: 환경 셋업 시 "사전 함정 미리 알려줘"라고 먼저 물어보면 우회로가 줄어든다

🎯 이런 분들께 도움돼요

• AI 어시스턴트를 본격적으로 업무에 활용하고 싶은 비개발자/PM/기획자

• 매일 캘린더·메일·문서를 손으로 일일이 클릭해서 관리하는 반복 작업에 지친 직장인

• Claude Code를 이미 쓰고 있는데 Google Workspace 자동화까지 확장해보고 싶은 개발자

😫 문제 상황 (Before)

매일 아침 비슷한 루틴이 반복됐습니다. 캘린더 열어서 일정 확인하고, 일기 캘린더에 첨부된 일지 문서 열어서 어제 무슨 생각을 적었나 보고, 가계부 캘린더에 들어가서 지출 기록 점검하고… 창 4~5개를 띄워가며 클릭으로 옮겨다니는 일. 별로 어려운 일은 아닌데 매일 반복되니 누적 시간이 만만치 않았습니다.

특히 답답했던 건, Claude 같은 AI 어시스턴트는 옆에 띄워두고도 정작 내 데이터에는 접근을 못 한다는 점이었어요. "오늘 일정 알려줘"라고 묻고 싶어도 캘린더를 직접 못 보니 의미가 없죠.

알아보니 Claude Code 같은 AI 도구가 Google Workspace를 직접 다루려면 명령줄 도구(CLI) + OAuth 인증이 필요했습니다. 그동안 GCP/OAuth 설정이 복잡해 보여서 미뤘는데, "AI랑 같이 하면 한 번에 끝낼 수 있겠다" 싶어서 새벽에 작정하고 앉았습니다.

🛠️ 사용한 도구

• AI 도구: Claude Code (Opus 4.7, 1M context window)

• 명령줄 도구: gws (Google Workspace CLI), gcloud SDK

• 인증: Google OAuth 2.0 (Desktop app, testing mode)

• 자동화 결과물: 30+ 슬래시 커맨드(/gws-calendar, /gws-gmail, /gws-docs 등) + DEVLOG.md + 동기화된 Google Docs

🔧 작업 과정

1. 일단 셋업부터 — "gws 설치 좀 해줘"

새벽 2시 13분, 첫 메시지부터 추상적이었습니다. 공식 저장소 링크 하나만 던졌어요.

https://github.com/googleworkspace/cli 을 참고해서 gws 설치좀

Claude는 알아서 공식 README를 읽고 Homebrew tap을 등록한 다음 brew install로 gws 0.22.5를 깔았습니다. 그러더니 묻지도 않은 후속 단계까지 안내하더군요. "인증을 하려면 gcloud SDK도 필요한데, 깔까요?" 같은 식으로요. 다음에 뭐가 필요한지 미리 짚어주는 것 자체가 비개발자 입장에선 든든했습니다.

곧바로 gcloud SDK도 설치했고, 이쯤 되니 슬슬 인증 단계에 들어갈 차례였습니다.

2. 첫 번째 막힘 — 대화형 명령어는 어떻게 같이 하지?

gcloud auth login을 입력했는데 Claude가 의외의 대답을 했습니다.

gcloud auth login

"이 명령은 브라우저가 열리는 대화형 명령이라 백그라운드 실행 시 응답을 못 받아요. 메시지 창에 ! prefix를 붙여서 직접 실행해주세요."

처음엔 그게 뭔 소린가 싶었는데, ! gcloud auth login이라고 치면 그 명령이 세션 터미널에서 직접 실행되어 결과가 자동으로 Claude에게 전달되는 구조였습니다. 덕분에 브라우저로 로그인 → 결과 자동 인식 → 다음 단계 진행이 매끄럽게 이어졌습니다. 이건 진짜 알아두면 두고두고 쓸 팁이라고 느꼈어요.

3. 진짜 막혔던 곳 — OAuth 클라이언트는 수동으로 만들어야 한다고?

여기서 한참 헤맸습니다. gws auth setup을 돌리면 GCP 프로젝트 만들고, API 활성화하고, OAuth 클라이언트까지 한 번에 만들어줄 줄 알았는데 — OAuth 클라이언트 ID 발급만큼은 자동화가 안 되더라구요.

Claude는 이 사실을 진단하자마자 "수동으로 해야 하는 단계가 있어요" 하고 정리해줬습니다.

1. GCP Console에서 OAuth consent screen 구성 (External, testing mode)

2. Test users에 본인 계정을 반드시 추가 — 안 그러면 "Access blocked" 에러

3. OAuth Client ID 생성할 때 Application type을 Desktop app으로 선택

4. 다운로드한 JSON을 ~/.config/gws/client_secret.json으로 이동

5. @gmail.com 계정은 unverified app이라 스코프 25개 제한이 있으니 필요한 것만 골라서 요청할 것

이 중에 2번(Test users)이랑 5번(스코프 제한)은 모르고 지나치면 한참 뒤에 에러로 만나는 함정이에요. Claude가 작업 시작 전에 이걸 미리 짚어줘서 우회로를 안 만들고 한 방에 통과했습니다.

다운로드받은 JSON 파일을 정해진 위치로 옮기는 것까지 끝내고, 드디어 OAuth 로그인 차례.

! gws auth login -s drive,gmail,sheets,calendar

4. "진행상태 어떻게 되니" — 백그라운드 진단

여기서 또 한 번의 헤맴이 있었습니다. OAuth 로그인 명령은 백그라운드로 돌면서 브라우저 콜백을 기다리는데, 제 브라우저가 자동으로 안 열렸어요. 그것도 모르고 30분 가까이 멍하니 있다가 물었습니다.

진행상태 어떻게 되니

Claude의 진단이 인상적이었습니다. 단순히 "기다리세요"가 아니라:

• "OAuth 프로세스 PID는 살아있고, localhost:58955 포트도 LISTEN 상태"

• "출력은 URL 안내 이후 변동 없음 = 브라우저에서 인증 완료 안 됨"

• "브라우저가 자동으로 안 열린 것 같으니 이 URL을 직접 여세요"

상태를 진단하는 게 사람보다 정확했어요. URL 누르고 동의 한 번 하니까 끝. drive/sheets/gmail.modify/calendar 4개 스코프가 한 번에 인증됐고, 자격증명은 OS keyring 기반으로 암호화되어 안전하게 저장됐다는 친절한 안내까지.

이후 docs 스코프만 추가로 한 번 더 로그인해서 인증 단계는 모두 마무리.

5. 진짜 임팩트가 터진 순간 — 스킬 한 번 깔았더니 30+ 커맨드

여기까지는 준비 단계였습니다. 진짜 임팩트는 다음 명령 한 줄.

npx --yes skills add https://github.com/googleworkspace/cli

이거 한 번 돌리니까 Claude Code의 슬래시 커맨드 목록에 /gws-calendar, /gws-gmail, /gws-drive, /gws-docs, /gws-sheets, /gws-tasks, /gws-meet, /gws-chat, /gws-classroom, /gws-forms, /gws-keep… 수십 개가 한꺼번에 활성화됐습니다.

이 순간이 진짜 "오!" 했던 부분이에요. 평소 같으면 각 서비스마다 따로 가이드 읽고 따로 셋업했을 텐데, 공식 CLI 하나 깔고 스킬 한 번 등록하면 끝나는 거였습니다.

6. 첫 사용 — 자연어 한 마디가 캘린더와 Drive를 잇다

기능 확인 차 /gws-calendar를 호출해서 오늘 일정을 봤습니다. 새벽 시간이라 일정은 단출했어요. 그러다 일기 캘린더에 "일기"라는 이벤트가 보이길래, 무심코 물었습니다.

오늘 일기에 포함된 doc 있지않나

Claude는 (제가 아무런 추가 안내를 안 했는데도):

1. 캘린더 목록을 조회해서 "모든 기록(일기,일지,느낀점)" 캘린더의 ID를 알아냈고

2. 그 캘린더에서 오늘의 일기 이벤트만 골라서 상세 조회를 했고

3. 이벤트에 첨부된 Google Docs 2026-일지를 찾아서 링크까지 안내

매일 들어가던 일기 문서를, 자연어 한 마디로 캘린더 이벤트를 거쳐 자동으로 찾아준 거예요. 이게 평소 같으면 캘린더 클릭 → 이벤트 클릭 → 첨부 클릭 3번이 필요했던 경로인데, 한 문장으로 처리됐습니다.

7. 작업 기록까지 자동 — AI가 자기 작업을 회고록으로 정리

작업이 어느 정도 끝나갈 때쯤 /write-post라는 스킬을 돌렸습니다. 이게 기능이 좀 재밌어요. 오늘 세션의 모든 대화 로그를 자동으로 파싱해서 날짜별·작업별로 정리된 개발 로그(DEVLOG.md)를 만들어줍니다. 제가 어떤 메시지를 보냈고 Claude가 뭘 했는지가 시간순으로 깔끔하게 정리됐어요.

그 다음 /gws-docs로 "오늘 날짜로 문서 생성해서 DEVLOG.md 파일 저장해줘"라고 요청. 이번엔 방금 셋업한 환경을 진짜로 써본 거죠. 빈 Google Docs 문서가 만들어지고, DEVLOG 내용이 통째로 업로드됐습니다.

마지막 단계가 좀 재귀적이에요. /write-post를 한 번 더 돌리면서 "오늘 작업 내용 업데이트해줘"라고 요청했는데, AI가 이 마지막 요청까지 포함해서 DEVLOG에 자기 자신의 작업을 기록했습니다. 그리고 같은 내용을 Google Docs에 동기화. 작업하면서 자기 자신을 회고하는 AI라니, 좀 묘했어요.

✅ 결과 (After)

Before vs After

결과물

• ~/.config/gws/: OAuth 자격증명이 OS keyring 키로 AES-256-GCM 암호화된 상태로 안전하게 저장

• 30+ 슬래시 커맨드: /gws-calendar, /gws-gmail, /gws-drive, /gws-docs, /gws-sheets, /gws-tasks, /gws-meet, /gws-chat, /gws-classroom 등

• DEVLOG.md: 본 세션의 모든 대화가 시간순으로 자동 정리된 개발 로그

• Google Docs "gpters_project 개발 로그 - 2026-05-21": 같은 내용이 웹에서도 열람 가능

💬 이 과정에서 배운 AI 활용 팁

효과적이었던 것

1. 사전 함정 미리 물어보기: AI에게 환경 셋업을 시킬 때 "잘 하는 실수나 함정이 뭐가 있는지 알려줘"라고 먼저 물어보면, OAuth Test users 누락처럼 모르고 지나치면 한참 뒤에 만나는 문제들을 미리 짚어줍니다.

2. CLI + 슬래시 스킬 조합: 공식 CLI(gws) + 관련 스킬 자동 설치(npx skills add) 조합이 세팅 시간을 30분 안쪽으로 줄여줍니다. 따로따로 깔지 마세요.

3. 대화형 명령은 ! prefix: gcloud auth login 같은 브라우저 콜백이 필요한 명령은 메시지 창에 ! prefix로 입력하면, 세션 터미널에서 직접 실행되면서 결과가 AI에게도 자동으로 전달됩니다.

4. 백그라운드 진행 상태는 그냥 물어보기: "진행상태 어떻게 되니" 한 줄에 PID·포트·로그까지 진단해줍니다. 무작정 기다리지 마세요.

5. 작업 기록 자동화는 첫날부터: 세션 기록 자동 파싱(/write-post 같은 스킬)을 첫날부터 설정해두면, 나중에 사례글이나 회고를 쓸 때 원본 데이터가 통째로 남아있어서 진짜 편합니다.

이렇게 하면 안 돼요

1. OAuth 클라이언트 자동 발급을 기대하지 말 것 — gws auth setup 같은 도구가 GCP Console의 OAuth 클라이언트 ID까지 자동으로 만들어주지는 않습니다. Console에서 수동으로 발급받아야 해요.

2. OAuth Test users 깜빡하지 말 것 — @gmail.com 개인 계정으로 testing mode를 쓰면 본인을 Test users에 직접 추가해야 합니다. 안 그러면 OAuth 흐름이 "Access blocked"로 끊깁니다.

3. 스코프 25개 제한 주의 — unverified app(@gmail.com)은 한 번에 요청 가능한 스코프가 25개로 제한됩니다. "recommended" 전체를 한 번에 요청하면 실패해요. 필요한 것만 골라서 요청.

4. OAuth 로그인이 멈춰 보일 때 그냥 기다리지 말 것 — 브라우저가 자동으로 안 열리는 경우가 많습니다. 출력에 적힌 URL을 직접 여세요.

🌍 다른 업무에 적용한다면?

이번 셋업의 진짜 가치는 재사용 가능한 인프라라는 점입니다. 한 번 깔린 gws + 스킬 조합은 앞으로 모든 Workspace 자동화의 기반이 돼요. 예를 들면:

• 회의 준비 자동화: "다음 회의 30분 전에 참석자 리스트랑 관련 문서 미리 정리해줘" 같은 워크플로우

• 메일 트리아주: "오늘 받은 메일 중에 답장 필요한 것만 골라줘"

• 지출 트래킹: 캘린더의 지출 기록 이벤트를 Sheets로 자동 추출해서 월별 소비 패턴 분석

• 회사 위키 동기화: 회의록 → Google Docs → Drive 폴더 자동 분류

OAuth/CLI 한 번만 제대로 세팅해두면, 이런 시나리오들이 전부 자연어 한 줄짜리 요청으로 가능해집니다.

🚀 앞으로의 계획

1. 일기 자동 요약·회고: 매일 쓰는 일기 Google Docs를 AI가 자동으로 읽고 주간/월간 회고 리포트를 만들도록

2. 지출 데이터 자동 분석: 캘린더의 지출 기록 이벤트를 Sheets로 추출해서 월별 소비 패턴을 시각화

3. 캘린더+메일 통합 액션: "이번 주 회의 최종 장소 확정하고 참석자에게 메일 보내줘" 같은 멀티 서비스 워크플로우 구축

📋 재사용 가능한 프롬프트

프롬프트 1: 환경 셋업 사전 함정 점검

[설치하려는 도구나 서비스]를 셋업하려고 해. 진행하기 전에, 처음 하는 사람이 자주 빠지는 함정이나 미리 알아야 할 제약(권한, 인증, 호환성, 무료 한도 등)이 뭐가 있는지 먼저 정리해줘. 우회로를 만들어가며 진행하지 않게.

프롬프트 2: 대화형 명령 실행 안내 요청

지금부터 실행할 명령 중에 브라우저 콜백이나 사용자 입력이 필요한 대화형 명령이 있는지 미리 알려줘. 있으면 ! prefix로 어떻게 실행하면 되는지, 그리고 실행 후 어떤 결과를 너에게 알려주면 되는지 설명해줘.

프롬프트 3: 백그라운드 작업 진행 상태 확인

[명령어 이름]이 백그라운드로 돌고 있는 것 같은데 진행상태 어떻게 되니. 단순히 "기다려 보세요"가 아니라 PID·포트·로그까지 확인해서 지금 정확히 뭐 때문에 막혀 있는지 알려줘.

프롬프트 4: 작업 자동 기록 + 외부 동기화

[프로젝트 경로]에서 진행한 오늘 세션 작업을 정리해서 DEVLOG로 만들고, 같은 내용을 Google Docs [문서 제목 또는 ID]에 업로드해줘. 사용자 요청은 코드블록, AI 작업은 불릿으로.