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