왜 Claude Code Skills의 설정을 프로젝트 외부에 두는가

이 기사는 playpark Blog에서 전재되었습니다.

Claude Code Skills는 반복적인 작업을 AI 워크플로우로 정의하는 메커니즘입니다. GA4 분석, SNS 게시글 생성, 기사 공개 플로우——각각을 Skill로 작성해 두면 어떤 프로젝트에서도 호출할 수 있습니다.

있어야 했습니다.

실제로는 스크립트 안에 프로젝트 고유값이 직접 작성(Hard-coded)되어 있습니다:

PROPERTY_ID="123456789" # 이 프로젝트의 GA4 ID
SITE="sc-domain:example.com" # 이 프로젝트의 GSC URL

두 번째 프로젝트에서도 동일한 스킬을 사용하려면 값을 수정하여 복사/붙여넣기 할 수밖에 없습니다. 그렇게 되면 동일한 스킬이 두 개로 분열되어, 한쪽만 버그 수정이 이루어지는 상황이 발생합니다.

"자동화 도구를 수동으로 이식한다"는 모순이 발생하고 있었습니다.

프로젝트 간에 설정을 구분하여 사용하는 방법은 몇 가지가 있습니다:

세 번째 방식을 체계화한 것이 skill-config.json에 의한 3층 컨피그 머지(3-layer config merge)입니다.

근본적인 질문은 "무엇이 변하고, 무엇이 변하지 않는가"의 구분입니다.

변하지 않는 것 (스킬 본체):

변하는 것 (프로젝트 고유값):

"변하는 것"만 외부에 빼두면, 스킬 본체는 한 번만 작성하면 됩니다.

외부로 뺀 설정을 어디에 둘 것인가에도 의도가 있습니다:

스킬 내장 기본값 ← 글로벌 설정 ← 프로젝트 설정
(최저 우선순위) (사용자 공통) (최우선 순위)

글로벌 설정은 "어느 프로젝트에서나 동일한 값"만을 둡니다. 타임존은 Asia/Tokyo, 게시 언어는 ja, SNS 게시 대상은 기본적으로 X와 LinkedIn입니다. 이것들을 프로젝트마다 다시 작성할 이유가 없습니다.

프로젝트 설정은 "이 프로젝트만의 값"만을 둡니다. GA4 프로퍼티 ID는 당연히 프로젝트마다 다릅니다.

source "$SKILLS_DIR/_lib/common.sh"
config=$(load_skill_config "ga-analyzer")
# 글로벌 + 프로젝트의 머지된 설정을 얻을 수 있음
...

내부에서는 jq의 * 연산자를 사용하여 딥 머지(Deep Merge)를 구현하고 있습니다:

echo "$global_cfg" | jq --argjson proj "$project_cfg" '. * $proj'

딥 머지(Deep Merge)를 선택한 이유는 중첩된 객체의 일부만을 덮어쓰기 위해서입니다. 섀로우 머지(Shallow Merge)를 사용하면 중첩된 객체 전체가 덮어씌워져, 글로벌 설정의 대부분이 사라지게 됩니다.

이 설계가 효과를 발휘하는 것은 "동일한 스킬을 여러 프로젝트에서 재사용하고 싶을 때"입니다.

스킬이 1~2개이고 프로젝트도 하나라면 직접 작성하는 것으로 충분합니다. 여러 프로젝트에 걸쳐 있고, 스킬이 늘어남에 따라 설정 관리 비용이 상승하는 단계에서 도입을 검토하는 것이 현실적입니다.

반대로, 이 설계를 도입해 두면 "새로운 스킬을 작성하는 심리적 장벽이 낮아지는" 이차적인 효과가 있습니다. 어떤 프로젝트에서도 동작한다는 것을 알고 있다면, 하나의 스킬을 작성하는 투자의 회수처가 늘어나기 때문입니다.

이 기사에서는 3층 설정 병합 (3-layer config merge)의 설계 의도를 해설했습니다.

:page_facing_up: :page_facing_up:

Skills를 「어떤 프로젝트에서도 동작하는」 포터블 자산으로 만드는 설계 에서는 추가로:

_lib/

공유 라이브러리를 통한 중복 코드 제로화 구현 상세 - 외부 스킬 (skills.sh 등)의 심볼릭 링크 (symlink) 통합과
.gitignore

자동 관리 - 구형 설정 파일을 일괄적으로 이전하지 않고도 계속 동작하게 만드는 레거시 폴백 (legacy fallback) 메커니즘

을 다루고 있습니다.

playpark LLC - 업무 자동화 · AI 활용 · Web 개발

Insights