commit 2def6f705dff3c9bd71795a7c3bd4d2c0a8cb529 Author: hyeonggil <> Date: Sat Apr 11 19:27:29 2026 +0900 Initialize fe-common-rules repository with common Claude guidelines and scripts for frontend projects diff --git a/CLAUDE.md b/CLAUDE.md new file mode 100644 index 0000000..367eab4 --- /dev/null +++ b/CLAUDE.md @@ -0,0 +1,33 @@ +# 팀 공통 Claude 지침 (fe-common-rules) + +이 파일은 팀 전체에서 공통으로 사용하는 Claude 작업 지침의 **엔트리 포인트**입니다. +각 프로젝트의 `CLAUDE.md`에서 `@.claude/common/CLAUDE.md` 형태로 참조하여 사용합니다. + +## 적용 범위 + +- 팀 내 모든 프론트엔드 프로젝트 +- Claude Code / Claude 기반 자동화 작업 전반 + +## 포함된 지침 + +아래 문서들은 Claude가 이 파일을 읽을 때 자동으로 함께 로드됩니다. + +@rules/coding-conventions.md + +@rules/framework-rules.md + +@rules/commit-pr.md + +@rules/claude-workflow.md + +## 우선순위 + +1. 프로젝트 `CLAUDE.md`에 명시된 **프로젝트 지침**이 최우선입니다. +2. 이 공통 지침은 프로젝트 지침과 충돌하지 않는 범위 내에서 항상 적용됩니다. +3. 충돌이 발생하면 프로젝트 지침을 따르되, 차이를 사용자에게 알려주세요. + +## 업데이트 + +- 공통 지침은 이 레파지토리(`fe-common-rules`)에서만 수정합니다. +- 각 프로젝트는 `scripts/update-common.sh`(또는 `git submodule update --remote`)로 최신 버전을 받아갑니다. +- 수정 제안은 PR로 받습니다. 자세한 내용은 루트 `README.md` 참고. diff --git a/README.md b/README.md new file mode 100644 index 0000000..41034bb --- /dev/null +++ b/README.md @@ -0,0 +1,126 @@ +# 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 .claude/common +git submodule update --init --recursive +``` + +또는 이 저장소에 포함된 헬퍼 스크립트를 사용해도 됩니다. + +```bash +curl -fsSL | 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`를 참고하세요. diff --git a/rules/claude-workflow.md b/rules/claude-workflow.md new file mode 100644 index 0000000..680a759 --- /dev/null +++ b/rules/claude-workflow.md @@ -0,0 +1,62 @@ +# Claude 작업 방식 지침 + +이 문서는 Claude가 팀 프로젝트에서 작업할 때 따라야 할 일반적인 원칙을 정의합니다. + +## 기본 원칙 + +1. **기존 코드 존중**: 수정 전에 관련 파일과 주변 컨벤션을 먼저 파악합니다. +2. **최소 변경**: 요구사항을 충족하는 최소한의 변경만 수행합니다. 관련 없는 리팩토링은 별도 작업으로 분리합니다. +3. **가정 대신 질문**: 요구사항이 모호하면 추측하지 말고 사용자에게 확인합니다. +4. **근거 있는 수정**: 코드 변경의 이유를 설명할 수 있어야 합니다. + +## 작업 순서 + +1. **탐색 (Explore)** + - 관련 파일을 먼저 읽고 프로젝트 구조를 파악합니다. + - 유사한 패턴이 이미 존재하는지 확인합니다. + +2. **계획 (Plan)** + - 여러 파일을 수정하거나 복잡한 작업이면 할 일 목록을 만들어 공유합니다. + - 아키텍처에 영향을 주는 변경은 착수 전에 사용자 승인을 받습니다. + +3. **구현 (Implement)** + - 한 번에 하나의 논리적 변경에 집중합니다. + - 공통 지침과 프로젝트 지침을 모두 준수합니다. + +4. **검증 (Verify)** + - 린트 / 타입체크 / 빌드가 깨지지 않는지 확인합니다. + - 테스트가 있는 프로젝트라면 관련 테스트를 실행합니다. + - 수동 검증이 필요한 경우 확인 방법을 사용자에게 안내합니다. + +## 해서는 안 되는 것 + +- **임의 기능 추가 금지**: 사용자가 요청하지 않은 기능을 추가하지 않습니다. +- **기존 코드 대량 리팩토링 금지**: 요청 범위를 벗어나는 변경은 하지 않습니다. +- **주석 / 문서 임의 삭제 금지**: 불필요해 보여도 삭제 전 사용자에게 확인합니다. +- **비밀정보 출력 금지**: 환경변수, 키, 토큰 등은 코드에 하드코딩하지 않습니다. +- **의존성 버전 임의 변경 금지**: 요청이 없다면 `package.json`의 버전을 변경하지 않습니다. +- **강제 푸시 / 히스토리 재작성 금지**: `push --force`, `reset --hard` 등은 사용자의 명시적 요청 없이 실행하지 않습니다. + +## 커뮤니케이션 + +- 답변은 간결하게, 결론을 먼저 말합니다. +- 코드를 수정했다면 **어떤 파일을 어떻게 바꿨는지** 요약합니다. +- 불확실한 부분은 솔직하게 밝히고 대안을 제시합니다. +- 긴 설명보다 실제 결과물(코드/파일)을 우선합니다. + +## 파일 작업 원칙 + +- 새 파일 생성보다 **기존 파일 수정**을 우선합니다. +- README, 문서는 사용자가 명시적으로 요청했을 때만 생성합니다. +- 파일을 읽지 않고 수정하지 않습니다. +- 대량 변경 시에는 diff를 확인할 수 있도록 단계별로 진행합니다. + +## 질문이 필요한 상황 + +다음의 경우 반드시 사용자에게 확인을 요청합니다. + +- 요구사항의 일부가 불명확할 때 +- 여러 구현 방식이 있고 각각 장단점이 뚜렷할 때 +- 공통 지침과 프로젝트 지침이 충돌할 때 +- 파괴적 작업(파일 삭제, 데이터 마이그레이션, 스키마 변경 등)이 필요할 때 +- 외부 서비스 호출이나 결제 관련 작업일 때 diff --git a/rules/coding-conventions.md b/rules/coding-conventions.md new file mode 100644 index 0000000..1ecc347 --- /dev/null +++ b/rules/coding-conventions.md @@ -0,0 +1,50 @@ +# 코딩 컨벤션 + +## 기본 원칙 + +- **가독성 우선**: 영리한 코드보다 읽기 쉬운 코드를 선호합니다. +- **일관성 유지**: 기존 코드의 스타일을 먼저 관찰하고 그에 맞춥니다. +- **작은 단위**: 함수와 파일은 한 가지 책임만 지도록 작게 유지합니다. + +## 포맷팅 + +- 들여쓰기: 스페이스 2칸 (탭 사용 금지) +- 문자열: 싱글 쿼터(`'`) 사용, JSX/템플릿 속성값은 더블 쿼터(`"`) +- 세미콜론: 생략하지 않고 항상 작성 +- 줄 끝 공백 제거, 파일 끝 개행 1줄 유지 +- 한 줄 최대 100자 (초과 시 줄바꿈) +- Prettier 설정 파일(`.prettierrc`)이 있는 경우 해당 설정을 우선합니다. + +## 네이밍 + +- **변수/함수**: `camelCase` (예: `userProfile`, `fetchUserData`) +- **상수**: `UPPER_SNAKE_CASE` (예: `MAX_RETRY_COUNT`) +- **컴포넌트/클래스/타입**: `PascalCase` (예: `UserCard`, `OrderStatus`) +- **파일명** + - Vue 컴포넌트: `PascalCase.vue` (예: `UserCard.vue`) + - Composable: `use` 접두사 + `camelCase` (예: `useAuth.ts`) + - 일반 TS 모듈: `kebab-case.ts` (예: `format-date.ts`) +- **이벤트 핸들러**: `handle` 또는 `on` 접두사 (예: `handleClick`, `onSubmit`) +- **불리언**: `is`, `has`, `can`, `should` 접두사 (예: `isLoading`, `hasError`) + +## 타입 + +- `any` 사용 금지. 불가피할 경우 주석으로 이유를 남기고 `unknown`을 먼저 고려합니다. +- 함수 시그니처에는 매개변수와 반환 타입을 명시합니다. +- 공개 API(타 모듈에서 import 되는 것)는 반드시 타입을 export 합니다. +- 유니온 타입은 `as const` 또는 별도 타입 alias로 관리합니다. + +## 주석 + +- "무엇을" 보다 "왜"를 설명합니다. +- TODO/FIXME 주석에는 작성자와 날짜 또는 이슈 번호를 포함합니다. +- 공개 함수/컴포넌트에는 JSDoc 한 줄 설명을 권장합니다. + +## import 순서 + +1. 외부 라이브러리 (예: `vue`, `nuxt`) +2. 내부 절대 경로 (예: `~/components/...`) +3. 상대 경로 (예: `./utils`) +4. 타입 only import는 각 그룹 내에서 별도 블록으로 분리 + +그룹 사이에는 빈 줄을 한 줄 둡니다. diff --git a/rules/commit-pr.md b/rules/commit-pr.md new file mode 100644 index 0000000..72a262a --- /dev/null +++ b/rules/commit-pr.md @@ -0,0 +1,83 @@ +# 커밋 / PR 규칙 + +## 커밋 메시지 + +[Conventional Commits](https://www.conventionalcommits.org/)를 따릅니다. + +``` +(): + + + +