Agent Instructions 평가 스킬
레포지토리의 에이전트 설정 파일(AGENTS.md, CLAUDE.md 등)을 ArXiv 논문 20편 및 Foundation Model 공식 가이드 기반의 8개 카테고리로 정량 평가하고, 개선 권고를 제공한다.
1단계: 대상 파일 탐색
$ARGUMENTS가 제공된 경우 해당 파일을 직접 읽는다. 미지정 시 아래 패턴을 자동 탐색한다:
code
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단계: 종합 점수 산출
가중 합산으로 종합 점수를 계산한다:
code
종합 = 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단계: 보고서 출력
아래 형식으로 보고서를 출력한다:
markdown
# 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으로 파악한 뒤 프로젝트에 맞게 커스터마이징하여 제안한다.
markdown
# 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를 참조한다.