SEG: Skill Evaluation Graph: 에이전트 스킬 감사 및 최적화를 위한 절차적 드라이버
에이전트 스킬을 신뢰할 수 있고, 토큰 효율적이며, 프로덕션에 적합한 엔지니어링 자산으로 전환합니다. 트리거 정밀도, 점진적 공개 구조, 행동 제어, 실행 결정성, 운영 안전성 및 토큰 경제성을 평가합니다.
빠른 참조 매트릭스
| 항목 | 목적 | 공식 리소스 |
|---|---|---|
| 공식 용어집 | 공식 용어 및 도메인 정의 | references/terminology.md |
| 6대 원칙 감사 루브릭 | 객관적인 1-5점 평가 기준 | references/audit-rubric.md |
| 안티패턴 카탈로그 | 14가지 반복적인 스킬 결함 진단 가이드 | references/anti-patterns.md |
| 컨텍스트 엔지니어링 | 다중 계층 점진적 공개 패턴 | references/progressive-disclosure-patterns.md |
| 평가 그래프 및 루프 | 자율 평가자 루프 엔진 실행 설명서 | references/workflow-graph-and-evaluator-loop.md |
| 하네스 호환성 | 플랫폼 간 도구 매핑 (Antigravity/Claude/Codex) | references/harness-tool-matrix.md |
| 행동 평가 러너 | 제어 vs. 치료 평가 및 실시간 시험 | scripts/eval_skill.py |
| 기능 주장 감사 | 기술적 현실 및 증거 분류 | references/claim-audit.md |
| 점수카드 템플릿 | 표준화된 평가 보고서 템플릿 | assets/skill-audit-scorecard-template.md |
| 예시 점수카드 | 완료된 평가 보고서 예시 | assets/example-scorecard.md |
| 자체 감사 점수카드 | SEG 자체 감사 기준 점수카드 | assets/self-audit-scorecard.md |
| 표준 정렬 | Applied AI Wiki 14단계 프레임워크 | references/wiki-standard-alignment.md |
| 에이전트 보호 | 환각 방지 기여자 계약 | assets/agent-contributor-contract-template.md |
[!IMPORTANT] 공식 용어집: references/terminology.md를 SEG의 공식 용어로 사용하십시오. 용어집을 업데이트하지 않고 정의된 개념에 대한 동의어를 도입하지 마십시오.
워크플로우 그래프 아키텍처
[노드 1: 접수 및 범위]
│
▼
[노드 2: 병렬 평가자 DAG 실행]
(스키마, 링크, 토큰, 안전/개인정보, 이식성, 트리거 라우팅, 행동 정책)
│
▼
[노드 3: 다중 노드 증거 결합]
│
▼
[노드 4: 다중 게이트 평가자 Oracle]
│
┌───────┼───────────────────────────────┐
▼ ▼ ▼
[노드 5A: 승인] [노드 5B/5C: 수정] [노드 5D: 에스컬레이션]
(점수카드 및 영수증) (샌드박스 검증 -> 미리보기/변경) (인간 개입 필요)
절차적 실행 드라이버
에이전트 스킬을 감사하거나 최적화할 때 다음 단계를 순서대로 따르십시오:
1단계: 대상 스킬 식별 및 범위 확인
SKILL.md가 포함된 대상 디렉토리를 찾습니다.SKILL.md,references/,scripts/,assets/디렉토리의 패키지 목록을 검사합니다.- 호스트 하네스 호환성 매니페스트(
.codex-plugin/plugin.json,CLAUDE.md,AGENTS.md,.agents/plugins/marketplace.json)를 확인합니다.
2단계: 공식 용어집 읽기
분석 결과를 기록하기 전에 references/terminology.md를 참조하십시오. 모든 피드백과 보고서는 정확한 공식 명칭(예: 정적 품질 점수, Oracle 판정, 평가 무결성 게이트, 사전 변조 스냅샷)을 사용해야 합니다.
3단계: 평가 그래프 실행
scripts/run_loop.py를 통해 모듈식 병렬 평가 DAG를 실행합니다:
# 읽기 전용 평가 및 diff 미리보기 (기본값)
python "<skill-dir>/scripts/run_loop.py" "<target-skill-path>" --target-score 95 --max-iterations 3
# 승인 시 점수카드 전달 포함
python "<skill-dir>/scripts/run_loop.py" "<target-skill-path>" --scorecard "<target-skill-path>/scorecard.md"
평가자 노드는 병렬 종속성 웨이브로 실행됩니다:
schema: YAML frontmatter, 명명 규칙 및 필수 필드 유효성을 검사합니다.links_syntax: 상대 링크, 단일 홉 규칙 및 코드 펜스를 확인합니다.tokens: 5가지 점진적 공개 계층의 토큰 예산을 프로파일링합니다.safety_privacy: 파괴적인 명령 및 워크스테이션 경로 노출을 감지합니다.portability: OpenAI Codex 플러그인 및 마켓플레이스 매니페스트의 유효성을 검사합니다.trigger_routing: frontmatter 설명 트리거 및 부정적 경계를 확인합니다.behaviour_policy: 합리화 방지 지침을 시행합니다.
4단계: 증거 결합 및 게이트 평가
모든 노드의 증거는 JoinedEvidence로 합성됩니다. EvaluatorOracle은 5가지 필수 게이트를 시행합니다:
- 평가 무결성 게이트 (게이트 0): 평가자 중 하나라도 처리되지 않은 오류가 발생하거나, 시간 초과되거나, 예기치 않게 건너뛰면 실패로 간주합니다.
- 사양 준수 게이트: 노드가
SPECIFICATION_ERROR(예: 잘못된 마켓플레이스 스키마 또는 손상된 frontmatter)를 보고하면 실패합니다. - 안전 및 개인정보 게이트: 파괴적인 명령 또는 워크스테이션 경로 유출 시 실패합니다.
- 링크 무결성 게이트: 깨진 상대 마크다운 링크가 있으면 실패합니다.
- 정적 품질 점수 정책 게이트: 전체 점수가
--target-score(기본값: 95)를 충족하는지 확인합니다.
5단계: Oracle 판정 처리
승인(노드 5A): 모든 필수 게이트 통과 및 정적 품질 점수 >= 95. 점수카드 및 평가 영수증 생성. 상태:완료(수리가 적용된 경우변경됨).수정(노드 5B/5C): 수정 가능한 결함 발견. 6단계로 진행합니다.에스컬레이션(노드 5D): 해결 불가능한 차단 요소 또는 반복 횟수 상한 도달. 상세 차단 목록과 함께 인간 개입을 위해 중단. 상태:에스컬레이션됨.
6단계: 수리 도출, 샌드박스에서 검증 및 권한을 가지고 변경
판정이 수정인 경우:
plan_repairs()는 분석 결과에서 결정론적 패치 제안을 도출합니다.RepairIsolator는 격리된 임시 샌드박스(tempfile.TemporaryDirectory)에 제안을 준비합니다.- 후보는 DAG 및 Oracle을 사용하여 샌드박스 내에서 재평가되어 다음을 확인합니다:
- 평가 무결성 게이트 통과.
- 필수 게이트가 퇴보하지 않음.
- 새로운
ERROR분석 결과가 도입되지 않음. - 정적 품질 점수 또는 분석 결과 수가 엄격히 개선됨.
- 후보가 검증을 통과하면:
- 기본값 (읽기 전용): 통합 diff가 인간 검토를 위해 표시됩니다. 디스크의 대상 스킬은 변경되지 않습니다. 상태:
미리보기됨. --apply포함: 검증된 패치가 사전 변조 스냅샷 보호(고유한 이름의 형제 복구 디렉토리)와 함께 디스크에 기록됩니다. 상태:변경됨.
- 기본값 (읽기 전용): 통합 diff가 인간 검토를 위해 표시됩니다. 디스크의 대상 스킬은 변경되지 않습니다. 상태:
승인되거나 최대 반복 횟수에 도달할 때까지 다음 반복을 위해 루프가 재개됩니다.
7단계: 선택적으로 행동 시험 실행
번들로 제공되는 버전 관리된 카탈로그는 evaluations/scenarios/에 있습니다. SEG를 실행하기 전에 requirements.txt에서 Python 종속성을 설치하십시오.
스킬 실행의 동적 검증을 위해 scripts/eval_skill.py를 실행합니다:
# 합리화 방지 시나리오의 오프라인 시뮬레이션
python "<skill-dir>/scripts/eval_skill.py" "<target-skill-path>"
# 분리된 홈 디렉토리를 사용한 실시간 인증 Codex CLI 시험
python "<skill-dir>/scripts/eval_skill.py" "<target-skill-path>" --live --harness codex --trials 1 --timeout 90
8단계: 증거 기반 점수카드 생성
scripts/audit_skill.py를 통해 최종 감사 점수카드를 생성합니다:
python "<skill-dir>/scripts/audit_skill.py" "<target-skill-path>" --scorecard "<output-scorecard.md>"
점수카드는 DAG 및 Oracle의 측정된 증거를 엄격하게 반영합니다:
- 권장 사항은 Oracle 판정 (
승인,수정,에스컬레이션)과 일치합니다. - 측정된 루브릭 기둥은 평가자 메트릭을 투영합니다.
- 측정되지 않은 기둥은 명시적으로
평가되지 않음으로 보고됩니다. - 최종 실행 상태에 대한 SHA256 다이제스트가 포함된 변조 방지 평가 영수증이 저장됩니다.
품질 불변 조건
- 링크 오류 제로: 모든 상대 마크다운 링크는 스킬 디렉토리 내에서 확인 가능해야 합니다.
- 엄격한 단일 홉: 참조 파일이 보조 참조 파일에 연결될 수 없습니다.
- 예산 준수:
SKILL.md는 300줄 또는 2500 토큰을 초과할 수 없습니다. - 자체 포함 이식성: 하드코딩된 머신 경로 또는 사용자 홈 디렉토리가 없어야 합니다.
- 증거 무결성: 점수카드와 영수증은 조작된 점수 없이 검증 가능한 증거를 반영해야 합니다.