Insights
AI가 자동으로 큐레이션·번역·정리하는 기술 동향 피드입니다.
월간 보고서 작성 과정을 Claude Code의 '스킬' 기능으로 자동화한 사례를 공유합니다. 이 스킬은 BI 툴 쿼리 결과부터 위키 페이지 생성까지의 복잡하고 반복적인 절차를 에이전트가 안내, 검증, 초안 작성하는 방식으로 처리합니다. 수동 작업에 비해 보고서 작성 시간을 약 3시간에서 20분으로 크게 단축시켰습니다.
AI 자동 생성 콘텐츠
본 콘텐츠는 Qiita AI의 원문을 AI가 자동으로 요약·번역·분석한 것입니다. 원 저작권은 원저작자에게 있으며, 정확한 내용은 반드시 원문을 확인해 주세요.
원문 바로가기제품 KPI의 월간 보고서를 Claude Code 스킬로 만들었습니다. BI 툴의 쿼리 결과부터 위키에 매월 페이지를 만드는 과정입니다.
처음부터 스킬을 만든 것은 아닙니다.
처음 2번은 직접 수동으로 진행하여 과정을 익히고 어려움을 파악한 후에 스킬화했습니다. - 스킬에는 과정(절차)과 실제 데이터를 통해 발견한 어려움만 적었습니다. 지표의 정의나 판별 기준은 설계서가 원본이므로, 스킬에는 포함하지 않았습니다. - 본 데이터에 대한 쿼리는 사람이 실행하고, 에이전트는 과정 안내, 검증, 초안 작성까지를 담당합니다.
완성된 스킬을 다른 에이전트에게 공실행시켜 보니, 수작업 결과와 일치했습니다. 동시에,
**12가지의 모호함(ambiguity)**을 발견했습니다. - 보고서 작성이 수동으로 약 3시간 걸리던 것이, 스킬을 사용하니 약 20분으로 단축되었습니다.
정형화된 업무를 Claude Code 같은 AI 에이전트에게 맡기고 싶은 분
스킬(에이전트에게 전달할 절차서)을 어떻게 써야 무너지지 않을지 고민하는 분
본 데이터를 다루는 작업에서, 에이전트에게 어디까지 위임해야 할지 경계를 짓고 싶은 분
Claude Code (스킬 기능)
BI 툴: Metabase (저장된 쿼리)
Wiki: Confluence
지표의 정의는 Git 관리 설계서(Markdown)에 보관하고 있습니다.
월간 보고서에서는 이용 현황과 서비스 품질의 두 페이지를 매달 만듭니다.
이 보고서는 스프린트 리뷰에서 사용됩니다. 저희는 1주일 단위로 스프린트를 진행하며, 월 1회 스프린트 리뷰 때 팀원들과 PdM(제품 관리자), PD(제품 디자이너)가 이 보고서를 확인합니다. 이용 현황의 추이를 보고 다음 스프린트에서 개선할 기능을 결정하기 위함입니다. 값이 틀리면 어떤 기능을 개선해야 할지 판단 자체를 잘못 내리게 됩니다.
만드는 과정은 매달 동일합니다.
절차 자체는 단순합니다. 그럼에도 불구하고, 매번 어딘가에서 사소한 실수를 합니다. 바로 이런 작업이야말로 에이전트에게 맡기고 싶은 부분입니다.
하지만 처음부터 스킬을 작성하지 않았습니다.
1회차에서는 과정(절차)을 파악하고, 2회차에서는 어려움(함정)을 파악했기 때문입니다.
| 회차 | 진행한 것 | 알게 된 것 |
|---|---|---|
| 1회차 | 지표 설계서를 만들면서 수동으로 보고서 작성 | 절차의 골격. 어떤 쿼리를 실행하고, 어떤 값을 어디에 적을지 |
| ... |
1회차 때 스킬을 작성했다면, 아직 흔들리는 절차를 고정해 버렸을 것입니다. 2회차는 같은 절차를 따라가면서 '어디서 실수하는지'를 모으는 과정이었습니다.
2회차에서는 기간을 변수로 처리한 것도 효과적이었습니다. 변수는 3가지입니다: 당월 초일, 다음 달 초일, 추이의 기준점이 되는 전전월 초일. 이 덕분에 매달 쿼리 본문을 수정할 필요가 없어졌고, 스킬은 '변수에 무엇을 넣을지'만 보여주면 되었습니다.
실제 데이터를 기반으로 발견한 내용을 그대로 스킬에 적었습니다.
| 어려움(함정) | 발생한 일 |
|---|---|
| 변수 입력 오류 | 추이의 기준점으로 전전월이 아닌 당월 초일을 넣었다. 추이 표에서 전전월 행이 사라졌다 |
| ... |
이런 것들은 절차서를 책상 위에 놓고 생각할 때는 떠올릴 수 없습니다. 실제 데이터에 접한 횟수만큼만 어려움(함정)을 발견할 수 있습니다.
가장 중요하게 여긴 원칙은, 스킬에는 지표의 정의・표기・판별 기준을 적지 않는다는 것입니다. 이들은 설계서가 원본이며, 스킬은 설계서를 참조합니다.
만약 스킬에 정의를 포함하면, 설계서가 수정되었을 때 스킬이 구식이 됩니다. 원본이 두 개가 되면 어느 것이 맞는 것인지 알 수 없게 됩니다. 스킬이 가져야 할 것은 '어떻게 만들지'와 '어디서 실수하는지'뿐입니다.
저희 리포지토리에는 '스킬에는 실제 데이터로 검증한 절차만 적는다'는 규율도 있습니다. 추측으로 작성된 절차는 실제 데이터를 거쳐봐야 정확한지 알 수 없습니다.
스킬은 사용자가 명시적으로 호출했을 때만 작동하도록 했습니다. 에이전트가 대화 흐름 속에서 멋대로 시작하지 않도록 하기 위함입니다.
---
name: monthly-report
description: 제품 KPI의 월간 보고서를 BI 툴 결과로 위키에 작성하는 과정
...
절차는 7가지입니다. 각 절차에 완료 기준을 작성하고, 작업 시작 시 체크리스트를 응답에 복사하게 한 뒤, 완료할 때마다 지워나가게 합니다.
월간 보고서 작성:
- [ ] 1. 대상 월과 변수의 값을 제시하고, BI 도구에서 실행을 요청한다
- [ ] 2. CSV를 검증한다
...
완료 기준은 '무엇을 했는지'가 아니라 '무엇이 갖춰졌는지'로 작성합니다. 예를 들어 절차 1은 '모든 쿼리 분량의 CSV 경로를 받았다', 절차 6은 '사용자가 초안을 승인했다'입니다. 에이전트가 '아마 끝났다'고 다음 단계로 넘어가는 것을 막을 수 있습니다.
스킬의 정본(master copy)은 Claude Code의 설정 폴더가 아니라, APM (Agent Package Manager)의 .apm/skills/에 두고 있습니다. APM이 거기서 Claude Code용과 Codex용 스킬을 생성하기 때문에, 동일한 절차서를 어떤 에이전트에서도 사용할 수 있습니다. 절차나 함정을 수정할 때도, 정본의 한 곳만 고치면 됩니다.
APM으로 에이전트 설정을 통합 관리하는 방법은 다른 글인 'Claude Code와 Codex 설정 통일화 (SSOT)'에서 작성했습니다.
운영 데이터를 다루기 때문에, 맡기는 범위를 명확하게 정했습니다.
| 작업 | 담당 | 이유 |
|---|---|---|
| 운영 데이터 쿼리 실행 | 사람 | 운영 데이터에 에이전트를 직접 접촉시키지 않음 (에이전트가 받는 것은 마스킹된 환경의 집계값만) |
| ... | ||
| 에이전트가 받는 CSV에도 개인 정보는 포함되지 않습니다. 쿼리를 실행하는 BI 도구는, 운영 DB 복제본에서 개인 정보 열을 마스킹한 환경입니다. 성명이나 자유 기술 본문은 대체되고, 마스킹되지 않은 개인 정보가 발견된 표는 애초에 BI 도구에서 보이지 않게 됩니다. 게다가 쿼리는 건수나 회사 수 같은 집계값만 반환하도록 되어 있어, 개인을 특정할 수 있는 열은 출력하지 않습니다. |
스킬을 작성한 후, 다른 인스턴스의 에이전트로 실제 데이터에 대해 공 실행(dry run)을 시켰습니다. 페이지 생성만은 금지했습니다.
스킬을 작성한 에이전트는 스킬에 쓰여있지 않은 전제를 무의식적으로 보완합니다. 다른 에이전트는 쓰여진 것만 알게 됩니다. 절차서 리뷰를 새로 온 멤버에게 실제로 맡기는 것과 같은 발상입니다.
결과는 두 가지였습니다.
값・트렌드・판단은 수작업 결과와 일치했다. 스킬의 절차로 올바른 보고서를 만들 수 있음을 확인할 수 있었습니다 -
12가지 모호함이 발견되었다. 일치는 했지만, 해석이 갈릴 수 있는 부분이 남아있었습니다
발견된 모호함의 예시입니다.
12가지 모호함을 스킬에 반영한 후, 차분 리뷰를 2회 진행하여 지적이 없을 때까지 수정했습니다. 마지막에는 사람이 리뷰했고, 반올림 규칙은 스킬이 아닌 설계서 쪽으로 옮겼습니다. 반올림은 '어떻게 만들 것인가'가 아니라 '지표의 정의'에 속하기 때문입니다.
| 수작업 | 스킬 | |
|---|---|
| 1회 보고서 작성 소요 시간 | 약 3시간 | 약 20분 |
스킬의 약 20분에는, 사람이 운영 데이터 쿼리를 실행하는 시간이 포함됩니다.
화면과 API 지표는 측정 메커니즘을 막 도입했기 때문에, 아직 한 달 분량의 데이터가 모이지 않았습니다. 그래서 스킬에서는 '측정 전'이라고 표기하게 하고, 값을 추측으로 채우지 않도록 했습니다.
측정 메커니즘은 다른 글인 'New Relic의 Events to Metrics로 8일 만에 사라지는 이벤트에서 SLI를 13개월간 유지하는 방법'에서 작성했습니다. 측정 가능한 달이 오면, 운영 모니터링 기반으로 조회하는 것을 승인제로 절차에 추가할 예정입니다. 그때까지는 예상치 못한 상황을 만나면 작업을 멈추고 상담한다 구조로 만들었습니다.
사람이 실행하는 BI 도구의 쿼리도, MCP (Model Context Protocol)로 에이전트가 호출할 수 있는지 검토하고 있습니다. 그 경우에도, 마스킹된 환경에서 집계값만 반환하는 쿼리에 한해서, 실행 전에 사람이 승인하는 형태를 전제로 합니다.
<table><thead><tr><th>방침</th><th>이유</th></tr></thead><tbody><tr><td>두 번 실행해보고 스킬로 만들기</td><td>한 번 눈으로 확인하면 절차, 두 번째 눈으로 확인하면 함정(落とし穴)을 알 수 있습니다.</td></tr></tbody></table><p>가장 큰 배움은, **스킬은 작성하는 시점에서는 완성되어 있지 않다**는 것입니다. 실제 데이터로 실행해보고, 다른 시각으로 빈 실행(空実行)을 해보아야 비로소 모호함을 발견할 수 있었습니다. 절차서(手順書)를 사람에게 전달할 때와 해야 할 일 자체는 변하지 않습니다.</p>