Claude Code로 로깅 작업을 자동화하는 엑셀 문서 작성 가이드#

#이 글을 쓰게 된 배경

서비스를 운영하다 보면 "이 버튼을 얼마나 많은 사람이 눌렀을까?", "이 페이지에서 이탈이 왜 이렇게 많지?" 같은 질문이 생깁니다.
이를 답하기 위해 유저 이벤트 로깅이 필요하고, 보통 기획자나 데이터 분석가가 스펙을 정리해 개발자에게 전달하는 구조로 일이 진행됩니다.

문제는 이 과정에서 커뮤니케이션 비용이 발생한다는 점입니다.

"이 이벤트는 어느 시점에 발생해야 하나요?"
"파라미터 값은 어떤 형식으로 넘겨드리면 되나요?"
"이 화면이 어느 컴포넌트인지 모르겠어요."

Claude Code는 엑셀 파일을 직접 읽고 코드베이스를 분석하여 로깅 코드를 삽입하는 작업을 자동화할 수 있습니다.
단, 이것이 가능하려면 엑셀 문서를 Claude Code가 의도를 파악할 수 있을 만큼 구조화되어 있어야 합니다.

이 글은 그 방법을 기획자와 데이터 분석가의 관점에서 설명합니다.

#전체 흐름

기획자와 데이터 분석가가 엑셀을 잘 작성할수록, 개발자의 검토 시간이 줄고 빠르게 반영됩니다. 전달하고자 하는 바는 "문서를 잘 만들어야 우리가 잘 해드리죠..." 와 같은 어느쪽에도 도움되지 못할 푸념을 전달하는 것이 아닙니다.

AI를 잘 활용하기 위한 방법 중의 하나인 명료하고 구체적인 프롬프트 입력을 통해 업무 능률을 끌어올려보자는 것 입니다.

#엑셀 시트 구조

엑셀 파일은 하나의 시트로 구성하고, 아래 컬럼을 반드시 포함합니다.

컬럼명	필수 여부	설명
event_name	필수	GA4에 기록될 이벤트 이름 (영문 snake_case)
trigger	필수	어떤 유저 행동이 이 이벤트를 발생시키는가
screen	필수	어느 화면(페이지)에서 발생하는가
component	권장	어느 UI 요소에서 발생하는가 (버튼명, 카드명 등)
params	권장	함께 수집할 데이터 (key:value 형식)
memo	선택	추가 맥락 설명

#작성 예시

event_name	trigger	screen	component	params	memo
click_post	포스트 카드 클릭	전체 목록 페이지	포스트 카드	post_id:string, category:string	카테고리 필터 적용 여부와 무관하게 항상 수집
toggle_view_mode	보기 모드 변경 버튼 클릭	전체 목록 페이지	보기 모드 토글 버튼	mode:string (original|gallery|list)
page_view_post	포스트 상세 페이지 진입	포스트 상세 페이지	-	post_id:string, title:string

#트리거 조건 작성법

트리거는 Claude Code가 코드의 어느 위치에 로깅을 삽입할지 판단하는 핵심 정보입니다.
아래 기준으로 명확하게 작성해주세요.

#좋은 예 vs 나쁜 예

나쁜 예	좋은 예
사용자가 관심을 보일 때	포스트 카드를 클릭하는 순간
화면이 바뀔 때	포스트 상세 페이지 URL로 진입할 때
모달이 열릴 때	이미지 클릭 시 갤러리 모달이 열릴 때
뭔가 변경될 때	보기 모드 토글 버튼 클릭 시 (Original → Gallery)

#트리거 유형 참고표

유형	작성 예시
클릭	{요소명} 클릭 시
페이지 진입	{페이지명} 진입 시
노출	{요소명}이 화면에 노출될 때
제출	{폼명} 제출 버튼 클릭 시
스크롤	페이지를 {N}% 이상 스크롤했을 때

#파라미터 작성법

파라미터는 이벤트와 함께 수집할 추가 데이터입니다.
key:타입 형식으로 작성하고, 가능하면 예시 값도 함께 적어주세요.

#타입 종류

타입	설명	예시 값
string	문자열	"gallery", "fe"
number	숫자	1, 42
boolean	참/거짓	true, false

#작성 예시

값의 범위가 정해져 있다면 아래처럼 명시해주세요. Claude Code가 유효성 검증 코드도 함께 작성할 수 있습니다.

#screen 컬럼 작성법

개발자가 어느 파일을 수정해야 하는지 파악할 수 있도록, URL 경로나 페이지 이름을 명확하게 기재합니다.

나쁜 예	좋은 예
메인	홈 (/)
목록	포스트 목록 페이지 (/fe)
상세	포스트 상세 페이지 (/fe/{slug})

URL 경로를 모른다면, 실제 서비스에서 해당 화면의 브라우저 주소창 값을 그대로 적어주세요.

#전달 전 자가 체크리스트

엑셀을 개발자(또는 Claude Code)에게 전달하기 전에 아래 항목을 확인해주세요.

• event_name이 모두 영문 소문자와 언더스코어(_)로만 이루어져 있는가
• trigger가 "클릭", "진입", "노출" 등 명확한 유저 행동으로 기술되어 있는가
• screen에 URL 경로 또는 페이지 이름이 명시되어 있는가
• 수집이 필요한 데이터는 params에 모두 기재되어 있는가
• 중복된 event_name이 없는가
• 같은 이벤트가 발생하는 화면이 여러 개라면 행을 분리했는가

#Claude Code에 전달하는 방법

엑셀이 완성되면, Claude Code가 실행 중인 터미널에서 아래와 같이 요청합니다.

Claude Code는 엑셀을 파싱하고, 코드베이스에서 해당 화면과 컴포넌트를 찾아 로깅 코드를 자동으로 삽입합니다.
트리거 조건이 모호하거나 대상 컴포넌트를 특정하기 어려운 경우에는 확인을 요청할 수 있으며, 이 경우 추가 설명을 제공하면 됩니다.

#마치며

로깅 자동화의 품질은 엑셀 문서의 품질에 비례합니다.

기획자와 개발자가 같은 언어로 소통할 수 있는 구조화된 문서를 작성하는 것 자체가, 협업의 질을 높이는 첫 걸음입니다.