127 lines
4.2 KiB
Markdown
127 lines
4.2 KiB
Markdown
# 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 작업 방식 지침
|
|
├── scripts/
|
|
│ ├── install.sh # 프로젝트에 submodule로 설치
|
|
│ └── 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"
|
|
```
|
|
|
|
---
|
|
|
|
## ✍️ 공통 지침 수정 프로세스
|
|
|
|
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`를 참고하세요.
|