[사내AX] 🪄 제각각인 상세페이지, 섹션별 자동화로 내 맘대로 수정하기 (feat. 클로드스킬)

🎯 한줄 요약

스터디마다 다른 상세페이지를 Claude Code로 자동 생성하는 시스템을 만들어서, 전체/섹션별/개별 수정을 자유롭게 할 수 있게 됐습니다.

👥 이런 분들께 도움돼요

• 여러 스터디/강의/이벤트 상세페이지를 관리하는 콘텐츠 운영자

• 통일된 템플릿을 만들고 싶은데 내용이 제각각이라 어려움을 겪는 분

• "이건 코드로, 이건 AI가 판단하게" 구분이 어려운 분

ALT

채팅 앱 - 한국어

결과 먼저 보기 - 18기, 19기 vs 20기 상세페이지

(많이 이뻐졌다.. 쿠쿠)

ALT

웹페이지에 있는 한국어 스크린샷

ALT

한국어 앱 스크린샷

ALT

한국 앱 스크린샷

ALT

한국어 텍스트가 있는 페이지의 스크린샷

ALT

버튼이 있는 한국어 페이지

😫 문제 상황 (Before)

1. 통일된 템플릿을 만들 수 없었다

스터디 상세페이지는 7개 섹션 구조가 정해져 있습니다:

• 히어로 (제목, 카테고리, 날짜 등) / 스터디 소개 / 이런 분께 추천해요 / 커리큘럼 /결과물 / 스터디장 소개 / 참여 전 확인

문제는 그 안의 내용이 스터디마다 전부 다르다는 거였습니다:

• 어떤 스터디는 이미지가 들어가고, 어떤 스터디는 링크가 들어감

• 결과물이 1개인 스터디도 있고 5개인 스터디도 있음

• 커리큘럼도 누구는 주차별 과제가 있고 누구는 없고

그래서 "이 위치에 이 값을 넣어라"라는 고정 템플릿으로는 해결이 안 됐습니다. AI가 동적으로 그때마다 데이터를 보고 판단해서 생성하는 과정이 중간에 필요했습니다.

2. n8n + AI API 조합의 한계

처음에는 n8n(노코드 자동화 툴)으로 해결하려고 했습니다.

문제 1: 필드 지정이 너무 번거로움 로직 만들 때마다 "이 테이블에서 이 필드를 가져와서 여기 넣어"를 n8n 노드에서 일일이 지정해줘야 했습니다. 필드가 추가되거나 바뀌면 또 노드를 수정해야 하고요.

문제 2: 한 섹션 틀리면 전체 재생성 AI API로 상세페이지 전체(7개 섹션)를 한 번에 생성하는 방식이라, 한 섹션만 잘못되어도 전체를 다시 돌려야 했습니다.

문제 3: 토큰 과다 소모로 인한 품질 저하 한 번 요청에 상세페이지 전체(7개 섹션) 데이터를 다 넣으니까 토큰이 엄청 소모됐습니다. 그러다 보니 AI가 제대로 처리를 안 하고 대충 넘어가는 경우가 많았어요. 섹션별로 쪼개면 그때그때 처리할 토큰이 줄어드는데, n8n에서는 그게 어려웠습니다. (뭐 단계별로 할 순 있었겠지만 한 땀 한 땀 한 노드 두 노드..)

문제 4: 지침을 무시함 "절대 기존 내용을 임의로 바꾸지 마"라고 AI 노드 지침에 넣어도 자꾸 원본 텍스트를 요약하거나 바꿔버렸습니다. 아마 하나의 엄청 긴 인스트럭션으로 모든 걸 관리해서 그랬던 것 같아요. 템플릿 지정, 각 섹션별 처리 방법, 주의사항까지 전부 한 곳에 넣으니까 AI가 다 기억 못 하고 일부를 무시해버렸습니다.

3. 디자인 개선이 어려웠다

n8n에서는 템플릿 HTML 코드를 한 번 주고 끝입니다. "이 부분 비율 좀 바꿔줘", "여기 디자인 좀 더 이쁘게 해줘" 같은 UX 관점에서 AI와 대화하며 점진적으로 개선하는 게 불가능했습니다.

결국 깨달았습니다. n8n으로는 "AI API를 호출해서 결과만 받는 것"밖에 못 한다는 걸요. 제가 필요한 건 AI 에이전트가 직접 보고 → 판단하고 → 계획하고 → 실행하고 → 고치는 것이었습니다.

⚙️ 이 시스템이 작동하는 방식

Claude Code 스킬이란?

Claude Code에서 스킬(Skill)은 /명령어로 실행할 수 있는 자동화된 작업 흐름입니다.

예를 들어 /detail-update Tx8BOzXYiCTtFar 이렇게 치면:

1. 스킬 파일(skill.md)에 정의된 순서대로

2. 코드 실행 → AI 판단 → 코드 실행이 자동으로 진행됩니다

실제 구조

프로젝트 폴더/
├── .claude/
│   └── commands/           ← 스킬 정의 폴더
│       ├── detail-update/
│       │   └── skill.md    ← 상세페이지 생성 스킬
│       └── update-hero/
│           └── skill.md    ← 히어로 섹션 업데이트 스킬
├── generate_html.py        ← 데이터 조회/저장 스크립트
├── update_hero.py          ← 히어로 업데이트 스크립트
├── studies-data.json       ← 스터디 기본정보 (변동 없는 데이터)
└── template-guide.md       ← 디자인/템플릿 가이드

스킬 파일(skill.md) 안에는 뭐가 있나?

스킬 파일에는 Claude Code가 따라야 할 실행 순서와 지침이 적혀 있어요:

# /detail-update 스킬

## 실행 순서
1. python3 generate_html.py --fetch <studyId> 실행
2. 출력된 데이터를 보고 HTML 생성 (template-guide.md 참고)
3. python3 generate_html.py --update <record_id> 실행

## 주의사항
- (필수) 태그가 붙은 항목은 절대 생략하지 마
- 레벨은 studies-data.json의 '구분' 값을 그대로 써

이렇게 해두면 Claude Code가 순서대로 실행하면서, 중간에 AI 판단이 필요한 부분만 직접 처리합니다.

왜 이렇게 나눠야 하나?

🛠️ 사용한 도구

• 도구명: Claude Code (VS Code Extension)

• 모델: Claude Opus 4.5

• 작업 기간: 3일 (2025.12.28 ~ 12.30)

🤝 AI와 협업한 과정

1. 첫 번째 깨달음: AI API 호출 ≠ AI 에이전트 실행

n8n으로 삽질하면서 깨달았습니다. AI API를 호출해서 결과만 받는 것과, AI 에이전트가 직접 보고 → 판단하고 → 계획하고 → 실행하고 → 고치는 것은 완전히 다르다는 걸요.

Claude Code는 후자였습니다. 그래서 선택했습니다.

2. 데이터 소스 정리: "헷갈리면 여기 봐"

에어테이블에 있는 값으로 상세페이지를 생성하고, 다시 게시판에서 스터디장이 수정한 최신 버전을 에어테이블에 저장하는 과정에서... Claude Code도 어떤 값을 봐야 하는지 헷갈려했습니다.

이렇게 해결했어요:

"요일, 카테고리, 스터디장 정보는 에어테이블에서 봐. 스터디 소개, 커리큘럼, 결과물은 베터모드에서 가져온 값으로 봐. 그리고 변동 없는 스터디 기본정보는 studies-data.json 파일에 저장해뒀으니까 헷갈리면 무조건 이 파일 봐."

각 필드를 어디서 봐야 하는지 미리 지정해주니까 헷갈림이 사라졌습니다.

3. 섹션별 수정을 위한 모드 분리

상황: 히어로 섹션만 수정하고 싶은데 전체 상세페이지를 다시 생성해야 했습니다.

이렇게 요청했어요:

"전체 상페를 다 다시 만드는 게 아니라 섹션별로 수정을 요청하고 싶어"

결과: Claude Code가 기존 스크립트에 --hero, --output 같은 모드를 추가해줬습니다.

이게 왜 좋았냐면:

• 히어로만 수정하고 싶은데 전체 다시 생성 안 해도 됨

• 문제 있는 섹션만 콕 집어서 고칠 수 있어서 디버깅이 쉬워짐

이때 처음 알았어요. 파이썬 파일 실행할 때 --fetch, --update 같은 파라미터를 붙이면 해당 기능만 실행하는 개념이 있다는 걸요.

4. 스킬로 "퐁당퐁당" 순서 정의하기

문제: 어떤 건 코드로 짜고 싶고, 어떤 건 Claude Code가 직접 보고 판단했으면 했는데... Claude Code는 "전부 스크립트로" 또는 "전부 직접 하기" 이렇게만 생각하는 것 같았습니다.

예를 들어 이런 순서가 필요했어요:

1. 데이터 조회 → 코드가

2. 내용 생성 → Claude Code가 직접

3. 베터모드/에어테이블 싱크 → 코드가

깨달음: 이 "퐁당퐁당" 순서 자체를 스킬로 만들어서 정의해야 했습니다.

여러 번 삽질 끝에 깨달았어요. 스킬은 단순히 기능을 재사용하는 게 아니라, "어떤 순서로 뭘 실행할지"를 정의하는 것이었습니다.

💡 배운 것: 코드 실행과 AI 판단을 섞고 싶으면, 그 "퐁당퐁당" 순서 자체를 스킬로 정의해야 한다. 스킬 = 실행 순서의 정의.

5. 막혔던 순간들과 해결

문제 1: 템플릿 개선을 요청했는데 1회성으로만 수정함

"이 부분 비율 바꿔줘", "여기 태그로 바꿔줘" 이렇게 요청하면 Claude Code가 세 가지 중 하나로 반응했어요:

1. 해당 HTML 파일만 직접 수정 → 다른 페이지 생성할 때 적용 안 됨

2. 그 부분만 바꾸는 별도 스크립트 파일을 생성 → 동일한 부분을 수정하는 코드가 여러 개 생겨서 나중에 뭘 실행해야 하는지 헷갈림

3. 템플릿 가이드에 반영 → 이게 정답!

해결:

"1회성 수정 말고 템플릿 가이드에 반영해줘. 다음에 다른 페이지 생성할 때도 적용되게."

문제 2: Claude Code가 값을 임의로 판단함

입문 레벨인 스터디를 중급으로 넣어버린 적이 있어요. Claude Code가 "이 정도 내용이면 중급인 것 같아서요"라고 했는데... 아니, 그건 니가 판단할 게 아니잖아!

해결:

"적절한 레벨을 판단하지 마. studies-data.json의 '구분' 값이 레벨이야. 그대로 써."

✨ 결과 (After)

Before vs After

얻은 것

• 수정의 자유도: 진짜 내 맘대로 수정할 수 있게 됨

• 구조 설계의 중요성: 삽질을 통해 "처음부터 설계해야 한다"는 깨달음

• 스킬 개념 이해: 코드 실행과 AI 판단을 섞으려면 그 순서를 스킬로 정의해야 함

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

핵심: 로직 vs AI 구분하고 스킬로 묶기

이번에 가장 크게 배운 건 "어떤 건 코드로, 어떤 건 AI가"를 미리 나누고, 그 순서를 스킬로 정의해야 한다는 거였어요.

1단계: 작업을 쪼개서 분류하기

ALT

한국어 HTML 페이지의 스크린샷

2단계: 실행 순서 정하기

예를 들어 상세페이지 생성은 이런 순서가 필요했어요:

1. 에어테이블에서 데이터 조회 → 코드

2. 데이터 보고 HTML 생성 → AI

3. 생성된 HTML을 에어테이블에 저장 → 코드

4. 베터모드에 업데이트 → 코드

5. 캐시 동기화 → 코드

3단계: 스킬로 묶기

이 순서를 스킬 파일(skill.md)에 정의해두면, /detail-update studyId 한 번으로 전체 프로세스가 실행됩니다.

# 스킬 실행 순서 예시
1. python3 generate_html.py --fetch <studyId>  ← 코드가 데이터 조회
2. Claude가 데이터 분석 후 HTML 생성           ← AI가 판단
3. python3 generate_html.py --update <record_id> ← 코드가 저장/싱크

왜 이렇게 나눠야 하나요?

• AI에게 전부 맡기면 토큰 소모가 심하고 실수가 많음

• 코드로만 하면 동적인 판단이 어려움

• 딱 AI가 필요한 부분만 AI에게 맡기면 효율적이고 정확함

기타 효과적이었던 것

1. 수정 단위를 미리 설계하고 스킬/모드를 나눠라

   • 전체 생성 / 섹션별 수정 / 일괄 업데이트 각각 분리

   • --fetch, --update, --hero 같은 모드 활용

2. AI가 헷갈려하면 데이터 소스를 명확히 지정해라

   • "이 정보는 에어테이블에서, 저 정보는 베터모드에서"

   • 헷갈릴 만한 건 JSON 파일로 저장해두고 "무조건 여기 봐"

3. 1회성 수정이 아니라 템플릿/지침에 반영되도록 요청해라

   • "이거 수정해줘" → "이거 수정하고 템플릿 가이드에도 반영해줘"

이렇게 하면 안 돼요

1. 구조 설계 없이 바로 "만들어줘" 하면 나중에 다 뜯어고쳐야 함

2. AI가 알아서 잘 하겠지 믿으면 레벨을 중급으로 바꿔버림

3. 한 번에 다 시키면 토큰 많이 쓰면서 대충 처리함

🚀 앞으로의 계획

당장 해결할 것

• D-day 카운트다운 로직 확인: 매일 트리거 되는 건지, 페이지 로딩될 때마다 계산하는 건지 명확히 파악 후 개선

고민 중인 것

• 팀 협업 환경 구축: 지금은 나만 쓰는데, 다른 팀원도 이 환경을 그대로 실행할 수 있게 하려면 어떻게 해야 할지 (매번 git push/pull? 다른 방법?)

📝 재사용 가능한 프롬프트

프롬프트 1: 데이터 소스 정리할 때

"[필드명]은 [소스1]에서, [필드명]은 [소스2]에서 가져와. 변동 없는 기본정보는 [파일명]에 저장해뒀으니까 헷갈리면 무조건 이 파일 봐."

프롬프트 2: 섹션별 수정 기능 만들 때

"전체를 다 다시 만드는 게 아니라 [섹션명]별로 수정을 요청하고 싶어. 모드를 나눠서 실행할 수 있게 해줘."

프롬프트 3: AI 임의 판단 막을 때

"[항목]을 적절히 판단하지 마. [파일명]의 [필드명] 값을 그대로 써."

프롬프트 4: 1회성 수정 방지

"이거 수정해주고, [템플릿/지침 파일명]에도 반영해서 다음에 생성할 때도 적용되게 해줘."