---
id: wiki-2026-0508-naming-conventions
title: Naming Conventions
category: 10_Wiki/Topics
status: needs_review
canonical_id: self
aliases: []
duplicate_of: none
source_trust_level: A
confidence_score: 0.92
tags: [uncategorized]
raw_sources: []
last_reinforced: 2026-05-08
github_commit: pending
inferred_by: Claude Opus 4.7 (auto-normalize 2026-05-08)
tech_stack:
  language: unspecified
  framework: unspecified
---

## 📌 한 줄 통찰 (The Karpathy Summary)
Naming Conventions(명명 규칙)은 코드의 가독성, 유지보수성, 그리고 협업 효율성을 높이기 위해 파일, 컴포넌트, 변수 등의 이름을 짓는 합의된 표준이다. 명확한 규칙을 통해 코드의 역할을 직관적으로 파악하게 하며, 특히 운영체제 간의 대소문자 구분 차이로 인한 빌드 오류를 방지하는 실질적인 엔지니어링 목적을 갖는다.

## 📖 구조화된 지식 (Synthesized Content)
1. **파일 및 폴더 (kebab-case)**
   - 대소문자 구분이 없는 OS(Windows, macOS)와 엄격한 OS(Linux) 간의 CI/CD 빌드 충돌을 막기 위해 소문자와 하이픈을 사용하는 `kebab-case`를 권장한다.
   - Next.js의 예약어(`page.js`, `layout.js`)나 라우트 그룹(`(folder)`) 등의 규칙을 준수한다.
2. **React 컴포넌트 및 타입 (PascalCase)**
   - 컴포넌트명과 TypeScript의 Type/Interface, Enum 등은 첫 글자를 대문자로 하는 `PascalCase`를 사용하여 일반 변수와 구별한다.
3. **변수, 함수, 프로퍼티 (camelCase)**
   - JavaScript 표준에 따라 첫 단어는 소문자로 시작하는 `camelCase`를 사용한다.
   - Boolean 값은 `is`, `has`, `should` 접두사를, 이벤트 핸들러는 `handle`, `on` 접두사를 붙여 의미를 명확히 한다.
4. **커스텀 훅 (use 접두사)**
   - React의 Rules of Hooks를 준수하기 위해 반드시 `use` 접두사로 시작하는 `camelCase`를 사용한다.
5. **상수 (UPPER_SNAKE_CASE)**
   - 변경되지 않는 고정 값은 대문자와 밑줄을 사용하는 `UPPER_SNAKE_CASE`로 작성하여 식별력을 높인다.
6. **Git 및 워크플로우**
   - 브랜치명: `{type}/{ticket-id}-{description}` 형식의 소문자 kebab-case 사용.
   - 커밋 메시지: Conventional Commits(`feat:`, `fix:` 등) 형식을 준수하여 추적성을 확보한다.

## ⚠️ 모순 및 업데이트 (Contradictions & Updates)
- **엄격함 vs 유연성**: 너무 복잡한 네이밍 규칙은 개발자의 인지 부하를 늘리고 생산성을 저하시킬 수 있으므로, 팀 규모에 맞는 적절한 수준의 합의가 필요하다.
- **자동화 도구의 한계**: ESLint 등으로 많은 네이밍 규칙을 강제할 수 있으나, '의미론적(Semantic) 적절성'까지는 도구가 판단할 수 없으므로 여전히 코드 리뷰가 중요하다.
- **프레임워크 제약**: 사용 중인 프레임워크(예: Next.js)의 예약어 규칙이 팀의 컨벤션과 충돌할 경우, 프레임워크의 규칙을 우선시해야 시스템 오류를 방지할 수 있다.

## 🔗 지식 연결 (Graph)
### Related Concepts (Auto-Linked)
* [[Abstract_Syntax_Tree]]
* [[Branching Strategies]]
* [[ESLint]]
* [[Feature-Sliced_Design]]
* [[JavaScript]]
* [[Next.js]]
* [[Prettier]]
* [[React]]
* [[Research]]

### Related Concepts
- **kebab-case**: 파일 시스템 호환성을 위한 소문자-하이픈 조합 (관계: 물리적 저장 표준)
- **Conventional Commits**: 변경 이력 가독성을 위한 표준 (관계: 협업 워크플로우 규칙)
- **PascalCase**: 컴포넌트 및 타입 식별을 위한 대문자 시작 조합 (관계: 논리적 식별 표준)

### Deeper Research Questions
1. OS별 대소문자 인식 차이가 실제 프로덕션 빌드 환경에서 유발하는 'Silent failure' 사례와 그 디버깅 방법은?
2. 네이밍 규칙 준수가 TypeScript의 타입 추론 성능이나 트리 쉐이킹(Tree Shaking) 효율에 간접적인 영향을 미치는가?
3. 대규모 리팩토링 시, 기존의 네이밍 컨벤션을 일괄 변경하기 위한 AST(Abstract Syntax Tree) 기반 자동화 도구 활용 방안은?
4. `isVisible` vs `showComponent`와 같이 상태 중심 네이밍과 명령 중심 네이밍 중 어떤 것이 유지보수에 더 유리한가?
5. 다국어 지원(i18n) 프로젝트에서 키값(Key) 네이밍을 도메인 중심으로 짓는 것과 페이지 중심으로 짓는 것의 트레이드오프는?

### Practical Application Contexts
- **협업 환경 구축**: ESLint 및 Prettier 설정을 통해 팀원 전체가 동일한 네이밍 케이스를 사용하도록 자동 강제.
- **이슈 추적**: 브랜치명에 티켓 ID를 포함하여 Jira/GitHub Issues와 코드를 유기적으로 연결.

### Adjacent Topics
- **Clean Code & Meaningful Names**
- **Feature-Sliced Design (FSD)**
- **Git Branching Strategies**

## 🤖 LLM 활용 힌트 (How to Use This Knowledge)

**언제 이 지식을 쓰는가:**
- *(TODO)*

**언제 쓰면 안 되는가:**
- *(TODO)*

## 🧪 검증 상태 (Validation)

- **정보 상태:** needs_review
- **출처 신뢰도:** A
- **검토 이유:** *(P-Reinforce Phase 1 자동 정규화. 본문 검증 필요.)*

## 🧬 중복 검사 (Duplicate Check)

- **기존 유사 문서:** *(TODO: 인덱서 클러스터 리포트 참조)*
- **처리 방식:** UPDATE (자동 정규화)
- **처리 이유:** Phase 1 정규화 — 옛 템플릿/누락 필드 보강.

## 🕓 변경 이력 (Changelog)

| 날짜 | 변경 내용 | 처리 방식 | 신뢰도 |
|------|-----------|-----------|--------|
| 2026-05-08 | P-Reinforce Phase 1 정규화 (frontmatter + 헤더 표준화) | UPDATE | A |

## 💻 코드 패턴 (Code Patterns)

**패턴 1:** *(TODO: 이 프로젝트 컨벤션 반영한 구조 스켈레톤)*

```text
# TODO
```

## 🤔 의사결정 기준 (Decision Criteria)

**선택 A를 써야 할 때:**
- *(TODO)*

**선택 B를 써야 할 때:**
- *(TODO)*

**기본값:**
> *(TODO)*

## ❌ 안티패턴 (Anti-Patterns)

- **[안티패턴]:** *(TODO: 무엇을 하면 안 되는가 + 이유 + 대신 무엇을)*