Community라이팅 & 에디팅github.com

ultraeval: 스킬 또는 코드베이스 평가 → 근거 기반의 AI 활용 가능한 수정 문서

멀티 에이전트 워크플로우를 통해 스킬이나 코드베이스를 평가하고, 모든 발견 사항을 실제 file:line에 근거하여 TDD 수정 백로그를 생성합니다. skills.sh 에이전트 스킬입니다.

ultraeval: 스킬 또는 코드베이스 평가 → 근거 기반의 AI 활용 가능한 수정 문서란 무엇인가요?

ultraeval은 스킬 또는 코드베이스를 체계적으로 평가하고, 모든 발견 사항을 실제 파일과 라인에 근거하여 신뢰할 수 있는 수정 계획을 생성하는 멀티 에이전트 평가 도구입니다. 이 도구는 'grounding gate'라는 2단계 검증 메커니즘을 통해 할루시네이션된 발견을 걸러내며, 구조적 검증(check)과 의미론적 검증(verify)을 모두 수행합니다. 평가 결과는 우선순위가 지정된 BACKLOG.json, 상세한 REMEDIATION.md, 그리고 각 발견 사항별로 RED→GREEN→REFACTOR 단계를 따르는 TDD 카드(fixes/FIX-*.md)로 제공되어, AI 에이전트가 추가 분석 없이 바로 수정을 구현할 수 있습니다. Claude Code, Cursor, Codex 등 다양한 AI 에이전트 플랫폼에서 사용할 수 있으며, 평가 모드(audit, improve, deep)와 다양한 루브릭을 지원하여 결함 발견, 개선 기회 발굴, 또는 두 가지 모두를 수행할 수 있습니다.

지원 대상✓Claude Code~Codex CLI~Cursor
npx skills add maxgfr/ultraeval

Installed? Explore more 라이팅 & 에디팅 skills: steipete/notion, langchain-ai/langchain, bytedance/podcast-generation · View all 6 →

즐겨 사용하는 AI에게 물어보기

이 에이전트 스킬이 미리 로드된 새 채팅을 엽니다.

문서

ultraeval: 스킬 또는 코드베이스 평가 → 근거 기반의 AI 활용 가능한 수정 문서은(는) 무엇을 하나요?

마크다운이 프로그램입니다. 작은 결정론적 엔진이 실행을 구성하고, 멀티 에이전트 워크플로우를 생성하며, 근거 검증 게이트를 강제합니다; 여러분(분산된 서브에이전트와 함께)이 연구, 판단, 작성을 수행합니다. 모든 발견 사항은 대상의 실제 file:line으로 확인되어야 합니다 — 게이트는 할루시네이션된 발견을 거부합니다 — 그리고 출력은 우선순위가 지정된 백로그와 모델이 red→green→refactor로 구현할 수 있는 TDD 카드입니다.

사용 시기

  • "이 스킬(또는 저장소)을 평가/감사/등급/점수 매기기"; "프로덕션 준비가 되었는가 / 기대에 부합하는가?"
  • "이 코드베이스를 검토하고 수정 계획 / TDD 백로그를 제공해 주세요."
  • 변경 후 자신의 스킬을 회귀 테스트하거나, 신뢰하기 전에 타사 스킬을 검증할 때.

사용하지 않는 경우: 빠른 단일 파일 코드 리뷰(그냥 읽으면 됨); 대상의 자체 테스트 스위트 실행(직접 수행).

루프

init → plan → run(research → test-plan → execute+gates → judge → results) → verify → backlog(TDD) → score → render

모든 것은 일반 node <skill-dir>/scripts/ultraeval.mjs <cmd> 호출입니다. 서브에이전트를 분산하는 것은 생성된 워크플로우가 인코딩하는 최적화일 뿐이며, 필수 사항이 아닙니다.

확인할 입력

  • 대상(Target) — 평가할 스킬/저장소의 경로(또는 사용자가 이미 로컬에 클론한 Git URL).
  • 종류(Kind) — skill 또는 codebase (자동 감지: SKILL.md가 있으면 skill). --kind로 재정의.
  • 범주(Category) — 예: "agent skill", "CLI", "library", "web app", "security tool". 시작 루브릭을 결정합니다.
  • 모드(Mode) — audit (결함, 기본값) · improve (근거 기반 개선 기회) · deep (둘 다). --mode로 설정.

모드 및 개선 발견

ultraeval은 두 가지를 찾으며, 모두 근거 기반 및 게이트 검증을 거칩니다:

  • 결함(Defects) (audit, deep) — 문제가 있음; 각각 실제 file:line을 인용.
  • 기회(Opportunities) (improve, deep) — 근거 기반의 개선 방향(내부 건전성 및 제품/기능), 영향 × 노력으로 평가. analyze(결정론적 핫스팟/의존성/변경/테스트 격차) → brainstorm(발산적 렌즈) → brainstorm --rank(순위가 매겨진 기회를 kind:"opportunity"로 findings.json에 통합)를 통해 발견. 동일한 게이트가 적용됨 — 기회는 실제 코드/메트릭에 고정되어야 하므로 "모든 것을 다시 작성"과 같은 모호한 제안이 되지 않음. references/analysis-playbook.md 참조.

improve/deep 모드의 경우, plan이 생성된 워크플로우에 분석(Analyze) 및 브레인스토밍(Brainstorm) 단계를 추가합니다.

절차

1. 실행 준비(Scaffold).

node <skill-dir>/scripts/ultraeval.mjs init --target <PATH> --out <RUN> [--kind skill|codebase] [--category "<c>"]

시작 차원과 함께 eval.config.json을 작성(references/rubric-library.md 참조).

2. 워크플로우 + 서브에이전트 계약 생성.

node <skill-dir>/scripts/ultraeval.mjs plan --run <RUN>

<RUN>/eval.workflow.mjs (바로 실행 가능한 멀티 에이전트 워크플로우, 절대 엔진 및 대상 경로가 내장됨), <RUN>/agents/*.md (디스패치 계약), TEST-PLAN.template.md, dimensions.json, findings.schema.json을 생성.

3. 평가 실행. 작업 흐름 도구를 사용하여 생성된 워크플로우를 실행: Workflow({ scriptPath: "<RUN>/eval.workflow.mjs" }). 이는 연구 → 테스트 계획 → 실행 → 발견 → 게이트 → 판단 → 결과를 파이프라인으로 연결하고 엔진 게이트를 자체 호출합니다. 워크플로우 도구가 없으면 단계를 수동으로 실행: 각 agents/<stage>.md를 읽고 계약에 따라 서브에이전트를 디스패치합니다. references/orchestration.md 참조. 모든 서브에이전트는 절대 <skill-dir>/scripts/ultraeval.mjs 경로를 받습니다 — 자체 cwd가 있으므로 상대 경로를 확인할 수 없음(plan이 이미 절대 경로를 워크플로우에 내장함).

4. 모든 발견 사항 근거 확보. 결과를 <RUN>/findings.json으로 통합(스키마: references/gate-contract.md). 각 발견 사항은 evidence[].ref를 대상의 path:line 또는 생성된 로그의 run:relpath#Lnn으로 인용합니다. 그런 다음:

node <skill-dir>/scripts/ultraeval.mjs check --run <RUN>

종료 코드 0이 될 때까지 findings.json을 수정 — 근거 없는 발견은 수정하거나 삭제하고, 게이트를 약화시키지 마십시오.

5. 검증(적대적 종료 게이트).

node <skill-dir>/scripts/ultraeval.mjs verify --run <RUN>          # VERIFY.todo.json 작성
# 각 평결 입력: supported | partial | refuted | unsupported (회의론자 서브에이전트 사용; --shards N --shard i로 병렬화)
node <skill-dir>/scripts/ultraeval.mjs verify --run <RUN> --apply <verdicts.json>
node <skill-dir>/scripts/ultraeval.mjs check --run <RUN> --semantic --require-verify   # 종료 게이트 — 이 통과 전에는 절대 제시하지 마십시오.

refuted(반박됨) 발견은 dismissed(기각)으로 설정해야 합니다. supported(지원됨)/partial(부분 지원) 발견은 유지됩니다.

6. 수정 — 전달물.

node <skill-dir>/scripts/ultraeval.mjs backlog --run <RUN> --tdd

BACKLOG.json (다운스트림 에이전트가 실행할 수 있는 기계 판독 가능한 우선순위 작업 목록), REMEDIATION.md, 확인된 각 발견 사항당 하나의 fixes/FIX-*.md TDD 카드 생성 — 각각 RED 실패 테스트 우선 사양, GREEN 변경 사항, VERIFY 명령이 포함됨. references/tdd-remediation.md 참조.

7. 점수 + 렌더링 + 제시.

node <skill-dir>/scripts/ultraeval.mjs score --run <RUN>           # judges.jsonl + dimensions -> scorecard.json (0-100 + meets-expectations)
node <skill-dir>/scripts/ultraeval.mjs render --run <RUN>          # index.html + index.md 대시보드 (평결 표시)

score는 심사 패널의 judges.jsonl과 구성 차원을 가중 평결로 축소합니다. 실시간 P0 발견(또는 어떤 심사자가 반대하거나 점수가 기준 미만인 경우)은 meets-expectations를 false로 제한합니다. 평결, P0/P1 백로그 헤드라인, 그리고 수정 에이전트가 사용해야 하는 경로(RESULTS.md, BACKLOG.json, fixes/)를 제시합니다.

CLI 전체의 종료 코드: 0 정상 / 게이트 통과 · 1 게이트 실패(check/verify) · 2 사용법 또는 런타임 오류.

8. (선택 사항) 수정 실행. 각 fixes/FIX-*.md를 빌드 에이전트에 전달하여 TDD를 구현 — 카드는 문제를 다시 도출하지 않고 red→green→refactor 단계를 진행할 수 있도록 작성됩니다.

근거 계약(The grounding contract)

발견 사항은 증거가 확인될 때만 신뢰할 수 있습니다. check는 대상의 각 path:line을 열고 해당 라인이 존재하고 범위 내에 있는지 확인합니다. 오래되었거나 조작된 라인은 하드 실패입니다. verify는 그런 다음 회의론자가 인용된 콘텐츠가 실제로 주장을 지지하는지 질문합니다. 이 2층 게이트(구조적 + 의미론적)가 핵심입니다 — 전체 문법 및 통과/실패 규칙은 references/gate-contract.md에 있습니다.

방법 및 루브릭

  • references/eval-playbook.md — 연구→테스트 계획→실행→판단→결과 방법 및 차원별 점수 루브릭 구축 방법.
  • references/orchestration.md — 생성된 워크플로우, 서브에이전트 디스패치 계약 및 분산을 위한 절대 <skill-dir> 불변성.
  • references/gate-contract.md — findings.json 스키마, 증거 참조 문법 및 check/verify의 통과/실패 조건.
  • references/tdd-remediation.md — BACKLOG.json 구조 및 fixes/FIX-*.md TDD 카드 형식.
  • references/rubric-library.md — 대상 범주별 시작 차원.
  • references/analysis-playbook.md — analyze 신호, 브레인스토밍 렌즈 및 기회가 근거 기반을 유지하는 방법.

안전

  • ultraeval은 대상에서 읽기만 하고 <RUN> 아래에만 씁니다. 대상의 코드를 실행하지 않습니다. 실행자 서브에이전트는 대상의 자체 명령(테스트, 게이트)을 실행할 수 있습니다 — 신뢰할 수 없는 저장소는 샌드박스 처리하십시오.
  • clean --run <RUN>은 파생된 게이트/렌더링 아티팩트만 제거하고 전달물은 유지합니다. --all은 전체 실행을 제거합니다.

관련 스킬