gameservice-fe-agent/
├── CLAUDE.md                     # 공통 지침 엔트리 포인트 (rules/* 를 @import)
├── README.md                     # 이 파일
├── rules/
│   ├── coding-conventions.md     # 포맷팅, 네이밍, 타입
│   ├── framework-rules.md        # Vue/Nuxt/Tailwind/라이브러리 규칙
│   ├── commit-pr.md              # 커밋 & PR 규칙
│   └── claude-workflow.md        # Claude 작업 방식 지침
├── templates/
│   ├── CLAUDE.md.tpl             # 프로젝트 루트 CLAUDE.md 템플릿
│   └── project/                  # 프로젝트 지침 양식
│       ├── overview.md
│       ├── conventions.md
│       └── architecture.md
├── skills/                       # 팀 공용 Claude skill 모음
│   ├── README.md
│   ├── vue-component-review/
│   │   └── SKILL.md
│   └── conventional-commit/
│       └── SKILL.md
├── scripts/
│   ├── install.sh                # submodule 설치 + 템플릿 복사 + skill 링크
│   ├── init-project.sh           # .claude/project 양식만 다시 초기화/diff
│   ├── link-skills.sh            # 공통 skill 을 .claude/skills 로 링크/해제
│   └── update.sh                 # 최신 공통 지침으로 업데이트
└── examples/
    └── sample-nuxt-project/      # Nuxt4 + Vue3 + TS + Tailwind 샘플

🚀 프로젝트에 도입하기

1. Submodule 설치 (최초 1회)

프로젝트 루트에서 아래 명령을 실행합니다.

# 순서대로 입력

#1
git submodule add https://git.sginfra.net/sgp-web-d/gameservice-fe-agent.git .claude/common
#2
git submodule update --init --recursive
#3
bash .claude/common/scripts/install.sh https://git.sginfra.net/sgp-web-d/gameservice-fe-agent.git

설치 후 프로젝트 구조는 다음과 같이 됩니다.

your-project/
├── .claude/
│   ├── common/            ← submodule (gameservice-fe-agent)
│   └── project/           ← 프로젝트 고유 지침
├── CLAUDE.md              ← 공통 + 프로젝트 지침을 @import
└── ...

2. 프로젝트 `CLAUDE.md` 작성

프로젝트 루트의 CLAUDE.md에서 공통 지침과 프로젝트 지침을 함께 불러옵니다.

# <프로젝트 이름>

## 공통 지침
@.claude/common/CLAUDE.md

## 프로젝트 지침
@.claude/project/overview.md
@.claude/project/conventions.md

Claude Code는 @경로 구문을 만나면 해당 파일의 내용을 컨텍스트에 포함시킵니다. 공통 지침의 CLAUDE.md는 내부적으로 rules/*.md를 다시 @import하므로, 한 줄의 @.claude/common/CLAUDE.md만으로 모든 공통 지침이 로드됩니다.

3. 공통 지침 업데이트 받기

# 최신 master 브랜치의 공통 지침으로 업데이트
git submodule update --remote .claude/common

# 또는 헬퍼 스크립트
bash .claude/common/scripts/update.sh

📝 프로젝트 지침 양식 사용 (수동 파일 복사 or /script/init-project.sh 사용)

.claude/project/ 에 들어갈 지침은 공통 저장소의 templates/project/ 에 양식으로 관리됩니다. 팀원은 install.sh 를 사용하면 submodule 설치와 동시에 이 양식을 자동으로 복사받아 작성을 시작할 수 있습니다.

신규 프로젝트 — install.sh 한 번으로 끝

bash .claude/common/scripts/install.sh https://git.sginfra.net/sgp-web-d/gameservice-fe-agent.git
# → .claude/common 에 submodule 설치
# → templates/project/*.md 를 .claude/project/ 로 복사
# → templates/CLAUDE.md.tpl 을 루트 CLAUDE.md 로 복사

이미 submodule 이 있는 프로젝트 — init-project.sh

이미 공통 저장소를 submodule 로 연결해둔 프로젝트에서 .claude/project/ 양식만 따로 초기화하거나, 공통 저장소에 새 양식이 추가됐을 때 사용합니다.

# 기본: 없는 파일만 복사 (기존 파일은 건너뜀)
bash .claude/common/scripts/init-project.sh

# 기존 파일을 덮어쓰고 싶을 때
bash .claude/common/scripts/init-project.sh --force

# 차이만 확인하고 복사는 하지 않기
bash .claude/common/scripts/init-project.sh --diff

양식을 추가/수정하려면

공통 저장소의 templates/project/*.md 를 수정하는 PR 을 올립니다. 머지 후 팀원들은 git submodule update --remote 로 새 양식을 받은 뒤, 필요하면 init-project.sh --diff 로 자신의 프로젝트 지침과 비교할 수 있습니다.

🛠 공통 Skill 사용

Claude Code 는 프로젝트의 .claude/skills/<skill-name>/SKILL.md 를 자동으로 탐색합니다. 공통 저장소는 skills/ 폴더에 팀 공용 skill 들을 두고, 각 프로젝트는 심볼릭 링크로 이를 .claude/skills/ 에 연결합니다. 링크 방식이기 때문에 git submodule update 한 번으로 모든 프로젝트가 최신 skill 을 자동으로 사용하게 됩니다.

설치 (install.sh 사용 시 자동)

install.sh 는 submodule 추가, 템플릿 복사, 공통 skill 링크 까지 한 번에 처리합니다. 별도 조치가 필요하지 않습니다.

이미 설치된 프로젝트 — link-skills.sh

# 모든 공통 skill 을 .claude/skills/ 로 링크 (기존 링크는 건너뜀)
bash .claude/common/scripts/link-skills.sh

# 실제 링크 없이 어떤 작업이 일어날지 미리보기
bash .claude/common/scripts/link-skills.sh --dry-run

# 기존 링크/폴더를 덮어쓰기
bash .claude/common/scripts/link-skills.sh --force

# 특정 skill 하나만 링크
bash .claude/common/scripts/link-skills.sh vue-component-review

# 공통 skill 링크 전체 해제 (프로젝트 고유 skill 은 건드리지 않음)
bash .claude/common/scripts/link-skills.sh --unlink

프로젝트 고유 skill 과의 공존

.claude/skills/ 아래에는 공통 skill 링크와 프로젝트 자체 skill 폴더가 함께 있을 수 있습니다. link-skills.sh 는 심볼릭 링크(-L)인 항목만 관리하므로 프로젝트 고유 skill 은 덮어쓰지 않습니다.

.claude/skills/
├── vue-component-review     → 링크: ../common/skills/vue-component-review
├── conventional-commit      → 링크: ../common/skills/conventional-commit
└── my-project-only-skill/   ← 이 프로젝트만의 skill (실제 폴더)
    └── SKILL.md

새 skill 을 공통 저장소에 추가

skills/<skill-name>/SKILL.md 를 작성 (YAML frontmatter 에 name, description 필수)
PR 을 올리고 팀 리뷰

머지 후 각 프로젝트에서 아래 실행

git submodule update --remote .claude/common
bash .claude/common/scripts/link-skills.sh    # 새로 추가된 skill 이 자동 링크됨
git add .gitmodules .claude
git commit -m "chore: sync gameservice-fe-agent"

✍️ 공통 지침 수정 프로세스

이 저장소를 별도로 clone 합니다.
브랜치를 만들고 rules/*.md 혹은 CLAUDE.md를 수정합니다.
PR을 열고 팀 리뷰를 받습니다.
머지 후 각 프로젝트에서 git submodule update --remote 로 동기화합니다.

수정 시 가이드

기존 규칙을 바꿀 때는 이유를 PR 설명에 반드시 기록합니다.
특정 프로젝트에만 해당되는 내용은 공통 지침이 아닌 프로젝트 지침으로 분리합니다.
충돌 가능성이 있는 규칙은 기본값을 정하고, 프로젝트에서 오버라이드 가능하도록 문장을 구성합니다.

🧭 지침 우선순위

Claude가 동시에 여러 지침을 읽는 경우 다음 우선순위를 따릅니다.

프로젝트 지침 (.claude/project/*.md) — 최우선
공통 지침 (.claude/common/*.md) — 프로젝트와 충돌하지 않는 범위 내에서 적용
Claude의 일반 원칙

충돌이 발생하면 Claude는 프로젝트 지침을 따르되, 차이를 사용자에게 명시적으로 알려야 합니다.

📦 샘플 프로젝트

examples/sample-nuxt-project/ 폴더에 Nuxt4 + Vue3 + TypeScript + Tailwind CSS 기반의 샘플 구성이 들어 있습니다. 프로젝트에 이 저장소를 연결하는 실제 예시를 보려면 해당 폴더의 README.md를 참고하세요.

README.md

gameservice-fe-agent

📁 저장소 구조