@choblue/claude-code-toolkit 1.2.3 → 1.2.5

package/.claude/.project-map-cache

@@ -1 +1 @@
-3b3477495f8b6aeafca6aa34cc433d15ccdd0622
+e48648429d9686e998960a4fddaa11593ee785d5

package/.claude/CLAUDE.md

@@ -32,7 +32,30 @@ Claude는 작업 시작 전 반드시 이 규칙을 따라야 한다.
 
 ---
 
-## 2. 티어별 워크플로우
+## 2. 점진적 구현 원칙
+
+**"한 번에 하나, 완전하게"** — 범위를 넓게 잡고 80%로 끝내지 말고, 좁게 잡고 100%로 완성한다.
+
+### 작업 분해
+- 요구사항을 **가장 작은 배포 가능 단위(smallest deliverable unit)**로 쪼갠다
+- 한 단위를 **완전히 끝낸 후** 다음 단위로 이동한다
+- 에이전트 1회 호출 당 **파일 3개 이하**를 원칙으로 한다
+
+### 예시: "게시판 만들어줘"
+```
+Step 1: Entity + API (목록 조회만) → 확인
+Step 2: 목록 UI → 확인
+Step 3: 생성 API + UI → 확인
+Step 4: 수정/삭제 → 확인
+```
+
+### 금지
+- 한 번의 계획에 기능 전체를 담아 한꺼번에 구현하는 것
+- 에이전트에 5개 이상 파일 동시 생성/수정을 위임하는 것
+
+---
+
+## 3. 티어별 워크플로우
 
 ### S 티어 (trivial)
 Main Agent가 직접 처리한다. 서브에이전트 위임 불필요.
@@ -42,15 +65,15 @@ Main Agent가 직접 처리한다. 서브에이전트 위임 불필요.
 ### M 티어 (moderate)
 TDD/Review를 생략하고 핵심 단계만 수행한다.
 1. **Planning**: 요구사항 정리, 필요 시 `explore`로 탐색
-2. **Implementation**: `code-writer` 에이전트에 구현 위임
+2. **Implementation**: `code-writer` 에이전트에 구현 위임 (단위별로 나눠 호출)
 3. **Commit**: `git-manager`로 커밋/PR 생성
 
 ### L 티어 (complex)
-파일 기반 설계 후 구현한다.
+파일 기반 설계 후 **단위별로** 구현한다.
 1. **Research**: `explore`로 탐색 → `research.md` 작성 (관련 코드 분석, 제약 조건)
-2. **Plan**: `plan.md` 작성 (접근 방식, 변경 파일, 트레이드 오프, 작업 순서)
+2. **Plan**: `plan.md` 작성 (접근 방식, 변경 파일, 트레이드 오프, **단위별 작업 순서**)
 3. **주석 사이클**: 사용자가 plan.md에 메모 → 반영 → **승인 전까지 구현 금지**
-4. **Implementation + Test**: `implementer`에 plan.md 전달하여 구현+테스트 동시 위임
+4. **Implementation + Test**: plan.md의 각 단위를 순서대로 `implementer`에 위임 (단위당 1회 호출)
 5. **Review**: `code-reviewer`로 리뷰 → `git-manager`로 커밋/PR
 
 ### 풀스택 작업 (FE + BE 동시 변경)
@@ -58,7 +81,7 @@ TDD/Review를 생략하고 핵심 단계만 수행한다.
 
 ---
 
-## 3. 문서 참조 가이드
+## 4. 문서 참조 가이드
 
 ### Agents (서브에이전트 프롬프트)
 - `.claude/agents/explore.md` - 코드베이스 탐색 전문가
@@ -98,7 +121,7 @@ TDD/Review를 생략하고 핵심 단계만 수행한다.
 
 ---
 
-## 4. 프로젝트별 오버라이드
+## 5. 프로젝트별 오버라이드
 
 프로젝트 루트에 `CLAUDE.md`가 있으면 이 글로벌 규칙보다 우선한다.
 프로젝트별 규칙은 글로벌 규칙을 확장하되, 충돌 시 프로젝트 규칙을 따른다.

package/.claude/skills/Planning/SKILL.md

@@ -68,10 +68,29 @@ M 티어는 파일 없이 채팅에서 간단히 계획을 제시한다:
 2. [작업] → [담당 에이전트]
 ```
 
-## 4. 작업 분해 체크리스트
+## 4. 작업 분해 원칙
 
+**"한 번에 하나, 완전하게"** — 전체를 한꺼번에 80%로 끝내지 말고, 단위별로 100% 완성한다.
+
+### 분해 기준
+- **가장 작은 배포 가능 단위(smallest deliverable unit)**로 쪼갠다
+- 각 단위는 독립적으로 동작하고 확인할 수 있어야 한다
+- 에이전트 1회 호출 당 파일 3개 이하를 원칙으로 한다
+
+### 분해 체크리스트
 - [ ] 사용자가 원하는 최종 결과물은?
+- [ ] 가장 작은 동작 단위로 쪼갰는가?
+- [ ] 각 단위가 독립적으로 확인 가능한가?
 - [ ] 변경되는 레이어는? (UI / API / Domain / DB)
-- [ ] 기존 코드에 영향을 주는 범위는?
 - [ ] 작업 간 순서 의존성이 있는가?
-- [ ] 외부 의존성이 있는가? (패키지 설치, DB 마이그레이션 등)
+- [ ] 외부 의존성이 있는가? (패키지 설치, DB 마이그레이션 등)
+
+### plan.md 작업 순서 작성 예시
+```markdown
+## 작업 순서 (단위별)
+1. Entity + Repository 정의 → implementer-be (파일 2개)
+2. 목록 조회 API → implementer-be (파일 2개) → **확인**
+3. 목록 UI → implementer-fe (파일 2~3개) → **확인**
+4. 생성 API + UI → implementer-be → implementer-fe → **확인**
+5. 수정/삭제 → implementer-be → implementer-fe → **확인**
+```

package/.claude/skills/React/SKILL.md

@@ -313,7 +313,82 @@ function UserPage({ userId }: UserPageProps) {
 
 ---
 
-## 9. 금지 사항
+## 9. 접근성 (a11y)
+
+### 시맨틱 HTML 사용
+- 클릭 가능한 요소는 반드시 `<button>` 또는 `<a>`를 사용한다
+- `<div onClick>`, `<span onClick>`을 금지한다
+
+```typescript
+// Bad
+<div onClick={handleDelete} className="cursor-pointer">삭제</div>
+
+// Good
+<button type="button" onClick={handleDelete}>삭제</button>
+```
+
+### 아이콘 버튼에 aria-label 필수
+
+```typescript
+// Bad - 스크린 리더가 내용을 알 수 없음
+<button onClick={onClose}><XIcon /></button>
+
+// Good
+<button onClick={onClose} aria-label="닫기"><XIcon /></button>
+```
+
+### 이미지에 alt, width, height 필수
+
+```typescript
+// Bad
+<img src={user.avatar} />
+
+// Good
+<img src={user.avatar} alt={`${user.name} 프로필`} width={40} height={40} />
+```
+
+### focus-visible 보장
+- `outline: none`을 사용할 때 반드시 `focus-visible` 대체 스타일을 제공한다
+
+```typescript
+// Bad - 포커스 표시 완전 제거
+<button className="outline-none">
+
+// Good - 키보드 포커스 시 표시
+<button className="outline-none focus-visible:ring-2 focus-visible:ring-blue-500">
+```
+
+### 폼 접근성
+- 모든 입력 필드에 `<label>` 또는 `aria-label`을 연결한다
+- 적절한 `type`, `inputMode`, `autoComplete` 속성을 사용한다
+- 붙여넣기(`onPaste`)를 차단하지 않는다
+
+---
+
+## 10. UX 패턴
+
+### 파괴적 액션에 확인 단계
+- 삭제, 초기화 등 되돌릴 수 없는 동작에는 확인 UI를 추가한다
+
+### URL 파라미터와 UI 상태 동기화
+- 탭, 필터, 페이지 등 공유 가능한 UI 상태는 URL 파라미터에 반영한다
+
+```typescript
+// Bad - 새로고침하면 상태 소실
+const [tab, setTab] = useState('overview');
+
+// Good - URL에 상태 반영 (deep-link 가능)
+const [searchParams, setSearchParams] = useSearchParams();
+const tab = searchParams.get('tab') ?? 'overview';
+```
+
+### 대규모 리스트 가상화
+- 50개 이상의 항목을 렌더링할 때는 가상화 라이브러리를 사용한다
+- `@tanstack/react-virtual`, `react-window` 등을 활용한다
+
+---
+
+## 11. 금지 사항
 
 - `any` 타입 사용 금지
 - 인라인 스타일(`style={{}}`) 사용 금지 - 프로젝트 스타일링 방식을 따른다
@@ -325,4 +400,8 @@ function UserPage({ userId }: UserPageProps) {
 - `useEffect` 내에서 상태 동기화 로직 작성 금지 (파생값으로 처리)
 - Props drilling이 3단계 이상일 때 Context 또는 상태 관리 라이브러리 미사용 금지
 - 서버 상태(API 데이터)를 `useState` + `useEffect`로 관리 금지 (서버 상태 라이브러리 사용)
-- 각 함수/컴포넌트마다 try-catch 남발 금지 (에러 경계에서 일괄 처리)
+- 각 함수/컴포넌트마다 try-catch 남발 금지 (에러 경계에서 일괄 처리)
+- `<div onClick>`, `<span onClick>` 금지 (`<button>` 또는 `<a>` 사용)
+- 아이콘 버튼에 `aria-label` 누락 금지
+- `outline: none` 단독 사용 금지 (`focus-visible` 대체 필수)
+- 입력 필드에 `onPaste` 차단 금지

package/.claude/skills/TailwindCSS/SKILL.md

@@ -361,7 +361,43 @@ export function Button({ variant, size, className, ...props }: ButtonProps) {
 
 ---
 
-## 8. 금지 사항
+## 8. 트랜지션 & 모션
+
+### transition 속성 명시
+- `transition-all` 사용을 금지한다 - 변경되는 속성만 명시한다
+- 불필요한 속성까지 트랜지션되면 성능이 저하된다
+
+```typescript
+// Bad - 모든 속성에 트랜지션
+<button className="transition-all">
+
+// Good - 필요한 속성만
+<button className="transition-colors">
+<div className="transition-[transform,opacity]">
+```
+
+### prefers-reduced-motion 존중
+- 애니메이션/트랜지션이 있는 요소에는 `motion-reduce:` 변형을 고려한다
+
+```typescript
+// 모션 감소 선호 시 애니메이션 비활성화
+<div className="animate-bounce motion-reduce:animate-none">
+<div className="transition-transform motion-reduce:transition-none">
+```
+
+### 다크 모드 color-scheme
+- 다크 모드 지원 시 `color-scheme: dark`를 설정하여 네이티브 UI(스크롤바, 입력 필드 등)도 다크 테마에 맞춘다
+
+```css
+/* app.css */
+.dark {
+  color-scheme: dark;
+}
+```
+
+---
+
+## 9. 금지 사항
 
 - 인라인 `style={{}}` 사용 금지 - Tailwind 유틸리티 클래스를 사용한다
 - 임의값(arbitrary values) 남용 금지 - `w-[137px]` 같은 임의값은 최소화한다
@@ -373,6 +409,7 @@ export function Button({ variant, size, className, ...props }: ButtonProps) {
 - Tailwind 기본 테마 토큰 삭제 금지 - `@theme`에서 필요한 토큰만 추가한다
 - 사용하지 않는 커스텀 색상/간격 정의 금지 - 실제 사용하는 값만 정의한다
 - `tailwind.config.ts` 사용 금지 - v4에서는 CSS `@theme`으로 설정한다
+- `transition-all` 사용 금지 - 변경되는 속성만 명시한다 (`transition-colors`, `transition-opacity` 등)
 - 클래스 문자열 동적 생성 금지 - Tailwind의 JIT가 감지하지 못한다
 
 ```typescript

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@choblue/claude-code-toolkit",
-  "version": "1.2.3",
+  "version": "1.2.5",
   "description": "Claude Code 서브에이전트 위임 툴킷 - npx로 바로 설치",
   "bin": {
     "claude-code-toolkit": "bin/cli.js"