convention-check-hd

Prerequisites

설정 파일

• .hyeondong-config.json (프로젝트 루트): conventions 배열에서 적용할 컨벤션 목록을 참조한다.
• 이 파일이 없으면 기본값 (default-conventions)으로 동작한다.

--init (컨벤션 선택)

$ARGUMENTS가 --init이면 아래 절차를 실행하고 종료한다:

1. 사용 가능한 컨벤션 목록 제시: 플러그인 내 컨벤션 스킬과 프로젝트의 CLAUDE.md를 탐색하여 목록을 구성한다.

   "어떤 컨벤션을 적용할까요? (복수 선택 가능, 쉼표 구분)"

   플러그인 내장:

   1. default-conventions — React/Next.js/TypeScript 가이드라인

   프로젝트: 2. CLAUDE.md — 프로젝트 아키텍처 컨벤션

   예: 1,2 (전체) 또는 1 (기본만)

2. 유저 선택 수집: AskUserQuestion으로 선택을 받는다.

3. 설정 파일 업데이트: .hyeondong-config.json의 conventions 배열을 업데이트한다.

   {
     "conventions": [
       { "name": "default-conventions", "source": "plugin", "skill": "hyeondongs-harness:default-conventions-hd" },
       { "name": "CLAUDE.md", "source": "project", "path": "CLAUDE.md" }
     ]
   }
   

4. 결과 보고:

   "컨벤션 설정 완료. 적용 컨벤션: [선택 목록]"

--doctor (상태 진단)

$ARGUMENTS가 --doctor이면 아래 항목을 점검하고 결과를 보고한 뒤 종료한다:

## Convention Check — Doctor

| 항목 | 상태 | 비고 |
|------|------|------|
| .hyeondong-config.json | OK / MISSING | conventions 배열 확인 |
| default-conventions 스킬 | OK / MISSING | 플러그인 스킬 확인 |
| CLAUDE.md | OK / MISSING | 프로젝트 루트 확인 |
| 적용 컨벤션 목록 | [목록] | 현재 설정 표시 |

---

Execution

설정 파일 로드

1. 프로젝트 루트에서 .hyeondong-config.json을 읽는다.
2. conventions 배열이 없으면 기본값으로 진행: default-conventions

컨벤션 검사

설정된 각 컨벤션에 대해 위배 사항을 검사하고 보고한다:

• source: "plugin": 해당 스킬의 내용을 기준으로 코드를 검사한다.
• source: "project": 해당 파일의 내용을 기준으로 코드를 검사한다.

이전 세션 변경 사항 검증

현재 세션의 변경뿐 아니라, git blame으로 이전 세션에서 변경된 코드도 컨벤션 준수 여부를 검증한다:

1. git diff에서 변경된 파일 목록을 추출한다.
2. 각 파일의 git blame을 확인하여 최근 변경된 라인을 식별한다.
3. 이전 세션의 변경(현재 커밋 범위 밖)이라도 컨벤션 위반이 있으면 [PREV_SESSION] 태그로 보고한다.
4. 단, 이전 세션 위반은 자동 수정하지 않고 보고만 한다 (유저 판단에 위임).

[Assumption] 태그 누락 검사

Spec(Technical Spec 또는 유저 지시)에 명시되지 않은 동작 변경이 코드에 존재하는지 검사한다:

1. git diff에서 새로 추가/변경된 비즈니스 로직을 추출한다.
2. 해당 변경이 Spec의 요구사항에 직접 대응하는지 확인한다.
3. 대응하지 않는 변경(e.g. 추가 필터, 정렬 변경, 상태 체크 추가 등)에 [Assumption] 주석 또는 커밋 메시지 태그가 없으면 위반으로 보고한다.

외부 패키지 Import 규칙

변경된 파일에 새로운 외부 패키지 import가 추가된 경우, 프로젝트 내 기존 사용 패턴과 일치하는지 자동 검사한다:

1. git diff에서 새로 추가된 import 라인을 추출한다.
2. react, next, 프로젝트 내부 경로(@/, ~/, ../)는 제외한다.
3. 남은 외부 패키지에 대해 Grep으로 프로젝트 내 기존 사용 여부를 확인한다:
   • 기존에 사용 중: 기존 import 방식(alias 등)과 일치하는지 확인
   • 프로젝트 최초 도입: [NEW_DEPENDENCY]로 표기하고 위반으로 보고 (의도적 도입인지 확인 필요)

useMemo/useCallback 의존성 배열 검사

변경된 파일에서 useMemo, useCallback, useEffect의 의존성 배열을 자동 검사한다:

1. git diff에서 useMemo(, useCallback(, useEffect(가 포함된 변경 라인을 추출한다.
2. 각 훅의 콜백 내에서 참조하는 외부 변수(state, props, 함수)를 파악한다.
3. 의존성 배열([])에 해당 변수가 포함되어 있는지 검증한다.

위반 유형	심각도	설명
빈 배열 [] + 외부 state 참조	ERROR	stale closure 발생. 의존성 추가 필수
의존성 누락 (참조하지만 배열에 없음)	ERROR	값이 업데이트되지 않음
불필요한 의존성 (배열에 있지만 참조 안 함)	WARN	불필요한 리렌더링 유발 가능
객체/배열 리터럴이 의존성에 포함	WARN	매 렌더링 새 참조 → 무한 루프 위험
eslint-disable-next-line react-hooks/exhaustive-deps	WARN	비활성화 사유를 주석으로 명시했는지 확인

위반 시 [HOOKS_DEPS] 태그로 보고:

"UserList.tsx:25 — useCallback 의존성 배열에 searchTerm이 누락되어 있습니다. stale closure 위험."

컴포넌트 구조 검사

.hyeondong-config.json의 componentPattern에 따라:

• feature-based: 컴포넌트가 올바른 feature 디렉토리에 배치되었는지
• atomic: atoms/molecules/organisms 분류가 적절한지
• flat: components/ 하위에 배치되었는지

---

출력 형식

## Convention Check 결과

### 컨벤션 위반
| # | 컨벤션 | 파일 | 위반 내용 | 심각도 |
|---|--------|------|----------|--------|
| 1 | default-conventions | src/... | [내용] | ERROR / WARN |

### [Assumption] 태그 누락
| # | 파일 | 변경 내용 | 태그 필요 여부 |
|---|------|----------|-------------|

### 외부 패키지
| # | 패키지 | 파일 | 상태 |
|---|--------|------|------|
| 1 | lodash | src/... | [NEW_DEPENDENCY] |

### 종합
- **위반 사항**: N개 (ERROR: A, WARN: B)
- **상태**: CLEAN / VIOLATIONS FOUND