fe-common-rules/README.md

# fe-common-rules

팀 전체에서 공통으로 사용하는 **프론트엔드 Claude 지침 저장소**입니다.
각 프로젝트는 이 저장소를 **Git submodule**로 포함하고, `CLAUDE.md`의 `@import` 구문으로 공통 지침을 불러와 사용합니다.

---

## 📁 저장소 구조

```
fe-common-rules/
├── 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회)

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

```bash
# 원격 저장소 URL은 팀 내부 Git 주소로 교체하세요
git submodule add <fe-common-rules-repo-url> .claude/common
git submodule update --init --recursive
```

또는 이 저장소에 포함된 헬퍼 스크립트를 사용해도 됩니다.

```bash
curl -fsSL <install.sh raw URL> | bash
```

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

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

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

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

```markdown
# <프로젝트 이름>

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

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

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

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

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

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

업데이트 이후에는 submodule 포인터가 변경되므로 반드시 커밋합니다.

```bash
git add .claude/common
git commit -m "chore: update fe-common-rules submodule"
```

---

## 📝 프로젝트 지침 양식 사용

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

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

```bash
bash .claude/common/scripts/install.sh git@github.com:<org>/fe-common-rules.git
# → .claude/common 에 submodule 설치
# → templates/project/*.md 를 .claude/project/ 로 복사
# → templates/CLAUDE.md.tpl 을 루트 CLAUDE.md 로 복사
```

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

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

```bash
# 기본: 없는 파일만 복사 (기존 파일은 건너뜀)
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

```bash
# 모든 공통 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 을 공통 저장소에 추가

1. `skills/<skill-name>/SKILL.md` 를 작성 (YAML frontmatter 에 `name`, `description` 필수)
2. PR 을 올리고 팀 리뷰
3. 머지 후 각 프로젝트에서 아래 실행
   ```bash
   git submodule update --remote .claude/common
   bash .claude/common/scripts/link-skills.sh    # 새로 추가된 skill 이 자동 링크됨
   git add .gitmodules .claude
   git commit -m "chore: sync fe-common-rules"
   ```

---

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

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

수정 시 가이드

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

---

## 🧭 지침 우선순위

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

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

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

---

## 📦 샘플 프로젝트

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