React 컴포지션 패턴
유연하고 유지보수 가능한 React 컴포넌트를 구축하기 위한 컴포지션 패턴입니다. boolean prop의 확산을 피하기 위해 복합 컴포넌트(compound components), 상태 끌어올리기(lifting state), 내부 구성(composing internals)을 사용합니다. 이러한 패턴은 코드베이스가 확장됨에 따라 사람과 AI 에이전트 모두가 작업하기 쉽게 만듭니다.
적용 시점
다음 상황에서 이 가이드라인을 참조하세요:
- 많은 boolean prop을 가진 컴포넌트를 리팩토링할 때
- 재사용 가능한 컴포넌트 라이브러리를 구축할 때
- 유연한 컴포넌트 API를 설계할 때
- 컴포넌트 아키텍처를 검토할 때
- 복합 컴포넌트나 컨텍스트 프로바이더로 작업할 때
우선순위별 규칙 범주
| 우선순위 | 범주 | 영향도 | 접두사 |
|---|---|---|---|
| 1 | 컴포넌트 아키텍처 | HIGH | architecture- |
| 2 | 상태 관리 | MEDIUM | state- |
| 3 | 구현 패턴 | MEDIUM | patterns- |
| 4 | React 19 API | MEDIUM | react19- |
빠른 참조
1. 컴포넌트 아키텍처 (HIGH)
architecture-avoid-boolean-props- 동작을 커스터마이즈하기 위해 boolean prop을 추가하지 말고 컴포지션을 사용하세요.architecture-compound-components- 공유 컨텍스트로 복잡한 컴포넌트를 구조화하세요.
2. 상태 관리 (MEDIUM)
state-decouple-implementation- 프로바이더만이 상태가 어떻게 관리되는지 알고 있습니다.state-context-interface- 의존성 주입을 위해 상태, 액션, 메타를 포함한 제네릭 인터페이스를 정의하세요.state-lift-state- 형제 접근을 위해 상태를 프로바이더 컴포넌트로 이동하세요.
3. 구현 패턴 (MEDIUM)
patterns-explicit-variants- boolean 모드 대신 명시적 변형 컴포넌트를 만드세요.patterns-children-over-render-props- renderX prop 대신 컴포지션을 위해 children을 사용하세요.
4. React 19 API (MEDIUM)
⚠️ React 19+ 전용. React 18 이하를 사용하는 경우 이 섹션을 건너뛰세요.
react19-no-forwardref-forwardRef를 사용하지 말고,useContext()대신use()를 사용하세요.
사용 방법
자세한 설명과 코드 예제를 보려면 개별 규칙 파일을 읽으세요:
rules/architecture-avoid-boolean-props.md
rules/state-context-interface.md
각 규칙 파일에는 다음이 포함되어 있습니다:
- 왜 중요한지에 대한 간략한 설명
- 설명이 포함된 잘못된 코드 예제
- 설명이 포함된 올바른 코드 예제
- 추가 컨텍스트 및 참조
전체 컴파일 문서
모든 규칙이 확장된 전체 가이드는 AGENTS.md를 참조하세요.