docs: GA4와 Clarity 방문 데이터를 UTM별로 조회하는 스크립트와 안내

[seungwonme]

무엇을

GA4와 Clarity 방문 데이터를 유입 경로(UTM)별로 조회하는 읽기 전용 스크립트와 그 안내를 추가합니다.

• scripts/analytics-report.sh ga [일수] [캠페인]: GA4, 기본 최근 7일
• scripts/analytics-report.sh clarity [일수]: Clarity, 최근 1~3일
• AGENTS.md "검색엔진과 방문 분석" 아래 "방문 데이터 조회" 절: 인증 방식, 호출 한도, 반영 지연, 권한 회수 방법

왜

• 공유 글에 UTM을 붙였지만 조회 방법이 한 세션의 대화에만 남아 있었습니다.
• 맥락 없는 새 에이전트에게 "GA랑 Clarity 봐 줘"를 시켰더니 GA 속성 번호를 찾지 못했고, 서비스 계정 토큰 발급은 안전 검사에 막혔습니다.

검증

• 스크립트 직접 실행: ga 7, ga 7 autorag-agent-intro(캠페인 필터), 없는 서비스 계정(오류 문구와 exit 1), clarity 1, 잘못된 인자(사용법을 stderr로 출력하고 exit 1)
• 환경변수를 비운 셸에서도 두 서비스 모두 HTTP 200
• 이 브랜치를 커밋한 뒤 맥락 없는 새 에이전트 두 개에 요청만 주고 확인했습니다. 두 에이전트 모두 이 절을 찾아 스크립트를 실행했고, 안전 검사에 막히지 않았습니다.
• 사이트 빌드에는 영향이 없습니다. AGENTS.md와 scripts/만 바꿨습니다.

인증 구조

• GA4: 키 파일 없이 GCP 프로젝트 nomadamas-analytics의 서비스 계정 ga-reader를 가장합니다. 이 서비스 계정은 GA4 속성의 뷰어이고, 토큰 발급 권한은 조직 공용 계정에만 있습니다. 스크립트는 gcloud auth list에서 권한이 있는 계정을 찾아 씁니다.
• Clarity: CLARITY_API_TOKEN 환경변수를 쓰고, 없으면 agents-env에서 꺼냅니다. 토큰은 출력하지 않습니다.

리뷰 포인트

• 공개 저장소라서 GA4 속성 번호, GCP 프로젝트 이름, 서비스 계정 이름이 공개됩니다. 셋 다 비밀값이 아니고 키 파일도 없어서 이것만으로는 데이터를 읽을 수 없습니다. 로그인 계정 이메일은 적지 않았습니다.