188 lines
5.0 KiB
Markdown
188 lines
5.0 KiB
Markdown
# 완전성 분석 가이드
|
|
|
|
대상 스킬의 에러 핸들링, 교차참조, 메타데이터 완전성을 분석하는 가이드입니다.
|
|
|
|
## 분석 대상
|
|
|
|
| 항목 | 검사 내용 |
|
|
|------|----------|
|
|
| 에러 핸들링 | 에러 처리 테이블 존재, 시나리오 커버리지, 해결책 명시 |
|
|
| 교차참조 | 다른 스킬과의 연결, 링크 유효성 |
|
|
| 메타데이터 | 버전, 작성자, 라이센스, 의존성 |
|
|
| 스크립트 경로 | 참조된 스크립트의 실제 존재 여부 |
|
|
|
|
## 에러 핸들링 검증
|
|
|
|
### 필수 요소
|
|
|
|
| 요소 | 검사 내용 | 필수 |
|
|
|------|----------|------|
|
|
| 에러 테이블 | "Error Handling" 또는 "에러 처리" 섹션 | 예 |
|
|
| 시나리오 | 최소 3개 이상의 에러 시나리오 | 예 |
|
|
| 해결책 | 각 시나리오별 해결 방법 명시 | 예 |
|
|
|
|
### 양호한 에러 핸들링 예시
|
|
|
|
```markdown
|
|
## Error Handling
|
|
|
|
| 상황 | 대응 |
|
|
|------|------|
|
|
| 경로 없음 | 사용자에게 SKILL.md 경로 요청 |
|
|
| 파일 없음 | 해당 경로에 SKILL.md가 없음 안내 |
|
|
| 읽기 실패 | 파일 권한 확인, 대체 경로 제안 |
|
|
```
|
|
|
|
### 부적절한 에러 핸들링 예시
|
|
|
|
```markdown
|
|
## Error Handling
|
|
에러가 발생하면 사용자에게 알립니다.
|
|
```
|
|
|
|
### 시나리오 커버리지 검사
|
|
|
|
| 카테고리 | 필수 시나리오 |
|
|
|----------|-------------|
|
|
| 입력 에러 | 잘못된 경로, 없는 파일, 빈 파일 |
|
|
| 권한 에러 | 읽기 불가, 쓰기 불가 |
|
|
| 환경 에러 | 필수 도구 미설치, 네트워크 불가 |
|
|
| 논리 에러 | 분석 불가, 형식 비표준 |
|
|
|
|
## 교차참조 검증
|
|
|
|
### 검사 항목
|
|
|
|
| 항목 | 검사 내용 |
|
|
|------|----------|
|
|
| 내부 링크 | 같은 스킬 내 다른 파일 참조 유효성 |
|
|
| 외부 링크 | 다른 스킬로의 참조 유효성 |
|
|
| 관련 스킬 | "Related Skills" 또는 "관련 스킬" 섹션 존재 |
|
|
|
|
### 내부 링크 검증
|
|
|
|
1. SKILL.md에서 마크다운 링크 추출
|
|
- `[text](path/to/file.md)` 패턴
|
|
- `| 경로 | path/to/file |` 테이블 패턴
|
|
|
|
2. 참조된 파일의 실제 존재 여부 확인
|
|
|
|
3. 존재하지 않는 파일 목록 생성
|
|
|
|
### 외부 링크 검증
|
|
|
|
1. 다른 스킬 디렉토리로의 참조 검색
|
|
2. 참조된 스킬이 실제로 존재하는지 확인
|
|
3. 스킬 이름 변경/이전에 따른 깨진 링크 탐지
|
|
|
|
## 메타데이터 검증
|
|
|
|
### 필수 메타데이터
|
|
|
|
| 필드 | 검사 내용 | 필수 |
|
|
|------|----------|------|
|
|
| `version` | SemVer 형식 (x.y.z) | 예 |
|
|
| `author` | 작성자 명시 | 예 |
|
|
| `tags` | 분류 태그 | 권장 |
|
|
| `dependencies` | 의존성 목록 | 권장 |
|
|
| `license` | 라이센스 | 선택 |
|
|
|
|
### 버전 검증
|
|
|
|
| 항목 | 검사 내용 |
|
|
|------|----------|
|
|
| 형식 | SemVer (major.minor.patch) |
|
|
| 일관성 | 같은 프로젝트 내 버전 체계 일관 |
|
|
| 의미 | 버전 번호가 의미 있게 증가 |
|
|
|
|
## 스크립트 경로 검증
|
|
|
|
### 검사 방법
|
|
|
|
1. SKILL.md에서 코드 블록/테이블 내 스크립트 참조 추출
|
|
- `./scripts/example.sh`
|
|
- `scripts/example.py`
|
|
- `` `scripts/example.sh` ``
|
|
|
|
2. 참조된 스크립트의 실제 존재 여부 확인
|
|
|
|
3. 스크립트 실행 권한 확인 (선택)
|
|
|
|
### 일반적인 문제
|
|
|
|
| 문제 | 설명 |
|
|
|------|------|
|
|
| 경로 변경 | 스크립트 이전 후 경로 미갱신 |
|
|
| 파일명 변경 | 스크립트 이름 변경 후 참조 미갱신 |
|
|
| 삭제된 스크립트 | 스크립트 삭제 후 참조 유지 |
|
|
| 권한 부재 | 스크립트 존재하나 실행 권한 없음 |
|
|
|
|
## 점수 산출
|
|
|
|
| 항목 | 배점 | 감점 기준 |
|
|
|------|------|----------|
|
|
| 에러 핸들링 테이블 | 30점 | 없음 -30점, 부족함 -15점 |
|
|
| 시나리오 커버리지 | 20점 | 카테고리당 -5점 |
|
|
| 교차참조 유효성 | 20점 | 깨진 링크당 -10점 |
|
|
| 메타데이터 | 15점 | 필수 필드 누락당 -8점 |
|
|
| 스크립트 경로 | 15점 | 누락당 -10점 |
|
|
|
|
## 개선 패턴
|
|
|
|
### 패턴 1: 에러 핸들링 추가
|
|
|
|
**현재:**
|
|
```markdown
|
|
## Error Handling
|
|
에러가 발생하면 알립니다.
|
|
```
|
|
|
|
**개선:**
|
|
```markdown
|
|
## Error Handling
|
|
|
|
| 상황 | 대응 |
|
|
|------|------|
|
|
| 경로 없음 | 사용자에게 SKILL.md 경로 요청 |
|
|
| 파일 없음 | 해당 경로에 SKILL.md가 없음 안내 |
|
|
| 읽기 실패 | 파일 권한 확인, 대체 경로 제안 |
|
|
| 백업 실패 | 수정 전 사용자에게 경고 |
|
|
| 분석 불가 | 스킬 형식이 비표준인 경우 분석 범위 제한 안내 |
|
|
```
|
|
|
|
### 패턴 2: 교차참조 추가
|
|
|
|
**현재:**
|
|
```markdown
|
|
## Related Skills
|
|
- deploy-model
|
|
```
|
|
|
|
**개선:**
|
|
```markdown
|
|
## Related Skills
|
|
|
|
| 스킬 | 관계 | 경로 |
|
|
|------|------|------|
|
|
| deploy-model | 배포 후 검증 | [deploy-model](../deploy-model/SKILL.md) |
|
|
| capacity | 배포 전 용량 확인 | [capacity](../capacity/SKILL.md) |
|
|
```
|
|
|
|
### 패턴 3: 메타데이터 보강
|
|
|
|
**현재:**
|
|
```yaml
|
|
name: my-skill
|
|
description: "설명"
|
|
```
|
|
|
|
**개선:**
|
|
```yaml
|
|
name: my-skill
|
|
description: "설명. Use for: ... DO NOT USE FOR: ..."
|
|
version: 1.0.0
|
|
author: User
|
|
tags: [tag1, tag2]
|
|
dependencies: [tool1, tool2]
|
|
```
|