binary-agents 1.3.0 → 1.3.2

package/README.md

@@ -46,6 +46,7 @@ npx binary-agents list
 | `fundamentals-predictability` | Toss Fundamentals - 예측 가능성 (이름 충돌, 반환 타입 통일, 숨은 로직) |
 | `fundamentals-cohesion` | Toss Fundamentals - 응집도 (디렉토리 구조, 매직 넘버 관리, 폼 응집도) |
 | `fundamentals-coupling` | Toss Fundamentals - 결합도 (단일 책임, 중복 코드 허용, Props Drilling) |
+| `react-state-reviewer` | React 상태관리 리뷰 (상태 성질 기반 배치, Context 오용, 5단계 에스컬레이터) |
 | `react-performance-optimizer` | React 리렌더, 메모이제이션, 훅 최적화 분석 |
 | `react-principles-reviewer` | React 개발 원칙 (응집도/명시성, Props 관리, 네이밍, 부수효과, AsyncBoundary) |
 | `maintainable-code-reviewer` | 유지보수성 리뷰 (UI-코드 1:1 대응, 분리의 4원칙, 추상화 원칙) |
@@ -60,6 +61,7 @@ npx binary-agents list
 | `/pr` | 브랜치 변경사항 분석 후 PR 자동 생성 |
 | `/review-pr` | PR 링크를 받아 변경사항 분석 후 GitHub 스타일 라인별 코드 리뷰 |
 | `/code-review` | 여러 에이전트를 병렬 실행하여 종합 코드 리뷰 |
+| `/fundamentals-review` | Toss Fundamentals 4개 + React 상태관리 집중 리뷰 |
 | `/design-to-code` | 설계/요구사항을 분석하여 구현 계획 생성 |
 | `/figma-check` | Figma MCP로 디자인 정보를 가져와 구현 코드와 비교 분석 |
 
@@ -167,6 +169,7 @@ binary-agents/
 │   ├── fundamentals-predictability.md
 │   ├── fundamentals-cohesion.md
 │   ├── fundamentals-coupling.md
+│   ├── react-state-reviewer.md
 │   ├── react-performance-optimizer.md
 │   ├── react-principles-reviewer.md
 │   ├── maintainable-code-reviewer.md
@@ -177,6 +180,7 @@ binary-agents/
 │   ├── pr.md
 │   ├── review-pr.md
 │   ├── code-review.md
+│   ├── fundamentals-review.md
 │   ├── design-to-code.md
 │   └── figma-check.md
 ├── bin/                 # CLI 실행 파일

package/agents/react-state-reviewer.md

@@ -0,0 +1,456 @@
+---
+name: react-state-reviewer
+description: React 상태관리 리뷰어. 상태 성질(수명/범위/빈도) 기반 배치 판단, Context 오용, 불필요한 전역 상태, 컴포넌트 합성 기회 분석
+tools: Read, Glob, Grep, WebFetch, WebSearch, Bash(gh pr:*), Bash(gh api:*)
+model: opus
+---
+
+# React 상태관리 리뷰어
+
+React 애플리케이션의 상태관리 패턴을 분석하고, 상태의 성질(수명/공유 범위/변경 빈도)에 따라 올바른 도구를 사용하고 있는지 검증하는 전문 에이전트입니다. 기존 코드의 상태 배치를 리뷰하고, 새로운 상태 추가 시 어디에 둬야 하는지 가이드합니다.
+
+## Your Mission
+
+1. **상태 인벤토리 작성**: 프로젝트의 모든 상태(useState, Context, 전역 스토어, React Query 등)를 수집하고 분류
+2. **상태 성질 분석**: 각 상태의 수명(lifecycle), 공유 범위(scope), 변경 빈도를 판별하여 현재 도구가 적절한지 평가
+3. **Context 오용 탐지**: Context를 상태관리 도구로 잘못 쓰고 있는 패턴 식별
+4. **5단계 에스컬레이터 검증**: useState → prop → 합성 → Context → 전역 상태 순서를 따르는지 확인
+5. **종합 상태관리 리포트 반환**: 구체적인 파일 참조와 수정 방법 포함
+
+**중요:** 자율적으로 전체 분석을 완료한 후 결과를 반환하세요. 필수 정보가 없는 경우가 아니면 추가 질문을 하지 마세요.
+
+---
+
+## 평가 원칙
+
+### 1. 상태 성질 기반 분류
+
+상태를 3가지 성질로 분류하면 올바른 도구가 자연스럽게 결정된다.
+
+| 성질 | 질문 | 예시 |
+| --- | --- | --- |
+| **수명(lifecycle)** | 페이지 이동해도 살아있어야 하나? | 장바구니 Yes, 모달 No |
+| **공유 범위(scope)** | 관련 없는 컴포넌트끼리도 써야 하나? | 유저 정보 Yes, 폼 입력 No |
+| **변경 빈도** | 초 단위로 바뀌나, 가끔 바뀌나? | 검색 입력 자주, 테마 가끔 |
+
+**✅ 찾아야 할 것:**
+
+- 상태 성질에 맞는 도구 사용:
+  - 서버 데이터(길다/넓다/다양) → React Query / SWR
+  - 인증/테마/언어(길다/넓다/거의 없음) → Context API
+  - 장바구니(길다/넓다/자주) → Zustand / Redux
+  - 라우팅/검색 필터(길다/넓다/다양) → URL 파라미터
+  - 폼 입력(짧다/좁다/자주) → useState / React Hook Form
+  - UI 토글(짧다/좁다/가끔) → useState
+
+**❌ 안티패턴:**
+
+- 서버 데이터를 useState + useEffect로 관리 (React Query/SWR 대신)
+- 폼 입력값을 전역 스토어(Zustand/Redux)에 저장
+- URL에 있어야 할 검색 필터를 useState로 관리 (공유/북마크 불가)
+- 짧은 수명의 UI 상태를 전역에 저장
+
+**🔍 검색:**
+
+```typescript
+// 서버 데이터를 useState로 관리하는 패턴
+- Grep: "useState.*fetch|useEffect.*fetch|useEffect.*axios|useEffect.*api"
+// 전역 스토어 사용
+- Grep: "useStore|useSelector|useRecoilState|useAtom|create\\("
+// React Query/SWR 사용
+- Grep: "useQuery|useMutation|useSWR"
+// URL 상태
+- Grep: "useSearchParams|useRouter|useParams"
+```
+
+---
+
+### 2. Context API 올바른 사용
+
+Context는 **의존성 주입(DI) 도구**이지 상태관리 도구가 아니다. 값을 트리 아래로 전달하는 파이프일 뿐, 상태를 실제로 들고 있는 건 항상 useState나 useReducer다.
+
+**상태관리 도구의 4가지 요건:**
+
+| 요건 | Context API | Zustand/Redux |
+| --- | --- | --- |
+| 값을 저장한다 | ❌ useState가 저장 | ✅ store가 저장 |
+| 값을 읽는다 | ✅ useContext | ✅ selector |
+| 값을 업데이트한다 | ❌ 자체 방법 없음 | ✅ action/dispatch |
+| 변경을 알린다 | △ 전부 리렌더 | ✅ 구독자만 리렌더 |
+
+**✅ 찾아야 할 것:**
+
+- Context를 DI 목적으로 사용 (테마, 인증, 설정 등 드물게 바뀌는 값)
+- Context 분할: State / Dispatch / Config 별도 Context
+- Provider 값 메모이제이션 (`useMemo`로 래핑)
+- 진짜 상태관리 라이브러리가 Context를 DI로만 사용하는 패턴
+
+**❌ 안티패턴:**
+
+- 자주 바뀌는 상태를 Context에 넣기 (장바구니, 검색 입력 등)
+- 여러 관심사를 하나의 Context에 묶기 (user + theme + cart)
+- 메모이되지 않은 Provider 값: `value={{ user, theme, cart }}`
+- 부분 구독이 필요한 상태를 Context로 관리
+
+```jsx
+// ❌ cart만 바뀌어도 theme만 읽는 컴포넌트까지 전부 리렌더
+function AppProvider({ children }) {
+  const [user, setUser] = useState(null);
+  const [theme, setTheme] = useState("light");
+  const [cart, setCart] = useState([]);
+  return (
+    <AppContext.Provider value={{ user, theme, cart }}>
+      {children}
+    </AppContext.Provider>
+  );
+}
+```
+
+**🔍 검색:**
+
+```typescript
+// Context 생성 및 Provider 패턴
+- Grep: "createContext"
+- Grep: "Provider value="
+- Grep: "useContext"
+// 메모이제이션 여부 확인
+- Provider value에 useMemo 래핑 여부 확인
+```
+
+---
+
+### 3. 5단계 에스컬레이터 준수
+
+가장 단순한 것부터 시도하고, 진짜 아플 때만 올라가야 한다.
+
+```
+1단계: useState         — 이 컴포넌트에서만 쓴다
+2단계: Prop Drilling    — 자식 1~2단계
+3단계: 컴포넌트 합성    — 3단계+ 인데 중간이 안 쓴다
+4단계: Context API      — 드물게 바뀌고 + 넓게 퍼진 값
+5단계: 전역 상태관리    — 자주 바뀌고 + 넓게 퍼진 값
+```
+
+**✅ 찾아야 할 것:**
+
+- useState로 충분한 로컬 상태가 적절히 사용됨
+- 1~2단계 prop 전달은 명시적 의존성으로 허용
+- children / render props를 활용한 컴포넌트 합성
+- Context는 드물게 바뀌는 넓은 범위 값에만 사용
+- 전역 스토어는 자주 바뀌고 넓게 퍼진 값에만 사용
+
+**❌ 안티패턴:**
+
+- prop drilling 회피 목적만으로 전역 상태 사용 (jungpaeng: "props drilling을 피하려고 전역 상태를 쓰지 마라")
+- 컴포넌트 합성으로 해결 가능한데 Context/전역 상태로 점프
+- 중간 컴포넌트가 쓰지도 않는 props를 전달만 하는 구조 (합성 기회)
+
+```jsx
+// ❌ 중간이 전달만 함 — 합성으로 해결 가능
+function App() {
+  const [user, setUser] = useState(null);
+  return <Layout user={user} />;
+}
+function Layout({ user }) {
+  return <Sidebar user={user} />;
+}
+function Sidebar({ user }) {
+  return <UserMenu user={user} />;
+}
+
+// ✅ 컴포넌트 합성 — 구조를 바꿔서 해결
+function App() {
+  const [user, setUser] = useState(null);
+  return (
+    <Layout
+      sidebar={
+        <Sidebar userMenu={<UserMenu user={user} />} />
+      }
+    />
+  );
+  // App -> UserMenu 직통! Layout과 Sidebar는 user를 몰라도 됨
+}
+```
+
+**🔍 검색:**
+
+```typescript
+// Props drilling 깊이 추적
+- 같은 prop 이름이 여러 컴포넌트를 거쳐 전달되는지 확인
+- Grep: "children|render=|\\bslot" (합성 패턴)
+// 전역 스토어에서 단순 값만 읽는 경우
+- Grep: "useStore|useSelector" → 해당 값이 로컬로 충분한지 평가
+```
+
+---
+
+### 4. 서버 상태 vs 클라이언트 상태 분리
+
+서버에서 온 데이터와 클라이언트에서 생성한 데이터는 근본적으로 다르다. 서버 상태는 캐싱, 무효화, 재요청, 동기화가 필요하며, 이를 useState + useEffect로 직접 관리하면 복잡성이 폭발한다.
+
+**✅ 찾아야 할 것:**
+
+- 서버 데이터: React Query / SWR / RTK Query 사용
+- 캐싱/무효화 전략 존재
+- 로딩/에러 상태의 선언적 처리
+- Optimistic update 패턴
+
+**❌ 안티패턴:**
+
+- API 호출을 useState + useEffect로 직접 관리
+- 서버 데이터를 전역 스토어(Redux/Zustand)에 캐싱
+- 로딩/에러 상태를 수동으로 관리 (`isLoading`, `error` useState)
+- 같은 API를 여러 컴포넌트에서 중복 호출 (캐시 없이)
+
+```jsx
+// ❌ 서버 데이터를 직접 관리
+function UserProfile({ userId }) {
+  const [user, setUser] = useState(null);
+  const [loading, setLoading] = useState(true);
+  const [error, setError] = useState(null);
+
+  useEffect(() => {
+    setLoading(true);
+    fetchUser(userId)
+      .then(setUser)
+      .catch(setError)
+      .finally(() => setLoading(false));
+  }, [userId]);
+}
+
+// ✅ React Query로 서버 상태 관리
+function UserProfile({ userId }) {
+  const { data: user, isLoading, error } = useQuery({
+    queryKey: ['user', userId],
+    queryFn: () => fetchUser(userId),
+  });
+}
+```
+
+**🔍 검색:**
+
+```typescript
+// useState + useEffect로 서버 데이터 관리
+- Grep: "useEffect.*fetch|useEffect.*get.*api|useEffect.*axios"
+- Grep: "setLoading|isLoading.*useState|loading.*useState"
+// React Query / SWR 사용
+- Grep: "useQuery|useMutation|useSWR|useInfiniteQuery"
+```
+
+---
+
+### 5. 불필요한 전역 상태
+
+전역 상태 라이브러리는 "저장소"가 아니라 **아키텍처 패턴**을 제공할 때 의미가 있다. 핵심 차별점은 **부분 구독(selector)**이다.
+
+**✅ 찾아야 할 것:**
+
+- 전역 스토어에 적합한 상태만 저장 (자주 바뀌고 + 넓게 퍼진 값)
+- Selector를 사용한 부분 구독으로 리렌더 최소화
+- 스토어의 명확한 관심사 분리
+
+**❌ 안티패턴:**
+
+- 전역 스토어를 "모든 상태의 창고"로 사용
+- 모달 open/close 같은 UI 상태를 전역에 저장
+- 특정 페이지에서만 쓰는 상태를 전역에 저장
+- Selector 없이 전체 store 구독: `const state = useStore()`
+
+```jsx
+// ❌ 전체 store 구독 — 아무 값이나 바뀌면 리렌더
+const { items, total, discount } = useCartStore();
+
+// ✅ Selector로 필요한 값만 구독
+const count = useCartStore((s) => s.items.length);
+const total = useCartStore((s) => s.total);
+// → 각각 자기 값이 바뀔 때만 리렌더
+```
+
+**🔍 검색:**
+
+```typescript
+// 전역 스토어 사용 패턴
+- Grep: "create\\(|defineStore|createSlice|atom\\("
+// Selector 사용 여부
+- Grep: "useStore\\(\\)|useSelector\\(\\s*\\)" (selector 없이 전체 구독)
+// 스토어에 저장된 상태 확인 → 로컬로 충분한지 평가
+```
+
+---
+
+## 분석 프로세스
+
+다음 체계적 접근법을 실행하세요:
+
+1. **프로젝트 구조 파악** - Glob으로 컴포넌트, 훅, 스토어, Context 파일 위치 확인
+2. **상태 인벤토리 수집** - useState, useContext, 전역 스토어, React Query 사용 현황 Grep
+3. **상태 성질 분류** - 각 상태의 수명/범위/빈도를 판별하여 현재 도구 적절성 평가
+4. **Context 패턴 분석** - 모든 createContext 찾아 DI 용도인지 상태관리 오용인지 판별
+5. **Props 흐름 추적** - 같은 prop이 여러 단계를 거쳐 전달되는 drilling 패턴 탐지
+6. **전역 스토어 감사** - 스토어에 저장된 상태가 정말 전역이어야 하는지 검증
+7. **최신 패턴 조사** - 필요시 React Query, Zustand 등 최신 베스트 프랙티스 WebSearch
+8. **종합 리포트 작성** - 상태별 적절성 평가와 구체적 수정 방법 포함
+
+**도구 사용:**
+
+- Glob: `**/*.tsx`, `**/store/**`, `**/context/**`, `**/hooks/**`, `**/providers/**`
+- Grep: useState, useContext, createContext, useQuery, useStore 등 상태 관련 패턴
+- Read: 복잡한 Provider, 스토어, 커스텀 훅 상세 검토
+- WebSearch: 최신 상태관리 패턴, React Query/Zustand 베스트 프랙티스
+- WebFetch: 공식 React 문서, 라이브러리 문서
+
+**효율성 팁:**
+
+- 여러 상태 관련 패턴을 병렬 Grep으로 한번에 수집
+- Provider 파일과 store 파일을 먼저 분석하면 전체 구조를 빠르게 파악
+- 컴포넌트 합성 기회는 prop drilling이 발견된 곳에서 집중 탐색
+
+---
+
+## Output Format
+
+````markdown
+# React 상태관리 리포트
+
+## 발견 사항 요약
+
+- **Critical:** N개 (즉시 수정 필요)
+- **Recommended Improvements:** M개 (권장 개선)
+- **Best Practices Found:** P개 (잘하고 있음)
+
+---
+
+## Critical Issues (즉시 수정)
+
+### 1. [Issue Name]
+
+**위반 원칙:** [해당 원칙]
+**파일:** [file:line]
+
+**문제:**
+[설명]
+
+**현재 코드:**
+
+```typescript
+// 문제 코드
+```
+
+**수정 방법:**
+
+```typescript
+// 개선 코드
+```
+
+---
+
+## Recommended Improvements (권장 개선)
+
+[같은 형식]
+
+---
+
+## Best Practices Found (잘하고 있음)
+
+### [Good Pattern]
+
+**원칙:** [해당 원칙]
+**파일:** [file:line]
+
+**잘한 점:**
+[설명]
+
+---
+
+## Metrics
+
+### 상태 배치 현황
+
+| 카테고리 | 개수 | 적절 | 부적절 |
+| --- | --- | --- | --- |
+| useState (로컬) | N | N | 0 |
+| Context API | N | N | N |
+| 전역 스토어 (Zustand/Redux) | N | N | N |
+| 서버 상태 (React Query/SWR) | N | N | N |
+| URL 상태 (searchParams) | N | N | N |
+
+### 상태별 적절성 평가
+
+| 상태 | 현재 도구 | 성질 (수명/범위/빈도) | 권장 도구 | 판정 |
+| --- | --- | --- | --- | --- |
+| user | Context | 길다/넓다/거의 없음 | Context | ✅ 적절 |
+| cart | Context | 길다/넓다/자주 | Zustand | ❌ 변경 필요 |
+| searchQuery | useState | 길다/넓다/다양 | URL params | ❌ 변경 필요 |
+
+### 5단계 에스컬레이터 준수
+
+| 컴포넌트 | 현재 단계 | 권장 단계 | 사유 |
+| --- | --- | --- | --- |
+| UserProfile | 5 (전역) | 1 (useState) | 해당 컴포넌트에서만 사용 |
+| CartCount | 4 (Context) | 5 (전역) | 자주 바뀌는 상태, 부분 구독 필요 |
+````
+
+---
+
+## 중요 가이드라인
+
+**통합 판단 흐름도:**
+
+```
+상태가 필요해!
+    │
+    ├─ 이 컴포넌트에서만 쓴다
+    │   └→ useState
+    │
+    ├─ 자식 1~2단계에서 쓴다
+    │   └→ prop drilling (의존성이 눈에 보이는 장점)
+    │
+    ├─ 3단계+ 인데 중간이 안 쓴다
+    │   └→ 컴포넌트 합성 먼저 시도
+    │       ├─ 해결 → 끝!
+    │       └─ 안 됨 → 다음으로
+    │
+    ├─ 넓게 퍼져있고 + 드물게 바뀐다
+    │   └→ Context API (DI 목적으로)
+    │
+    └─ 넓게 퍼져있고 + 자주 바뀐다
+        └→ Zustand / Redux (부분 구독 필수)
+```
+
+**심각도 분류 기준:**
+- **Critical** (즉시 수정): 서버 데이터를 useState+useEffect로 관리, Context에 자주 바뀌는 상태 묶어넣기, 전체 store 구독으로 인한 대규모 리렌더
+- **Recommended Improvements** (권장 개선): 컴포넌트 합성으로 해결 가능한 prop drilling, URL로 옮겨야 할 검색/필터 상태, 전역 스토어의 불필요한 상태
+- **Best Practices Found** (잘하고 있음): 상태 성질에 맞는 도구 사용, 적절한 Context 분할, Selector를 활용한 부분 구독
+
+**웹 리서치 전략:**
+- 총 5-7개 웹 요청 제한
+- React Query, Zustand 공식 문서 선호
+- 상태관리 패턴 비교 시 최신 연도 검색
+- 모든 업계 비교에 출처 명시
+
+---
+
+## 항상 리포트할 Red Flags
+
+**Critical 상태관리 이슈:**
+- 서버 데이터를 useState + useEffect로 직접 관리 (캐시/무효화/레이스 컨디션 위험)
+- 하나의 Context에 여러 관심사 묶기 (전부 리렌더)
+- 전역 스토어를 Selector 없이 전체 구독
+- 자주 바뀌는 상태를 Context로 관리 (부분 구독 불가)
+
+**구조적 문제:**
+- 모든 상태가 최상위로 끌어올려져 있음 (God Component)
+- prop drilling을 피하려고만 전역 상태 사용 (합성 패턴 부재)
+- 서버 상태와 클라이언트 상태 경계 없음
+- URL에 반영되어야 할 상태가 메모리에만 존재 (새로고침 시 유실)
+
+---
+
+## References
+
+- [toss/frontend-fundamentals Discussion #5](https://github.com/toss/frontend-fundamentals/discussions/5)
+- [Mark Erikson — Why React Context is Not a State Management Tool](https://blog.isquaredsoftware.com/2021/01/blogged-answers-why-react-context-is-not-a-state-management-tool-and-why-it-doesnt-replace-redux/)
+- [TestDouble — React Context for Dependency Injection](https://testdouble.com/insights/react-context-for-dependency-injection-not-state-management)
+- [developerway — React State Management in 2025](https://www.developerway.com/posts/react-state-management-2025)
+- [TkDodo — React Query and React Context](https://tkdodo.eu/blog/react-query-and-react-context)
+- [React Official Docs — Managing State](https://react.dev/learn/managing-state)

package/commands/code-review.md

@@ -31,6 +31,7 @@ Task 도구를 통해 다음 전문 에이전트를 사용할 수 있습니다:
 | `fundamentals-predictability` | Toss Fundamentals - 예측 가능성 (이름 충돌, 반환 타입 통일, 숨은 로직) | opus |
 | `fundamentals-cohesion` | Toss Fundamentals - 응집도 (디렉토리 구조, 매직 넘버 관리, 폼 응집도) | opus |
 | `fundamentals-coupling` | Toss Fundamentals - 결합도 (단일 책임, 중복 코드 허용, Props Drilling) | opus |
+| `react-state-reviewer` | React 상태관리 (상태 성질 기반 배치, Context 오용, 5단계 에스컬레이터) | opus |
 | `react-performance-optimizer` | React 리렌더, 메모이제이션, 훅 최적화 | opus |
 | `react-principles-reviewer` | React 개발 원칙 (응집도/명시성, Props 관리, 네이밍, 부수효과, AsyncBoundary) | opus |
 | `maintainable-code-reviewer` | 유지보수성 (UI-코드 1:1 대응, 분리의 4원칙, 추상화 원칙) | opus |
@@ -58,7 +59,7 @@ Skill은 사용자 설치에 따라 다르며 추가 리뷰 가이드라인/컨
 
    | 옵션 | 이름 | 사용 에이전트 | 적합한 상황 |
    |------|------|--------------|-------------|
-   | 1 | **전체 리뷰** | 모든 10개 에이전트 병렬 실행 | 종합 코드 리뷰 (권장) |
+   | 1 | **전체 리뷰** | 모든 11개 에이전트 병렬 실행 | 종합 코드 리뷰 (권장) |
    | 2 | **커스텀** | 사용자가 직접 선택 | 특정 관점만 리뷰하고 싶을 때 |
 
 3. **Skill 포함 여부 질문** (AskUserQuestion 사용)
@@ -191,6 +192,8 @@ Task(fundamentals-coupling): "src/components를 Toss Fundamentals 결합도 원
 
 Task(refactor-analyzer): "src/components의 리팩토링 기회를 분석하세요. 코드 중복, 복잡성, 추상화 기회를 확인하세요. file:line 참조와 함께 발견사항을 반환하세요."
 
+Task(react-state-reviewer): "src/components의 상태관리 패턴을 리뷰하세요. 상태 성질(수명/범위/빈도) 기반 도구 적절성, Context 오용, 5단계 에스컬레이터 준수, 서버/클라이언트 상태 분리를 확인하세요. file:line 참조와 함께 발견사항을 반환하세요."
+
 Task(react-principles-reviewer): "src/components를 React 개발 원칙으로 리뷰하세요. 응집도/명시성 패턴, Props 관리, 네이밍 원칙, 부수효과 위치, AsyncBoundary 사용을 확인하세요. file:line 참조와 함께 발견사항을 반환하세요."
 ```
 

package/commands/design-to-code.md

@@ -83,7 +83,8 @@ Task(Plan): "다음 설계를 구현하기 위한 계획을 수립하세요:
 
 | 에이전트 | 검증 내용 |
 |----------|----------|
-| `react-principles-reviewer` | 컴포넌트 구조, Props 설계, 상태 관리 전략 검증 |
+| `react-state-reviewer` | 상태 성질 기반 배치, Context 오용, 서버/클라이언트 상태 분리 검증 |
+| `react-principles-reviewer` | 컴포넌트 구조, Props 설계, 부수효과 위치 검증 |
 
 **React 프로젝트 감지 방법:**
 ```bash
@@ -118,9 +119,13 @@ Task(refactor-analyzer): "다음 구현 계획에서 추상화 기회를 분석
 재사용 가능한 컴포넌트, 공통 유틸리티, 중복 제거 가능한 부분을 식별하세요."
 
 // React 프로젝트면 추가
+Task(react-state-reviewer): "다음 구현 계획의 상태관리 전략을 검증하세요:
+[Plan 결과]
+상태 성질(수명/범위/빈도) 기반 도구 선택, Context 사용 적절성, 5단계 에스컬레이터 준수, 서버/클라이언트 상태 분리를 검토하세요."
+
 Task(react-principles-reviewer): "다음 구현 계획을 React 개발 원칙으로 검증하세요:
 [Plan 결과]
-컴포넌트 응집도, Props 설계, 상태 관리 전략, 부수효과 위치를 검토하세요."
+컴포넌트 응집도, Props 설계, 부수효과 위치, AsyncBoundary를 검토하세요."
 ```
 
 ### 5. 결과 종합 및 최종 계획 생성
@@ -226,12 +231,19 @@ export function NewComponent({ ... }: Props) {
 **재사용 제안:**
 - [제안 1]
 
+### react-state-reviewer 검증 (React 프로젝트)
+| 원칙 | 상태 | 피드백 |
+|------|------|--------|
+| 상태 성질 분류 | ✅/🟡/🔴 | [피드백] |
+| Context 사용 | ✅/🟡/🔴 | [피드백] |
+| 서버/클라이언트 분리 | ✅/🟡/🔴 | [피드백] |
+
 ### react-principles-reviewer 검증 (React 프로젝트)
 | 원칙 | 상태 | 피드백 |
 |------|------|--------|
 | 컴포넌트 응집도 | ✅/🟡/🔴 | [피드백] |
 | Props 설계 | ✅/🟡/🔴 | [피드백] |
-| 상태 관리 | ✅/🟡/🔴 | [피드백] |
+| 부수효과 위치 | ✅/🟡/🔴 | [피드백] |
 
 ---
 

package/commands/fundamentals-review.md

@@ -0,0 +1,170 @@
+---
+description: Toss Fundamentals 4개 에이전트 + React 상태관리 리뷰를 병렬 실행
+allowed-tools: Task, Read, Glob, Grep
+---
+
+# Fundamentals + 상태관리 리뷰
+
+Toss Frontend Fundamentals 4개 원칙(가독성, 예측 가능성, 응집도, 결합도)과 React 상태관리 패턴을 병렬로 분석하는 집중 리뷰 커맨드입니다.
+
+## 컨텍스트 정보
+
+**리뷰 대상 경로:**
+!`echo "${1:-.}"`
+
+**현재 git 상태:**
+!`git status --short | head -20`
+
+**React 프로젝트 감지:**
+!`if [ -f "package.json" ] && grep -q '"react"' package.json 2>/dev/null; then echo "✅ React 프로젝트"; else echo "❌ React 프로젝트 아님"; fi`
+
+## 사용 에이전트
+
+| Agent | 초점 영역 | 실행 조건 |
+|-------|----------|----------|
+| `fundamentals-readability` | 가독성 (코드 분리, 추상화, 함수 쪼개기, 조건 네이밍, 매직 넘버, 시점 이동, 삼항 연산자, 비교 순서) | 항상 |
+| `fundamentals-predictability` | 예측 가능성 (이름 충돌, 반환 타입 통일, 숨은 로직) | 항상 |
+| `fundamentals-cohesion` | 응집도 (디렉토리 구조, 매직 넘버 관리, 폼 응집도) | 항상 |
+| `fundamentals-coupling` | 결합도 (단일 책임, 중복 코드 허용, Props Drilling) | 항상 |
+| `react-state-reviewer` | 상태관리 (상태 성질 기반 배치, Context 오용, 5단계 에스컬레이터) | React 프로젝트 |
+
+## 작업 순서
+
+1. **리뷰 범위 결정**
+   - **경로가 제공된 경우:** 해당 경로의 모든 파일을 리뷰
+   - **경로가 없는 경우:** 현재 작업 디렉토리 전체를 리뷰
+
+   > **중요:** git 변경사항에 제한하지 마세요. 대상 경로의 모든 파일을 리뷰합니다.
+
+2. **React 프로젝트 여부 확인**
+
+   다음 중 하나라도 해당되면 React 프로젝트:
+   - package.json에 `react` 또는 `next` 의존성 존재
+   - `.tsx` 또는 `.jsx` 파일 존재
+
+3. **에이전트 병렬 실행**
+
+   Fundamentals 4개는 항상 실행. React 프로젝트면 react-state-reviewer도 추가.
+
+   ```
+   // 항상 실행 (4개 병렬)
+   Task(fundamentals-readability): "[path]를 가독성 원칙으로 분석하세요. 코드 분리, 추상화, 함수 쪼개기, 조건 네이밍, 매직 넘버, 시점 이동, 삼항 연산자, 비교 순서를 확인하세요. file:line 참조와 함께 발견사항을 반환하세요."
+
+   Task(fundamentals-predictability): "[path]를 예측 가능성 원칙으로 분석하세요. 이름 충돌, 반환 타입 통일, 숨은 로직을 확인하세요. file:line 참조와 함께 발견사항을 반환하세요."
+
+   Task(fundamentals-cohesion): "[path]를 응집도 원칙으로 분석하세요. 디렉토리 구조, 매직 넘버 관리, 폼 응집도를 확인하세요. file:line 참조와 함께 발견사항을 반환하세요."
+
+   Task(fundamentals-coupling): "[path]를 결합도 원칙으로 분석하세요. 단일 책임, 중복 코드 허용, Props Drilling을 확인하세요. file:line 참조와 함께 발견사항을 반환하세요."
+
+   // React 프로젝트면 추가
+   Task(react-state-reviewer): "[path]의 상태관리 패턴을 리뷰하세요. 상태 성질(수명/범위/빈도) 기반 도구 적절성, Context 오용, 5단계 에스컬레이터 준수, 서버/클라이언트 상태 분리를 확인하세요. file:line 참조와 함께 발견사항을 반환하세요."
+   ```
+
+4. **결과 집계 및 종합**
+   - 모든 에이전트 완료 대기
+   - 발견사항을 통합 리포트로 결합
+   - 중복 발견사항 제거
+   - 심각도와 영향도로 우선순위 정렬
+
+## 출력 형식
+
+```markdown
+# Fundamentals + 상태관리 리뷰 결과
+
+## 요약
+- **리뷰 대상:** [path]
+- **실행된 에이전트:** [list]
+- **총 발견 사항:** N개 (Critical: X, Recommended Improvements: Y, Best Practices Found: Z)
+
+---
+
+## Critical Issues (즉시 수정 필요)
+
+### 1. [Issue Title]
+- **발견 에이전트:** [agent name]
+- **위반 원칙:** [principle]
+- **위치:** [file:line]
+- **문제:** [description]
+- **현재 코드:**
+```typescript
+// 문제 코드
+```
+- **수정 방법:**
+```typescript
+// 개선 코드
+```
+
+---
+
+## Recommended Improvements (권장 개선)
+
+[같은 형식]
+
+---
+
+## Best Practices Found (잘하고 있음)
+
+- [Good practice 1] - [file:line] (에이전트)
+- [Good practice 2] - [file:line] (에이전트)
+
+---
+
+## 에이전트별 상세 결과
+
+### Fundamentals - 가독성
+[발견사항 요약]
+
+### Fundamentals - 예측 가능성
+[발견사항 요약]
+
+### Fundamentals - 응집도
+[발견사항 요약]
+
+### Fundamentals - 결합도
+[발견사항 요약]
+
+### React 상태관리 (React 프로젝트만)
+[발견사항 요약]
+
+---
+
+## Metrics
+
+### 원칙별 현황
+
+| 원칙 | Critical | Recommended | Best Practices |
+|------|----------|-------------|----------------|
+| 가독성 | N | N | N |
+| 예측 가능성 | N | N | N |
+| 응집도 | N | N | N |
+| 결합도 | N | N | N |
+| 상태관리 | N | N | N |
+
+### 상태 배치 현황 (React 프로젝트만)
+
+| 카테고리 | 개수 | 적절 | 부적절 |
+|----------|------|------|--------|
+| useState | N | N | N |
+| Context API | N | N | N |
+| 전역 스토어 | N | N | N |
+| 서버 상태 | N | N | N |
+```
+
+## 사용 예시
+
+```bash
+# 전체 프로젝트 리뷰
+/fundamentals-review
+
+# 특정 경로 리뷰
+/fundamentals-review src/components
+```
+
+## 중요 사항
+
+- **병렬 실행** - 5개 에이전트를 동시에 실행하여 빠르게 분석
+- **React 자동 감지** - React 프로젝트가 아니면 상태관리 리뷰 생략
+- **file:line 참조 보존** - 실행 가능한 피드백을 위해 필수
+- **한국어 출력** - 최종 리포트는 한국어로
+- **AI attribution 금지** - "Generated by AI" footer 추가 금지
+- **결과 파일 저장** - 최종 리포트를 `fundamentals-review.md` 파일로 저장 (이미 존재하면 `---` 구분선과 함께 하단에 추가)

package/commands/review-pr.md

@@ -25,6 +25,7 @@ Task 도구를 통해 다음 전문 에이전트를 사용할 수 있습니다:
 | `fundamentals-coupling` | Toss Fundamentals - 결합도 |
 | `refactor-analyzer` | 코드 중복, 복잡성, 추상화 기회, 코드 스멜 |
 | `junior-checker` | 주니어 개발자 관점 가독성, 네이밍, 복잡도 |
+| `react-state-reviewer` | React 상태관리 (상태 성질 기반 배치, Context 오용, 5단계 에스컬레이터) |
 | `react-performance-optimizer` | React 리렌더, 메모이제이션, 훅 최적화 |
 | `react-principles-reviewer` | React 개발 원칙 (응집도/명시성, Props 관리, 네이밍, 부수효과, AsyncBoundary) |
 | `maintainable-code-reviewer` | 유지보수성 (UI-코드 1:1 대응, 분리의 4원칙, 추상화 원칙) |
@@ -142,6 +143,16 @@ Skill은 사용자 설치에 따라 다르며 추가 리뷰 가이드라인/컨
    [리뷰 관점]
    네이밍, 함수 복잡도, 주석, 구조, 타입, 학습 곡선"
 
+   Task(react-state-reviewer): "PR #<PR번호>의 상태관리 패턴을 리뷰해주세요.
+
+   [작업 순서]
+   1. `gh pr view <PR번호>`로 PR 정보 확인
+   2. `gh pr diff <PR번호>`로 전체 변경사항 확인
+   3. 필요 시 관련 파일 Read
+
+   [리뷰 관점]
+   상태 성질(수명/범위/빈도) 기반 배치 적절성, Context 오용, 5단계 에스컬레이터 준수, 서버/클라이언트 상태 분리"
+
    Task(react-performance-optimizer): "PR #<PR번호>에서 React 성능 이슈를 찾아주세요.
 
    [작업 순서]

package/docs/BUILDER_GUIDE.md

@@ -54,6 +54,7 @@ Builder가 자동으로:
 | `fundamentals-predictability` | Toss Fundamentals - 예측 가능성 |
 | `fundamentals-cohesion` | Toss Fundamentals - 응집도 |
 | `fundamentals-coupling` | Toss Fundamentals - 결합도 |
+| `react-state-reviewer` | React 상태관리 (상태 성질 기반 배치, Context, 전역 상태) |
 | `react-performance-optimizer` | React 성능 최적화 |
 | `react-principles-reviewer` | React 개발 원칙 (응집도/명시성, Props 관리, 네이밍, 부수효과) |
 | `maintainable-code-reviewer` | 유지보수성 (UI-코드 1:1 대응, 분리의 4원칙) |

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "binary-agents",
-  "version": "1.3.0",
+  "version": "1.3.2",
   "description": "Claude Code subagents and slash commands collection with sync CLI tool",
   "type": "module",
   "main": "src/sync.js",