인수인계서 — 세션 22 (Development Protocol 통일 — 스킬/에이전트 컨벤션)
작성일: 2026-02-18 이전 세션: session21
작업 요약
03-skills/와 04-agents/의 작성 표준이 없어 품질 편차가 발생하던 문제를 해결하기 위해, 공식 컨벤션 2개를 신규 생성하고, kdyconvention에 Layer 5 강제 장치를 추가하고, 기존 스킬/에이전트 11개를 보정했다.
수정 파일 (17개)
| # | 파일 | 변경 내용 |
|---|---|---|
| 1 | docs/rules/skill-convention.md | 신규 — 스킬 작성 바인딩 규칙 7 Section |
| 2 | docs/rules/agent-convention.md | 신규 — 에이전트 작성 바인딩 규칙 4 Section |
| 3 | 03-skills/kdyconvention/references/rule-registry.md | Layer 5 추가 (SK-01 |
| 4 | 03-skills/kdyconvention/SKILL.md | Phase 0/1에 Layer 5 활성 조건 + Grep 패턴 |
| 5 | 03-skills/kdyconvention/references/violation-matrix.md | SK/AG 임계값 2행 추가 |
| 6 | 03-skills/cs/SKILL.md | ## 관련 스킬/에이전트 테이블 추가 |
| 7 | 03-skills/kdyclean/SKILL.md | 관련 스킬 테이블 3-column 규격화 |
| 8 | 03-skills/kdysetting/SKILL.md | 관련 스킬 테이블 3-column 규격화 |
| 9 | 03-skills/crawler-code-generator/SKILL.md | 관련 스킬 테이블 3-column 규격화 |
| 10 | 04-agents/tdd-guide.md | ## 호출 경로 테이블 추가 |
| 11 | 04-agents/build-error-resolver.md | ## 호출 경로 테이블 추가 |
| 12 | 04-agents/doc-updater.md | ## 호출 경로 테이블 추가 |
| 13 | 04-agents/web-crawler-builder.md | ## 호출 경로 테이블 추가 |
| 14 | 03-skills/00-community-reference/skill-writing-best-practices.md | 공식 컨벤션 참조 노트 추가 |
| 15 | 03-skills/kdygenesis/references/skill-creation-checklist.md | 공식 컨벤션 참조 노트 추가 |
| 16 | CLAUDE.md | 관련 문서 2링크 + 폴더 구조 MISSING_DESC 9건 보완 |
| 17 | docs/references/_COMPONENT_MAP.md | inception 갱신 (8 NEW, 2 CHANGED, 113+개 연결) |
상세 변경 사항
1. 컨벤션 문서 2개 — 공식 바인딩 규칙
skill-convention.md (7 Section):
- Section 0: 기존 비공식 가이드(best-practices, checklist)와의 관계 정립
- Section 1: Frontmatter 필수(name, description) / 권장(allowed-tools, argument-hint)
- Section 2: 파일 구조 8 표준 섹션, Phase 규칙, 크기 3 Tier (Micro ≤100 / Standard ≤500 / Large = references 분리)
- Section 3: Input Envelope (인수 테이블) + Output Envelope (진행 표시 → 보고서 → 파일 변경 → 다음 권장)
- Section 4: 4가지 관계 유형 (Trigger/Invoke/Recommend/Ref), 3-column 테이블
- Section 5: 네이밍 (kdy*/verify-*/kebab-case), 파일명, 한국어 주석
- Section 6: 변경 관리 (적용 이력, frontmatter 변경 시 동기화)
- Section 7: 품질 체크리스트 (생성 시 8항목, 리뷰 시 5항목)
agent-convention.md (4 Section):
- Section 0: 스킬 vs 에이전트 차이 (호출방식/자율성/컨텍스트)
- Section 1: Frontmatter 필수 4개(name/description/model/color), model 선택 가이드
- Section 2: 본문 구조 8 표준 섹션, 3-Tier 출력, 아카이브 규칙, 호출 경로 테이블
- Section 3-4: 네이밍 + 품질 체크리스트
2. kdyconvention Layer 5 — 기계적 검증 9개 규칙
| 코드 | 대상 | 검증 내용 |
|---|---|---|
| SK-01 | 스킬 | frontmatter name 또는 description 누락 |
| SK-02 | 스킬 | description에 한/영 트리거 키워드 없음 |
| SK-03 | 스킬 | ## 관련 스킬 테이블 없음 |
| SK-04 | 스킬 | SKILL.md 500줄 초과 + references/ 없음 |
| SK-05 | 스킬 | argument-hint 있는데 인수 테이블 없음 |
| AG-01 | 에이전트 | frontmatter 필수 4필드 누락 |
| AG-02 | 에이전트 | <example> 태그 2개 미만 |
| AG-03 | 에이전트 | 출력 3-Tier 심각도 없음 |
| AG-04 | 에이전트 | ## 호출 경로 테이블 없음 |
활성 조건: CWD가 00 general-pro이거나 --scope 03-skills/ 또는 --scope 04-agents/ 지정 시.
3. 기존 파일 보정 — SK-03/AG-04 위반 해소
스킬 4개에 ## 관련 스킬/에이전트 3-column 테이블 추가, 에이전트 4개에 ## 호출 경로 테이블 추가하여 SK-03/AG-04 위반이 0건으로 감소.
4. /inception + /kdyupdate 동기화
- _COMPONENT_MAP.md: Read 관계 2건, 문서 참조 2건, 수동 연쇄 2건, 에이전트-스킬 교차 4건 추가 → 총 113+개 연결
- CLAUDE.md: 폴더 구조 MISSING_DESC 9건 (스킬 7 + 에이전트 2) 설명 추가
검증 결과
- code-reviewer 에이전트 검증: 8/8 PASS (frontmatter, 구조, 관계, 최소 권한, 네이밍, 체크리스트, kdyconvention 통합, 기존 가이드 흡수)
- CLAUDE.md ABSOLUTE 섹션 무결성: 변경 없음 확인
터치하지 않은 영역
docs/rules/reusable-code.md— 기존 코딩 컨벤션 (변경 불필요)02-reusable-code/,02-reusable-code-python/— 코드 라이브러리 (변경 불필요)01-dev-rules-system/— 개발 규칙 시스템 (변경 불필요)- 글로벌 스킬 (
~/.claude/skills/) — 이번 세션에서 동기화 미수행
알려진 이슈
- 글로벌 스킬에 이번 세션 변경사항 미동기화 (kdyconvention SKILL.md, rule-registry.md 등)
_SYNERGY_ANALYSIS.md통계 여전히 45+로 기록됨 (113+로 갱신 필요)
다음 작업 제안
- kdyconvention Layer 5 실전 검증 —
kdyconvention --scope 03-skills/실행하여 baseline 위반 건수 확인 - 글로벌 스킬 동기화 — 이번 세션에서 변경된 kdyconvention 등을 글로벌에 반영
_SYNERGY_ANALYSIS.md통계 갱신 — 113+개 연결 반영