e228faabf5
G-1: 메신저 Webhook Relay + _send_to_room 실제 httpx 호출 구현 G-2: POST /api/tasks/bulk SR 대량작업 엔드포인트 (최대 100건) G-3: 라이선스 만료 알림 스케줄러 (매일 09:00 KST) G-4: 체험판 upgrade_banner 필드 + license.py 배너 로직 G-5: core/auto_rca.py + incidents/problem auto-rca 엔드포인트 G-6: core/deploy_impact.py + vibe impact-analysis 엔드포인트 G-7: core/ticket_classifier.py + SR 생성 시 AI 분류 + ai-suggestion API G-8: VulnPatchRecord 모델 + vuln_scan 패치추적 4개 엔드포인트 G-9: core/jira_sync.py + gateway Jira/Confluence 연동 엔드포인트 G-10: core/push_notify.py + routers/push.py + PushSubscription 모델 G-11: approvals 다중승인 (위임/서명/기한초과/마감연장) G-12: alembic.ini + migrations/ + cicd/migrate_to_postgres.sh 하네스: guardia-orchestrator 확장기능 Phase 반영 봇명령어: /sr /status /license /bulk 슬래시 명령어 추가 설치스크립트: setup/ (Ubuntu, CentOS, RHEL, Windows) --test 옵션 포함 Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
269 lines
7.9 KiB
Markdown
269 lines
7.9 KiB
Markdown
# 스킬 작성 가이드
|
|
|
|
하네스에서 생성하는 스킬의 품질을 높이기 위한 상세 작성 가이드. SKILL.md Phase 4의 보충 레퍼런스.
|
|
|
|
---
|
|
|
|
## 목차
|
|
|
|
1. [Description 작성 패턴](#1-description-작성-패턴)
|
|
2. [본문 작성 스타일](#2-본문-작성-스타일)
|
|
3. [출력 형식 정의 패턴](#3-출력-형식-정의-패턴)
|
|
4. [예시 작성 패턴](#4-예시-작성-패턴)
|
|
5. [Progressive Disclosure 패턴](#5-progressive-disclosure-패턴)
|
|
6. [스크립트 번들링 판단 기준](#6-스크립트-번들링-판단-기준)
|
|
7. [데이터 스키마 표준](#7-데이터-스키마-표준)
|
|
8. [스킬에 포함하지 않을 것](#8-스킬에-포함하지-않을-것)
|
|
|
|
---
|
|
|
|
## 1. Description 작성 패턴
|
|
|
|
Description은 스킬의 유일한 트리거 메커니즘이다. Claude는 `available_skills` 목록에서 name + description만 보고 스킬 사용 여부를 결정한다.
|
|
|
|
### 트리거 메커니즘 이해
|
|
|
|
Claude는 자신의 기본 도구로 쉽게 처리할 수 있는 단순 작업에는 스킬을 호출하지 않는 경향이 있다. "이 PDF 읽어줘" 같은 단순 요청은 description이 완벽해도 트리거되지 않을 수 있다. 복잡하고 다단계이며 전문적인 작업일수록 스킬 트리거 확률이 높다.
|
|
|
|
### 작성 원칙
|
|
|
|
1. **스킬이 하는 일** + **구체적 트리거 상황**을 모두 기술
|
|
2. 유사하지만 트리거하면 안 되는 경우를 구분하는 경계 조건 명시
|
|
3. 약간 "pushy"하게 — Claude가 트리거를 보수적으로 판단하는 경향을 보상
|
|
|
|
### 좋은 예시
|
|
|
|
```yaml
|
|
description: "PDF 파일 읽기, 텍스트/테이블 추출, 병합, 분할, 회전, 워터마크,
|
|
암호화/복호화, OCR 등 모든 PDF 작업을 수행. .pdf 파일을 언급하거나
|
|
PDF 산출물을 요청하면 반드시 이 스킬을 사용할 것. 단순히 PDF를
|
|
'읽어달라'는 요청이 아닌 변환/편집/분석이 필요할 때 특히 유용."
|
|
```
|
|
|
|
```yaml
|
|
description: "엑셀/CSV/TSV 파일의 열 추가, 수식 계산, 서식, 차트,
|
|
데이터 정제를 포함한 모든 스프레드시트 작업. 사용자가 스프레드시트
|
|
파일을 언급하면 — 심지어 캐주얼하게('다운로드 폴더의 xlsx')라고만
|
|
해도 — 이 스킬을 사용할 것."
|
|
```
|
|
|
|
### 나쁜 예시
|
|
|
|
- `"데이터를 처리하는 스킬"` — 너무 모호, 어떤 파일/작업인지 불분명
|
|
- `"PDF 관련 작업"` — 구체적 동작 나열 없음, 트리거 상황 미기술
|
|
|
|
---
|
|
|
|
## 2. 본문 작성 스타일
|
|
|
|
### Why-First 원칙
|
|
|
|
LLM은 이유를 이해하면 엣지 케이스에서도 올바르게 판단한다. 강압적 규칙보다 맥락 전달이 효과적이다.
|
|
|
|
**나쁜 예:**
|
|
```markdown
|
|
ALWAYS use pdfplumber for table extraction. NEVER use PyPDF2 for tables.
|
|
```
|
|
|
|
**좋은 예:**
|
|
```markdown
|
|
테이블 추출에는 pdfplumber를 사용한다. PyPDF2는 텍스트 추출에 특화되어
|
|
있어 테이블의 행/열 구조를 보존하지 못하기 때문이다. pdfplumber는
|
|
셀 경계를 인식하여 구조화된 데이터를 반환한다.
|
|
```
|
|
|
|
### 일반화 원칙
|
|
|
|
피드백이나 테스트 결과에서 문제가 발견되면, 특정 예시에만 맞는 좁은 수정 대신 **원리 수준에서 일반화**한다.
|
|
|
|
**오버피팅 수정:**
|
|
```markdown
|
|
"Q4 매출" 열이 있으면 해당 열을 숫자로 변환하라.
|
|
```
|
|
|
|
**일반화된 수정:**
|
|
```markdown
|
|
열 이름에 "매출", "금액", "수량" 등 수치를 암시하는 키워드가 있으면
|
|
해당 열을 숫자 타입으로 변환한다. 변환 실패 시 원본 값을 유지한다.
|
|
```
|
|
|
|
### 명령형 어조
|
|
|
|
"~합니다", "~할 수 있습니다" 대신 "~한다", "~하라" 형태를 사용한다. 스킬은 지시서이다.
|
|
|
|
### 컨텍스트 절약
|
|
|
|
컨텍스트 윈도우는 공공재다. 모든 문장이 토큰 비용을 정당화하는지 자문한다:
|
|
- "Claude가 이미 알고 있는 내용인가?" → 삭제
|
|
- "이 설명이 없으면 Claude가 실수하는가?" → 유지
|
|
- "구체적 예시 하나가 긴 설명보다 효과적인가?" → 예시로 대체
|
|
|
|
---
|
|
|
|
## 3. 출력 형식 정의 패턴
|
|
|
|
산출물의 형식이 중요한 스킬에서 사용:
|
|
|
|
```markdown
|
|
## 보고서 구조
|
|
다음 템플릿을 정확히 따른다:
|
|
|
|
# [제목]
|
|
## 요약
|
|
## 핵심 발견
|
|
## 권장 사항
|
|
```
|
|
|
|
형식 정의는 간결하게, 실제 예시를 포함하면 더 효과적이다.
|
|
|
|
---
|
|
|
|
## 4. 예시 작성 패턴
|
|
|
|
예시는 긴 설명보다 효과적이다:
|
|
|
|
```markdown
|
|
## 커밋 메시지 형식
|
|
|
|
**예시 1:**
|
|
입력: JWT 토큰 기반 사용자 인증 추가
|
|
출력: feat(auth): JWT 기반 인증 구현
|
|
|
|
**예시 2:**
|
|
입력: 로그인 페이지에서 비밀번호 표시 버튼이 동작하지 않는 버그 수정
|
|
출력: fix(login): 비밀번호 표시 토글 버튼 동작 수정
|
|
```
|
|
|
|
---
|
|
|
|
## 5. Progressive Disclosure 패턴
|
|
|
|
### 패턴 1: 도메인별 분리
|
|
|
|
```
|
|
bigquery-skill/
|
|
├── SKILL.md (개요 + 도메인 선택 가이드)
|
|
└── references/
|
|
├── finance.md (매출, 빌링 메트릭)
|
|
├── sales.md (기회, 파이프라인)
|
|
└── product.md (API 사용량, 기능)
|
|
```
|
|
|
|
사용자가 매출에 대해 물으면 finance.md만 로드.
|
|
|
|
### 패턴 2: 조건부 상세
|
|
|
|
```markdown
|
|
# DOCX 처리
|
|
|
|
## 문서 생성
|
|
docx-js로 새 문서를 생성한다. → [DOCX-JS.md](references/docx-js.md) 참조.
|
|
|
|
## 문서 편집
|
|
단순 편집은 XML을 직접 수정.
|
|
**추적 변경이 필요하면**: [REDLINING.md](references/redlining.md) 참조
|
|
```
|
|
|
|
### 패턴 3: 대형 레퍼런스 파일 구조
|
|
|
|
300줄 이상의 reference 파일은 상단에 목차를 포함한다:
|
|
|
|
```markdown
|
|
# API 레퍼런스
|
|
|
|
## 목차
|
|
1. [인증](#인증)
|
|
2. [엔드포인트 목록](#엔드포인트-목록)
|
|
3. [에러 코드](#에러-코드)
|
|
4. [레이트 리밋](#레이트-리밋)
|
|
|
|
---
|
|
|
|
## 인증
|
|
...
|
|
```
|
|
|
|
---
|
|
|
|
## 6. 스크립트 번들링 판단 기준
|
|
|
|
테스트 실행에서 에이전트들의 트랜스크립트를 관찰한다. 다음 패턴이 보이면 번들링 대상:
|
|
|
|
| 신호 | 조치 |
|
|
|------|------|
|
|
| 3개 테스트 중 3개에서 동일한 헬퍼 스크립트 생성 | `scripts/`에 번들링 |
|
|
| 매번 같은 pip install/npm install 실행 | 스킬에 의존성 설치 단계 명시 |
|
|
| 동일한 다단계 접근법 반복 | 스킬 본문에 표준 절차로 기술 |
|
|
| 매번 비슷한 에러 후 같은 회피책 적용 | 스킬에 알려진 문제와 해결법 기술 |
|
|
|
|
번들링된 스크립트는 반드시 실행 테스트를 거친다.
|
|
|
|
---
|
|
|
|
## 7. 데이터 스키마 표준
|
|
|
|
스킬 간 데이터 교환의 일관성을 위해 표준 스키마를 사용한다. 하네스에서 생성하는 스킬의 테스트/평가에 사용할 수 있다.
|
|
|
|
### eval_metadata.json
|
|
|
|
각 테스트 케이스의 메타데이터:
|
|
|
|
```json
|
|
{
|
|
"eval_id": 0,
|
|
"eval_name": "descriptive-name-here",
|
|
"prompt": "사용자의 작업 프롬프트",
|
|
"assertions": [
|
|
"산출물에 X가 포함되어 있다",
|
|
"Y 형식으로 파일이 생성되었다"
|
|
]
|
|
}
|
|
```
|
|
|
|
### grading.json
|
|
|
|
assertion 기반 채점 결과:
|
|
|
|
```json
|
|
{
|
|
"expectations": [
|
|
{
|
|
"text": "산출물에 '서울'이 포함됨",
|
|
"passed": true,
|
|
"evidence": "3번째 단계에서 '서울 지역 데이터 추출' 확인"
|
|
}
|
|
],
|
|
"summary": {
|
|
"passed": 2,
|
|
"failed": 1,
|
|
"total": 3,
|
|
"pass_rate": 0.67
|
|
}
|
|
}
|
|
```
|
|
|
|
**필드명 주의:** `text`, `passed`, `evidence`를 정확히 사용한다 (`name`/`met`/`details` 등 변형 금지).
|
|
|
|
### timing.json
|
|
|
|
실행 시간/토큰 측정:
|
|
|
|
```json
|
|
{
|
|
"total_tokens": 84852,
|
|
"duration_ms": 23332,
|
|
"total_duration_seconds": 23.3
|
|
}
|
|
```
|
|
|
|
서브에이전트 완료 알림에서 `total_tokens`와 `duration_ms`를 즉시 저장한다. 이 데이터는 알림 시점에만 접근 가능하고 이후 복구 불가.
|
|
|
|
---
|
|
|
|
## 8. 스킬에 포함하지 않을 것
|
|
|
|
- README.md, CHANGELOG.md, INSTALLATION_GUIDE.md 등 부가 문서
|
|
- 스킬 생성 과정의 메타 정보 (테스트 결과, 반복 이력)
|
|
- 사용자 대상 설명서 (스킬은 AI 에이전트를 위한 지시서)
|
|
- 이미 Claude가 알고 있는 일반적 지식
|