kdyconvention — 코드 컨벤션 검증 + 조건부 자기반성

글로벌 코딩 컨벤션을 규칙 기반으로 능동 스캔하고, 심각도에 따라 자동 수정 또는 에이전트 위임을 수행하는 스킬입니다.

레이어 위치

Layer 3 (메타)     : manage-skills          → verify-* 스킬 자체를 유지보수
Layer 2 (오케스트라): verify-implementation  → 프로젝트별 verify-* 스킬 순차 실행
Layer 1 (도메인)    : verify-api, verify-ui  → 프로젝트별 도메인 규칙 검증
Layer 0 (컨벤션)    : kdyconvention [이 스킬] → 글로벌 코딩 컨벤션 검증 + 자기반성

이중 운용 모드

모드	호출 방식	설명
독립 실행	`/kdyconvention` 직접 호출	전체 Phase 0~6 실행, 자기반성 발동 포함
오케스트라 편입	`verify-implementation`이 자동 탐색	프로젝트 `.claude/skills/verify-convention/SKILL.md` 생성 시 편입, Phase 4 비활성

인수 처리

사용자가 제공한 인수: $ARGUMENTS

인수	설명
(없음)	전체 범위, 전체 레이어, 모든 Phase 실행
`--scope <path>`	특정 경로만 검증
`--dry-run`	스캔만 실행, 수정 없음
`--fix-only`	자동 수정 가능 항목만 처리
`--stack <name>`	스택 강제 지정 (nextjs, react-vite, react, python, java-spring)

기본 경로

GENERAL_PRO 결정 순서:
1. 환경변수 GENERAL_PRO_PATH
2. CWD가 00-general-pro* 내부이면 해당 루트
3. ~/{develop,dev}/00-general-pro-web 존재 탐색
4. 실패 시 AskUserQuestion: "00-general-pro-web 경로를 입력해주세요"

GENERAL_PRO = {결정된 경로}
RULE_REGISTRY = $GENERAL_PRO/03-skills/kdyconvention/references/rule-registry.md
VIOLATION_MATRIX = $GENERAL_PRO/03-skills/kdyconvention/references/violation-matrix.md
CODING_STACKS = $GENERAL_PRO/01-dev-rules-system/02-project-template/docs/rules/coding-stacks/
REUSABLE_RULES = $GENERAL_PRO/docs/rules/reusable-code.md
SKILL_CONVENTION = $GENERAL_PRO/docs/rules/skill-convention.md
AGENT_CONVENTION = $GENERAL_PRO/docs/rules/agent-convention.md

Phase 0: 컨텍스트 탐지

프로젝트 스택을 자동 감지하고 활성 규칙 레이어를 결정합니다.

0-1. 프로젝트 루트 파일 탐색

Glob: package.json, pyproject.toml, pom.xml, build.gradle, go.mod
Glob: CLAUDE.md, docs/rules/**/*.md
Glob: next.config.*, vite.config.*, tsconfig.json, requirements.txt

0-2. 스택 판별 (우선순위 순)

조건	스택
package.json + next.config.*	`nextjs`
package.json + vite.config.*	`react-vite`
package.json + React 의존성	`react`
pyproject.toml 또는 requirements.txt	`python`
pom.xml 또는 build.gradle	`java-spring`
그 외	`unknown` → AskUserQuestion으로 사용자에게 질문

--stack <name> 인수가 있으면 자동 감지를 건너뛰고 지정값을 사용합니다.

0-3. 활성 규칙 레이어 결정

레이어	조건	규칙 소스
Layer 0 (하드룰)	항상 활성	이 SKILL.md 내장 (재정의 불가)
Layer 1 (글로벌)	항상 활성	`01-dev-rules-system/01-global-rules/CLAUDE.md`
Layer 2 (스택별)	스택 감지 시	`coding-stacks/{스택}.md`
Layer 3 (재사용 코드)	00 general-pro 내부일 때	`docs/rules/reusable-code.md`
Layer 4 (프로젝트 고유)	`docs/rules/` 존재 시	`{프로젝트}/docs/rules/` + `{프로젝트}/CLAUDE.md`
Layer 5 (스킬/에이전트)	00 general-pro 내부이거나 `--scope 03-skills/` 또는 `--scope 04-agents/` 지정 시	`docs/rules/skill-convention.md` + `docs/rules/agent-convention.md`

충돌 해결: Layer 4 > Layer 3 > Layer 2 > Layer 1. 단, Layer 0은 재정의 불가.

0-4. 인수 파싱

$ARGUMENTS에서 --scope, --dry-run, --fix-only, --stack 추출. 인수 없으면 전체 범위, 전체 레이어.

0-4-B. 스캔 범위 예측

소스 파일 수 = Glob *.ts *.tsx *.py *.js *.jsx 카운트 (node_modules, .next, dist, __pycache__, .venv 제외)

if 소스 파일 수 > 200 AND --scope 미지정:
    AskUserQuestion:
      question: "소스 파일 {N}개 감지. 스캔 범위를 선택하세요."
      options:
        - "전체 스캔" → 모든 소스 파일 대상
        - "src/ 디렉토리만 (권장)" → --scope src/ 자동 적용
        - "최근 변경 파일만" → git diff HEAD~3 --name-only 결과만 대상
else:
    → 기존 동작 유지 (--scope 지정값 또는 전체)

0-5. 이전 세션 패턴 참조

Read: docs/logs/YYYY-MM.md (현재 월)

## [날짜] kdyconvention 섹션에서 "반복 위반 파일" 목록을 추출합니다. 존재하면 Phase 1 스캔 우선 대상으로 설정하고 사용자에게 사전 경고합니다:

⚠️ 이전 세션에서 반복 위반된 파일이 있습니다:
- src/lib/api.ts (TS-01 any 타입 — 2회 연속)
우선 스캔 대상으로 설정합니다.

파일이 없거나 kdyconvention 기록이 없으면 이 단계를 건너뜁니다.

표시:

## kdyconvention 컨텍스트 탐지

- 프로젝트: {프로젝트명}
- 스택: {감지된 스택}
- 활성 레이어: Layer 0 + 1 + 2 ({스택}) [+ 3] [+ 4]
- 스캔 범위: {전체 | --scope 경로}
- 모드: {전체 | --dry-run | --fix-only}

스캔을 시작합니다...

Phase 1: 스캔 (Grep 기반 위반 탐지)

활성 레이어의 모든 규칙 패턴으로 소스 코드를 스캔합니다. 상세 패턴은 references/rule-registry.md를 참조합니다.

1-1. rule-registry.md 로드

Read: $RULE_REGISTRY

활성 레이어에 해당하는 규칙만 필터링합니다.

1-2. 규칙별 Grep/Glob/Bash 실행

각 규칙의 탐지 방법에 따라 도구를 실행합니다:

Grep 기반 규칙 (대부분):

Grep: pattern="{규칙 패턴}", glob="{대상 glob}", output_mode="content"

Glob 기반 규칙 (파일명 컨벤션):

Glob: pattern="{대상 패턴}"
→ 결과를 패턴 매칭으로 검증

Bash 기반 규칙 (줄 수 카운트 등):

Bash: wc -l {파일} 또는 madge --circular {경로}

Layer 5 전용 (.md 파일 대상, SK-/AG- 규칙):

Grep: pattern="^name:", glob="03-skills/*/SKILL.md", output_mode="files_with_matches"
Grep: pattern="## 관련 스킬", glob="03-skills/*/SKILL.md", output_mode="files_with_matches"
Grep: pattern="## 호출 경로", glob="04-agents/*.md", output_mode="files_with_matches"
Grep: pattern="<example>", glob="04-agents/*.md", output_mode="count"

중요: --scope 지정 시 해당 경로 내부만 스캔합니다.

1-3. 면제 처리

각 규칙에 정의된 면제 패턴을 적용합니다:

테스트 파일 (*.test.*, *.spec.*, __tests__/)
설정 파일 (*.config.*, .env.example)
타입 정의 파일 (*.d.ts)
shadcn 원본 경로 (TS-02 export default 등)
rule-registry.md의 면제 컬럼에 명시된 패턴

1-4. 스캔 결과 집계

## Phase 1: 스캔 결과

| # | 규칙 | 파일 | 라인 | 발견 내용 | 심각도 |
|---|------|------|------|----------|--------|
| 1 | H-02 | src/lib/api.ts | 42 | console.log(...) | HIGH |
| 2 | TS-01 | src/types/user.ts | 15 | data: any | IMPORTANT |
| ... | | | | | |

총 N건 발견 (CRITICAL: X, HIGH: Y, IMPORTANT: Z, MINOR: W)

Phase 2: 분석 (심각도 분류 + 임계값 판정)

위반을 분류하고 자기반성 발동 여부를 결정합니다. 상세 매트릭스는 references/violation-matrix.md를 참조합니다.

2-1. 심각도 집계

CRITICAL_COUNT = [C] 건수
HIGH_COUNT     = [H] 건수
IMPORTANT_COUNT = [I] 건수
MINOR_COUNT    = [M] 건수
TOTAL_COUNT    = 전체 건수

2-2. 자기반성 발동 판정 (임계값 매트릭스)

violation-matrix.md의 매트릭스에 따라 발동 액션을 결정합니다:

조건	발동 액션
CRITICAL ≥ 1 (보안 패턴: H-01, H-03, TS-05)	→ 자동: `security-reviewer` 에이전트
CRITICAL ≥ 1 (비보안: H-04 순환 의존성)	→ 추천: `code-reviewer` 에이전트
HIGH ≥ 3	→ 추천: `code-reviewer` 에이전트
IMPORTANT ≥ 5	→ 추천: 자동 수정 실행
MINOR만	보고서 출력, 에이전트 미발동
전체 0건	통과 보고서 출력 후 Phase 6으로 이동

2-3. 자동 수정 가능/불가 분류

자동 수정 가능 (AUTO_FIX_LIST):

규칙	수정 방법
H-02	`console.log` / `console.warn` / `console.error` 행 제거
TS-02	`export default` → named export 변환 (단순 케이스)
TS-03	`import { type X }` → `import type { X }` 변환
PY-02	`Optional[X]` → `X \| None` 변환
RC-02	따옴표 통일 (shadcn: 큰따옴표, 커스텀: 작은따옴표)

수동 필요 (MANUAL_LIST) — 위치 + 권장 조치만 안내:

규칙	사유
H-01	환경변수 노출 — 맥락 판단 필요
H-03	하드코딩 URL/시크릿 — 비즈니스 판단 필요
H-04	순환 의존성 — 아키텍처 결정 필요
G-01	1000줄 초과 — 리팩토링 전략 필요
G-02	import 15개 초과 — 모듈 분리 전략 필요
TS-01	any 타입 — 적절한 타입 추론 필요
TS-05	dangerouslySetInnerHTML — 보안 판단 필요
TS-06	props 10개 초과 — 컴포넌트 분리 필요
PY-01	독스트링 누락 — 내용 작성 필요
PY-03	print() 사용 — logger 전환 필요
JA-01	Controller 비즈니스 로직 — 서비스 분리 필요
RC-01	JSDoc 헤더 누락 — 메타데이터 작성 필요

표시:

## Phase 2: 분석 결과

### 심각도 분포
| 심각도 | 건수 |
|--------|------|
| CRITICAL | X |
| HIGH | Y |
| IMPORTANT | Z |
| MINOR | W |

### 발동 판정
- 에이전트 발동: {security-reviewer / code-reviewer / 없음}
- 자동 수정 가능: N건
- 수동 필요: M건

Phase 3: 사용자 확인 게이트

쓰기 전 반드시 사용자 승인을 받습니다.

3-1. 전체 0건인 경우

모든 컨벤션 검사를 통과했습니다! Phase 6으로 이동합니다.

Phase 6으로 바로 이동합니다.

3-2. 위반 발견 시

AskUserQuestion으로 선택지를 제시합니다:

선택지	설명
전체 자동 수정 실행	AUTO_FIX_LIST N건 수정 후 재검증
수정 없이 보고서만 출력	--dry-run과 동일 효과
에이전트 추가 실행	code-reviewer / security-reviewer 선택
개별 항목 선택	항목별 수정 여부 결정

--dry-run 모드에서는 이 Phase를 건너뛰고 Phase 6으로 이동합니다. --fix-only 모드에서는 "전체 자동 수정 실행"이 자동 선택됩니다.

Phase 4: 자기반성 실행 (조건부 발동)

Phase 2 판정 결과와 Phase 3 사용자 선택에 따라 에이전트를 호출합니다.

중요: 이 Phase는 독립 실행 모드에서만 활성화됩니다. verify-implementation 편입 시 비활성.

4-1. 자동 수정 실행

사용자가 자동 수정을 승인한 경우, AUTO_FIX_LIST 순서대로 Edit 도구를 실행합니다.

## 자동 수정 진행 중...

- [1/N] H-02: src/lib/api.ts:42 — console.log 제거 ✓
- [2/N] TS-03: src/types/user.ts:3 — import type 변환 ✓
- ...

N건 자동 수정 완료.

4-2. security-reviewer 에이전트 자동 발동

CRITICAL 보안 패턴(H-01, H-03, TS-05) 감지 시 자동 실행합니다:

Task 도구 호출:
  subagent_type: code-reviewer (security-reviewer 에이전트 정의 참조)
  prompt: |
    다음 파일에서 보안 위반이 탐지되었습니다. OWASP 기반 심층 분석을 수행해주세요.

    위반 파일 목록:
    {CRITICAL 보안 위반 파일:라인 목록}

    탐지된 패턴:
    {규칙 코드 + 발견 내용 요약}

에이전트 결과를 수신하여 Phase 6 보고서에 통합합니다.

4-3. code-reviewer 에이전트 발동

사용자가 에이전트 실행을 승인한 경우 실행합니다:

Task 도구 호출:
  subagent_type: code-reviewer
  prompt: |
    다음 파일에서 코딩 컨벤션 위반이 다수 발견되었습니다. 코드 품질 심층 분석을 수행해주세요.

    HIGH 이상 위반 파일 목록:
    {HIGH+ 위반 파일:라인 목록}

에이전트 결과를 수신하여 Phase 6 보고서에 통합합니다.

Phase 5: 재검증 루프

수정 후 동일 패턴을 재스캔하여 실제 개선을 확인합니다.

5-1. 재스캔 실행

LOOP_COUNT = 0
MAX_LOOP = 3
PREV_COUNT = Phase 1 총 위반 건수

수정된 파일만 대상으로 Phase 1 패턴을 재실행합니다.

5-2. 수렴 판정

NEW_COUNT = 재스캔 위반 건수

if NEW_COUNT == 0:
    → "모든 위반 해결" → Phase 6 (완전 통과)

if NEW_COUNT >= PREV_COUNT && LOOP_COUNT > 0:
    → "수렴 없음 — 추가 수정이 새 위반을 유발" → Phase 6

if LOOP_COUNT >= MAX_LOOP:
    → "최대 반복 초과 (3회)" → Phase 6

else:
    → LOOP_COUNT++
    → 잔여 위반 목록 표시
    → AskUserQuestion: "추가 수정을 진행할까요?"
    → 승인 시 Step 4-1 재실행 → 다시 재스캔

무한 루프 방지 3중 장치:

카운터 제한: MAX_LOOP = 3
수렴 판정: NEW_COUNT >= PREV_COUNT 시 중단
범위 고정: 루프 중 새 자동 수정 규칙 추가 없음

표시:

## Phase 5: 재검증 결과

| 반복 | 위반 건수 | 변화 |
|------|----------|------|
| 초기 | N | - |
| 1차 수정 후 | M | -X건 |
| 2차 수정 후 | K | -Y건 |

Phase 6: 최종 보고 + 아카이브

6-1. 최종 보고서 출력

## kdyconvention 검증 완료

### 결과 요약

| 항목 | 초기 | 최종 | 개선율 |
|------|------|------|--------|
| CRITICAL | N | N | N% |
| HIGH | N | N | N% |
| IMPORTANT | N | N | N% |
| MINOR | N | N | N% |
| **합계** | **N** | **N** | **N%** |

### 수정된 파일 (자동)
| # | 규칙 | 파일 | 수정 내용 |
|---|------|------|----------|

### 미해결 항목 (수동 필요)
| # | 규칙 | 파일:라인 | 문제 | 권장 조치 |
|---|------|----------|------|----------|

### 에이전트 실행 결과
(security-reviewer / code-reviewer 결과 통합, 있을 경우)

### 다음 권장 작업
- (미해결 항목 기반 구체적 권장사항)

6-2. 아카이브 (조건부)

CRITICAL 1개 이상 또는 HIGH 3개 이상인 경우 필수 기록, IMPORTANT 10개 이상인 경우 선택 기록으로 docs/logs/YYYY-MM.md에 append합니다:

## [YYYY-MM-DD] kdyconvention — {프로젝트명} ({스택})
- 레이어: Layer 0 + 1 + 2 ({스택}) [+ 3] [+ 4]
- 결과: C{N} / H{N} / I{N} / M{N}
- 자동 수정: {N}건
- 에이전트: {발동된 에이전트 또는 "없음"}
- 반복 위반 파일: {3회 이상 위반된 파일 목록}

docs/logs/ 디렉토리가 없으면 이 단계를 건너뜁니다 (00 general-pro 외부 프로젝트).

6-3. 전체 통과 시

## kdyconvention 검증 완료

모든 컨벤션 검사를 통과했습니다!

- 프로젝트: {프로젝트명}
- 스택: {스택}
- 활성 레이어: {레이어 목록}
- 스캔 대상: {파일 수}개 파일
- 위반: 0건

코드 리뷰 준비가 완료되었습니다.

Phase 6-B: verify-convention 스킬 생성 제안 (선택적)

프로젝트가 verify-implementation과 연동하려는 경우, 경량 verify-convention 스킬 생성을 제안합니다.

조건

if 프로젝트에 .claude/skills/ 구조가 존재하고
   .claude/skills/verify-convention/ 이 없으면:
    → AskUserQuestion: "프로젝트별 verify-convention 스킬을 생성할까요?"

승인 시 생성

현재 프로젝트 스택 기반 경량 verify 스킬을 .claude/skills/verify-convention/SKILL.md에 생성합니다.

생성되는 스킬의 구조:

---
name: verify-convention
description: 코딩 컨벤션 검증 (kdyconvention 파생)
---

# 코딩 컨벤션 검증

## Workflow

(현재 프로젝트 스택에 해당하는 Layer 0 + 2 규칙만 포함)

## Exceptions

(프로젝트 고유 면제 패턴)

## Related Files

(프로젝트 소스 파일 glob)

이후 /verify-implementation 실행 시 자동 편입됩니다.

Superpowers 연계

이 스킬 실행 중 아래 superpowers 원칙을 적용한다.

원칙	적용 시점	적용 방법
`verification-before-completion`	auto-fix 후	재스캔으로 위반 실제 해소 확인
`systematic-debugging`	auto-fix가 새 위반 유발 시	연쇄 위반 근본 원인 추적

예외사항

다음은 문제가 아닙니다:

면제 패턴에 해당하는 코드 — 테스트 파일, 설정 파일, 타입 정의 파일 등
shadcn 원본 컴포넌트 — TS-02(export default), RC-02(큰따옴표) 등 shadcn 경로 내부
주석 내 패턴 매칭 — 주석에서 console.log를 언급하는 것은 위반이 아님
스택과 무관한 레이어 규칙 — Python 프로젝트에서 TS 규칙 적용하지 않음
node_modules, .next, dist, pycache, .venv — 빌드/의존성 디렉토리 항상 제외

도구	역할	관계
`/kdygenesis`	메타 오케스트레이션	코드 생성 후마다 kdyconvention을 품질 게이트로 자동 호출
`code-reviewer`	코드 품질 심층 분석	kdyconvention이 HIGH 3+ 시 위임
`security-reviewer`	OWASP 보안 심층 분석	kdyconvention이 CRITICAL 보안 시 자동 위임
`verify-implementation`	verify-* 오케스트레이션	Phase 6-B로 연동 가능
`manage-skills`	verify-* 스킬 유지보수	verify-convention 생성 후 관리 대상
`kdyextract`	재사용 코드 추출	추출 전 kdyconvention 실행 권장
`/kdyselfreflection`	자기반성 + 체계 진화	01-dev-rules-system 규칙 수정 시 kdyconvention 검증 기반 변경 가능

사용 예시

# 전체 프로젝트 컨벤션 검증
/kdyconvention

# 특정 경로만 검증
/kdyconvention --scope src/components/

# 스캔만 실행 (수정 없음)
/kdyconvention --dry-run

# 자동 수정 가능 항목만 처리
/kdyconvention --fix-only

# 스택 강제 지정
/kdyconvention --stack python

# 재사용 코드 라이브러리 검증 (00 general-pro 내부)
/kdyconvention --scope 02-reusable-code/02-hooks/

kdyconvention

kdyconvention — 코드 컨벤션 검증 + 조건부 자기반성

레이어 위치

이중 운용 모드

인수 처리

기본 경로

Phase 0: 컨텍스트 탐지

0-1. 프로젝트 루트 파일 탐색

0-2. 스택 판별 (우선순위 순)

0-3. 활성 규칙 레이어 결정

0-4. 인수 파싱

0-4-B. 스캔 범위 예측

0-5. 이전 세션 패턴 참조

Phase 1: 스캔 (Grep 기반 위반 탐지)

1-1. rule-registry.md 로드

1-2. 규칙별 Grep/Glob/Bash 실행

1-3. 면제 처리

1-4. 스캔 결과 집계

Phase 2: 분석 (심각도 분류 + 임계값 판정)

2-1. 심각도 집계

2-2. 자기반성 발동 판정 (임계값 매트릭스)

2-3. 자동 수정 가능/불가 분류

Phase 3: 사용자 확인 게이트

3-1. 전체 0건인 경우

3-2. 위반 발견 시

Phase 4: 자기반성 실행 (조건부 발동)

4-1. 자동 수정 실행

4-2. security-reviewer 에이전트 자동 발동

4-3. code-reviewer 에이전트 발동

Phase 5: 재검증 루프

5-1. 재스캔 실행

5-2. 수렴 판정

Phase 6: 최종 보고 + 아카이브

6-1. 최종 보고서 출력

6-2. 아카이브 (조건부)

6-3. 전체 통과 시

Phase 6-B: verify-convention 스킬 생성 제안 (선택적)

조건

승인 시 생성

Superpowers 연계

예외사항

관련 스킬/에이전트

사용 예시