evaluate-instructions

name	evaluate-instructions
description	이 스킬은 사용자가 에이전트 설정 파일을 '평가', '분석', '개선', '점검'하고 싶을 때 사용합니다. AGENTS.md, CLAUDE.md, .cursorrules, .cursor/rules/*.mdc, .github/copilot-instructions.md 등 에이전트 instructions 파일의 품질을 20편의 ArXiv 논문 기반 기준으로 평가합니다. 'evaluate agents', 'agent instructions 평가', 'AGENTS.md 리뷰', 'instructions 품질 체크' 등의 요청에 활성화됩니다.
argument-hint	[파일경로] (미지정시 자동 탐색)
modeSlugs	["code"]

Agent Instructions 평가 스킬

레포지토리의 에이전트 설정 파일(AGENTS.md, CLAUDE.md 등)을 ArXiv 논문 20편 및 Foundation Model 공식 가이드 기반의 8개 카테고리로 정량 평가하고, 개선 권고를 제공한다.

1단계: 대상 파일 탐색

$ARGUMENTS가 제공된 경우 해당 파일을 직접 읽는다. 미지정 시 아래 패턴을 자동 탐색한다:

AGENTS.md
CLAUDE.md
.claude.local.md
.cursorrules
.cursor/rules/*.mdc
.github/copilot-instructions.md
.windsurfrules
codex.md

Glob 도구로 프로젝트 루트 및 하위 디렉토리를 탐색한다. 발견된 파일 목록을 사용자에게 보여준 뒤 평가를 진행한다.

파일 미발견 시 → 6단계(템플릿 제공)로 직접 이동한다.

2단계: 파일 내용 읽기 및 심층 분석

발견된 모든 파일을 Read 도구로 읽는다. think hard를 사용하여 파일 내용을 심층 분석한다. 분석 시 다음을 파악한다:

• 전체 줄 수 및 토큰 규모 추정
• 섹션 구조 (헤딩 계층, 구분자 사용)
• 지시문의 성격 (긍정형/부정형 비율, 구체성)
• 컨텍스트 정보 포함 여부 (WHY, 역할, 예시)
• 추론 유도 장치 (CoT, Planning, Extended Thinking)
• 피드백/반복 메커니즘
• 안전/제약 경계 정의
• 에이전틱 워크플로우 지원
• 진화/업데이트 구조

3단계: 8개 카테고리 평가

각 카테고리를 0-100점으로 채점한다. 아래의 체크리스트와 근거를 기준으로 평가한다.

A. 구조 (Structure) — 가중치 15%

체크 항목	배점	근거
Markdown 헤딩(#) 또는 XML 태그로 계층적 섹션 구분	25	OpenAI GPT-4.1, SPRIG (arxiv:2410.14826)
구분자(###, XML, 따옴표)로 중요 개념 표시	20	ATLAS #8, #17
Progressive Disclosure: 핵심만 최상위, 상세는 별도 파일 분리	20	Claude Agent Skills, HumanLayer
300줄 미만 유지 (Over-Specification 회피)	20	HumanLayer, UCL S*=0.509 (arxiv:2601.00880)
지시 배치: 중요 지시를 앞과 뒤 모두 배치 (primacy-recency)	15	OpenAI Long Context Guide

B. 명확성 (Clarity) — 가중치 15%

체크 항목	배점	근거
명시적 지시: 모호함 없이 구체적 행동 기술	25	Anthropic Claude 4, ATLAS #9
긍정형 지시 위주 ("하지 마" < "해")	20	ATLAS #4
단일 속성 집중: 복합보다 핵심 하나에 집중	20	ACL 2025 메타분석 (arxiv:2506.06950)
미지정 요구사항 명시 (LLM 기본 추론 41.1%만 가능)	20	CMU (arxiv:2505.13360)
Over-Specification 회피 (S*=0.509 임계점 인지)	15	UCL (arxiv:2601.00880)

C. 컨텍스트 (Context) — 가중치 15%

체크 항목	배점	근거
WHY 포함: 각 규칙에 동기/이유 명시	25	Anthropic Claude 4, ATLAS #2
역할 정의: 에이전트의 전문 역할 부여	15	ATLAS #16, The Prompt Report
예시 제공 (Few-Shot): 원하는 형식/접근방식의 구체적 예시	25	ATLAS #7, k=3~5 최적
실제 파일 참조: 추상적 설명 대신 실제 코드 경로	20	builder.io AGENTS.md
WHAT/WHY/HOW 구분: 기술 스택, 목적, 워크플로우 분리	15	HumanLayer

D. 추론 유도 (Reasoning) — 가중치 10%

체크 항목	배점	근거
CoT 트리거: "step by step", "think" 등 단계적 사고 유도	30	ATLAS #12, CoT +10-15%
Planning 유도: 함수 호출 사이 계획/반성 지시	30	OpenAI GPT-4.1, +4%
Extended Thinking 활용 ("think hard", "ultrathink")	20	Anthropic Claude Code
모델 세대 인지: 최신 모델에 과도한 제약 경계	20	Prompting Inversion (arxiv:2510.22251)

E. 피드백 (Feedback) — 가중치 10%

체크 항목	배점	근거
Self-Criticism: 자체 출력 평가/수정 유도	25	The Prompt Report
질문 허용: 정보 부족 시 질문 가능 명시	25	ATLAS #14
테스트 명령: 빌드/린트/테스트 명령 제공	30	Anthropic Claude 4, Arize AI SWE-bench +6%
상태 추적: 작업 상태 기록 지시	20	Anthropic Claude 4

F. 안전/제약 (Safety/Constraints) — 가중치 15%

체크 항목	배점	근거
자율 vs 확인 구분: 읽기/린트=자율, 삭제/push=확인	30	builder.io, Anthropic
최소 변경 원칙: 요청된 변경만 수행 지시	25	Anthropic, Arize AI
API 계약 보존: 기존 인터페이스 변경 금지	20	Arize AI SWE-bench
근본 원인 진단: 빠른 수정 지양, 원인 우선	15	Arize AI
Guardrail-to-Handcuff 회피: 과도한 제약 = 리터럴리즘 유발 인지	10	Prompting Inversion (arxiv:2510.22251)

G. 에이전틱 (Agentic) — 가중치 10%

체크 항목	배점	근거
Persistence: "완전히 해결될 때까지 계속" 지시	25	OpenAI GPT-4.1, 3대 리마인더 +20%
Tool-calling: 추측 대신 도구 사용 지시	25	OpenAI GPT-4.1, +2% pass rate
File-Scoped 명령: 전체 빌드 대신 개별 파일 명령	25	builder.io, 속도/비용 절감
병렬 실행 지시: 독립적 호출 병렬 처리	15	Anthropic Claude 4
Hooks 자동화: PostEdit/PreCommit 등 자동 트리거	10	Anthropic Claude Code

H. 컨텍스트 진화 (Context Evolution) — 가중치 10%

체크 항목	배점	근거
Delta Update 구조: 증분 업데이트 가능한 구조	30	ACE (arxiv:2510.04618), 적응 지연 -82.3%
피드백 기반 개선: 실행 결과 기반 규칙 추가/수정 흔적	30	ACE +17.0%, Arize AI
의미적 중복 제거: 중복 규칙 없이 간결	20	ACE
버전/날짜 관리: 업데이트 이력 추적 가능	20	ACE Grow-and-Refine

4단계: 종합 점수 산출

가중 합산으로 종합 점수를 계산한다:

종합 = A×0.15 + B×0.15 + C×0.15 + D×0.10 + E×0.10 + F×0.15 + G×0.10 + H×0.10

등급 매핑:

등급	점수 범위	해석
A	90-100	최적 — 연구 기반 모범 사례 충족
B	75-89	우수 — 핵심 원칙 대부분 충족, 미세 개선 여지
C	60-74	양호 — 기본 구조는 있으나 주요 개선점 존재
D	40-59	미흡 — 핵심 카테고리에서 큰 결함
E	20-39	부족 — 대폭 재작성 권장
F	0-19	불합격 — 파일 재작성 또는 새로 생성 필요

5단계: 보고서 출력

아래 형식으로 보고서를 출력한다:

# Agent Instructions 평가 보고서

## 평가 대상

- 파일: [파일 경로 목록]
- 총 줄 수: [N줄]
- 평가 기준: ArXiv 논문 20편 + Foundation Model 공식 가이드 기반

## 종합 결과

| 종합 점수  | 등급  |
| ---------- | ----- |
| **XX/100** | **X** |

## 카테고리별 점수

| 카테고리         | 가중치   | 점수   | 기여     |
| ---------------- | -------- | ------ | -------- |
| A. 구조          | 15%      | XX/100 | XX.X     |
| B. 명확성        | 15%      | XX/100 | XX.X     |
| C. 컨텍스트      | 15%      | XX/100 | XX.X     |
| D. 추론 유도     | 10%      | XX/100 | XX.X     |
| E. 피드백        | 10%      | XX/100 | XX.X     |
| F. 안전/제약     | 15%      | XX/100 | XX.X     |
| G. 에이전틱      | 10%      | XX/100 | XX.X     |
| H. 컨텍스트 진화 | 10%      | XX/100 | XX.X     |
| **종합**         | **100%** |        | **XX.X** |

## 강점 (Top 3)

1. [구체적 강점 — 파일 내 해당 위치 참조]
2. ...
3. ...

## 약점 및 개선 권고 (Impact 순)

### 1. [가장 높은 Impact 약점]

- **현재**: [파일:줄번호] — [현재 상태 인용]
- **문제**: [왜 문제인지, 근거 논문]
- **권고**: [구체적 개선 방안]
- **기대효과**: [정량적 근거]

### 2. [두 번째 Impact 약점]

...

### 3. [세 번째 Impact 약점]

...

## 정량적 기대효과 요약

| 개선 항목 | 근거   | 예상 효과 |
| --------- | ------ | --------- |
| [항목]    | [논문] | [수치]    |

## 참고 문헌

- AGENTS.md 효과: 런타임 -28.64%, 토큰 -16.58% (arxiv:2601.20404)
- Over-Specification 임계점: S\*=0.509 (arxiv:2601.00880)
- NLT 도구 호출: +18.4%p (arxiv:2510.14453)
- SPRIG 시스템 프롬프트 최적화 (arxiv:2410.14826)
- Instructions만 최적화: Claude +6% SWE-bench (Arize AI)
- ACE 컨텍스트 진화: +17.0% (arxiv:2510.04618)
- 단일 속성 집중 효과 (arxiv:2506.06950)
- 미지정 프롬프트 회귀율 2배 (arxiv:2505.13360)

> 💡 **자기 개선**: 평가 결과를 바탕으로 설정 파일을 자동 개선할 수 있습니다. "개선해줘" 또는 "improve"를 요청하세요.

6단계: 파일 미존재 시 템플릿 제공

에이전트 설정 파일이 하나도 발견되지 않은 경우, 아래 AGENTS.md v2 템플릿을 추천한다. 프로젝트의 기술 스택과 구조를 Glob/Grep으로 파악한 뒤 프로젝트에 맞게 커스터마이징하여 제안한다.

# Project: [프로젝트명]

## 기술 스택

[TypeScript, Next.js, PostgreSQL 등 — 실제 탐지 결과로 채움]

## 핵심 규칙

### Do

- [구체적 행동 지시 — 긍정형으로 작성]
- [각 규칙에 WHY 포함: "~이므로 ~하라"]
- [실제 파일 경로 참조: "src/components/Button.tsx 패턴 따르기"]

### Don't

- [구체적 금지 — 최소한으로, 핵심만]

## 빌드 & 테스트 (File-Scoped)

- 단일 타입체크: `[실제 프로젝트 명령]`
- 단일 린트: `[실제 프로젝트 명령]`
- 단일 테스트: `[실제 프로젝트 명령]`

## 아키텍처 제약

[프로젝트의 핵심 구조적 결정 사항]

## 프로젝트 구조

[실제 디렉토리 구조로 채움]

## 참조 패턴

- [실제 파일 경로 예시]

## 안전 경계

### 자율 수행

- 파일 읽기/편집, 포맷팅, 린트, 개별 테스트

### 확인 필요

- 패키지 설치/제거, git push, DB 마이그레이션, 파일 삭제

템플릿 제공 시 반드시 안내:

• AGENTS.md 존재만으로 에이전트 런타임 -28.64%, 토큰 -16.58% 감소 효과 (arxiv:2601.20404)
• 300줄 미만, 규칙 150개 이내로 유지할 것 (Over-Specification S*=0.509)
• 작성 후 /evaluate-agents로 재평가하여 반복 개선할 것 (MVES 루프)

7단계: 자기 개선 (사용자 요청 시)

사용자가 평가 결과를 확인한 후 개선을 요청하면, IMPROVE.md의 지시에 따라 대상 파일을 개선한다.

이 단계는 사용자의 명시적 요청이 있을 때만 실행한다. 세부 실행 흐름은 IMPROVE.md를 참조한다.