AI 튜토리얼

지속적인 AI 지원 코드 품질 평가에 Jev Review 사용하기

Jev Review를 로컬 MCP 서버로 설치하고, 지원되는 코딩 에이전트에 연결하며, 평가를 위해 변경 사항을 선별해 제출하고, 반복 작업 간 점수를 비교하고, Jev API 사용 중 민감한 저장소 데이터를 보호하는 방법을 알아보세요.

2026년 9월 17일약 15분 소요

Jev Review란?

Jev Review는 AI 코딩 에이전트가 작업하는 동안 구조화된 소프트웨어 품질 신호를 제공하는 로컬 Model Context Protocol 서버입니다. Claude Code, Codex, Cursor, OpenCode를 지원하며 jev_review라는 하나의 전용 MCP 도구를 제공합니다.

이 도구는 정확성, 복잡성, 가독성, 모듈성, 테스트 품질, 안정성, 보안, 유지 관리 가능성 등 서로 독립적인 기준으로 코드를 평가합니다. 설명식 코드 리뷰 에세이 대신 수치 점수, 신뢰도 값, 적용 가능성 지표, 미리 정의된 평가 기준 힌트를 반환합니다.

Jev는 품질 신호를 제공하지만, 주요 코딩 에이전트는 약점 진단, 코드 변경, 결과 검증을 계속 담당합니다.

Jev Review는 MCP stdio를 통해 로컬 Node.js 프로세스로 실행됩니다. 호스팅 백엔드, 데이터베이스, 텔레메트리 서비스 또는 제작자가 운영하는 프록시를 사용하지 않습니다. 명시적으로 제공된 리뷰 컨텍스트가 포함된 요청은 구성된 Jev API로 직접 전송됩니다.

주요 기능

지속적인 평가: 작업이 끝날 때까지 기다리지 않고, 일관된 구현 단위가 완료될 때마다 변경 사항을 검토합니다.
독립적인 품질 기준: 적용 가능한 각 지표에는 1~10의 개별 점수와 0~1의 신뢰도 값이 부여됩니다.
반복 비교: 이전 평가를 제공하여 개선 사항, 회귀, 해결되지 않은 약점을 확인합니다.
집중된 컨텍스트: 작업, diff, 선택한 파일, 저장소 컨텍스트 또는 이들의 적절한 조합을 제출합니다.
로컬 실행: 지원되는 모든 클라이언트는 stdio를 통해 동일한 번들 dist/server.js 프로세스를 실행합니다.
자동 저장소 접근 없음: 서버는 도구에 명시적으로 전달된 컨텍스트만 처리합니다.
인위적인 종합 점수 없음: Jev Review는 오해를 불러일으킬 수 있는 백분율로 결과를 혼합하지 않고 기준별 결과를 유지합니다.

사전 요구 사항

Jev Review를 설치하기 전에 다음을 준비하세요.

Node.js 20 이상.
TypeSafe 콘솔에서 발급한 Jev API 키.
Claude Code, Codex, Cursor 또는 OpenCode.

빠른 설치

1. API 키 내보내기

코딩 클라이언트를 실행하기 전에 환경 변수에 키를 설정하세요.

export JEV_API_KEY="your-key"

실제 키를 프롬프트, 소스 파일, diff 또는 커밋된 구성에 넣지 마세요.

2. GitHub에서 플러그인 설치

Jev Review는 npm에 게시된 패키지가 아니라 GitHub 저장소에서 직접 배포됩니다.

npx plugins add NiazMorshed2007/jev-review

메시지가 표시되면 코딩 클라이언트를 선택하고, 클라이언트를 다시 시작한 뒤 MCP 서버가 연결되었는지 확인하세요.

3. 리뷰 요청

중요한 변경 사항을 구현하고 테스트한 후 코딩 에이전트에 Jev Review를 사용하도록 요청하세요. 예를 들면 다음과 같습니다.

요청된 인증 변경을 구현하고 관련 테스트를 실행한 다음, 집중된 diff에 jev-review를 사용하세요. 중요한 기준 중 가장 취약한 항목을 점검하고, 타당한 개선 사항만 적용한 뒤 최종 전달 전에 다시 점수를 산정하세요.

클라이언트별 설정

Claude Code

Claude Code 대상을 명시적으로 설치하세요.

npx plugins add NiazMorshed2007/jev-review --target claude-code

Claude Code를 다시 시작하고 /mcp를 실행하여 jev-review가 연결되었는지 확인하세요.

수동으로 MCP만 구성하려면 Claude Code가 번들 서버를 사용하도록 설정하세요.

claude mcp add --scope user jev-review -- node /absolute/path/to/jev-review/dist/server.js

로컬 클론에서 개발하는 경우 플러그인 디렉터리를 직접 로드할 수 있습니다.

claude --plugin-dir /absolute/path/to/jev-review

Codex

Codex 대상을 설치하고 클라이언트를 다시 시작하세요.

npx plugins add NiazMorshed2007/jev-review --target codex

/mcp를 실행하여 연결을 확인하세요. 수동으로 구성하려면 ~/.codex/config.toml에 다음 서버 정의를 추가하세요.

[mcp_servers.jev-review]
command = "node"
args = ["/absolute/path/to/jev-review/dist/server.js"]
env_vars = ["JEV_API_KEY"]

Cursor

Cursor 대상을 설치하세요.

npx plugins add NiazMorshed2007/jev-review --target cursor

Cursor를 다시 시작하고 Settings → MCP를 확인하세요. 번들 스킬의 이름은 jev-review입니다. /jev-review로 호출하거나 Agent Decides로 설정해 둘 수 있습니다.

수동으로 설정하려면 ~/.cursor/mcp.json을 만들거나 업데이트하세요.

{
  "mcpServers": {
    "jev-review": {
      "type": "stdio",
      "command": "node",
      "args": ["/absolute/path/to/jev-review/dist/server.js"],
      "env": {
        "JEV_API_KEY": "${env:JEV_API_KEY}"
      }
    }
  }
}

macOS에서 Dock으로 실행한 Cursor는 셸 프로필의 변수를 상속하지 않을 수 있습니다. Cursor를 시작하기 전에 GUI 애플리케이션에서 내보낸 키를 사용할 수 있도록 설정하세요.

launchctl setenv JEV_API_KEY "$JEV_API_KEY"

값을 출력하지 않고 변수가 존재하는지 확인하세요.

test -n "$(launchctl getenv JEV_API_KEY)" && echo "JEV_API_KEY is configured"

OpenCode

현재 OpenCode는 이식 가능한 설치 대상 목록에 포함되어 있지 않습니다. 저장소를 클론하고 번들 서버를 수동으로 등록하세요.

git clone https://github.com/NiazMorshed2007/jev-review.git
cd jev-review
opencode mcp add jev-review --global -- node "$PWD/dist/server.js"

스킬과 MCP 서버 모두에 대해 ~/.config/opencode/opencode.json에 다음과 같은 설정을 추가하고, 절대 경로를 실제 경로로 바꾸세요.

{
  "$schema": "https://opencode.ai/config.json",
  "skills": ["/absolute/path/to/jev-review/skills"],
  "mcp": {
    "servers": {
      "jev-review": {
        "type": "local",
        "command": ["node", "/absolute/path/to/jev-review/dist/server.js"],
        "environment": {
          "JEV_API_KEY": "{env:JEV_API_KEY}"
        }
      }
    }
  }
}

opencode mcp list를 실행하여 연결을 확인하세요. OpenCode에서는 도구가 jev-review_jev_review로 표시될 수 있지만, 기본 MCP 이름은 jev_review로 유지됩니다.

도구 입력 이해하기

jev_review 도구는 다음 구조를 허용합니다.

{
  task?: string;
  diff?: string;
  files?: Array<{
    path: string;
    content: string;
  }>;
  repositoryContext?: string;
  previousEvaluation?: Evaluation;
}

현재 컨텍스트를 나타내는 필드가 하나 이상 필요합니다. 대부분의 경우 작업과 범위를 좁힌 diff를 보내세요. 변경 사항을 이해하는 데 주변 구현 세부 정보가 필요한 경우에만 전체 파일을 추가하세요.

개념적인 요청에는 다음과 같은 내용이 포함될 수 있습니다.

{
  "task": "계정 생성 엔드포인트에 입력 검증 추가",
  "diff": "<focused version-control diff>",
  "repositoryContext": "리포지토리의 기존 검증 규칙을 사용하는 Node.js 서비스"
}

이 예시는 입력 형식을 보여 줍니다. 일반적으로 코딩 클라이언트가 사용자를 대신해 MCP 도구를 호출합니다.

권장 평가 워크플로

작업을 이해합니다. 리포지토리, 요구 사항, 규칙 및 관련 테스트를 검토합니다.
일관된 단위를 구현합니다. 사소한 변경을 모두 검토하기보다 변경 사항의 의미 있는 부분을 완성합니다.
관련 검사를 실행합니다. 추가 작업을 안내할 점수를 요청하기 전에 동작을 검증합니다.
기준선을 설정합니다. 작업과 범위를 좁힌 diff를 포함해 jev_review를 호출합니다.
취약한 항목을 조사합니다. 코딩 에이전트가 구현을 검토하고 각 주요 취약점에 대한 구체적인 가설을 세우도록 합니다.
정당화할 수 있는 최소한의 개선을 적용합니다. 추측에 기반한 재작성이나 불필요한 아키텍처 변경을 피합니다.
다시 검증합니다. 테스트, 타입 검사, 린터 또는 프로젝트에 적합한 기타 검사를 다시 실행합니다.
이력을 포함해 재평가합니다. 이전 결과를 previousEvaluation으로 전달하여 지표별 비교를 확인합니다.
적절한 시점에 멈춥니다. 요구 사항과 검사를 통과했고 추가 점수 향상이 실질적인 가치를 거의 더하지 않을 때 마무리합니다.

예를 들어 비교 결과에 가독성이 6.3 → 8.1로 향상되었지만 보안은 8.2 → 8.2로 유지되었다고 표시될 수 있습니다. 이는 어떤 품질 차원이 변경되었는지 정확히 보여 주므로 단일 종합 점수보다 유용합니다.

품질 차원

핵심 차원

제공된 컨텍스트가 충분하면 Jev Review는 다음 항목을 평가합니다.

정확성과 요구 사항 부합 여부
인지 복잡도
가독성과 의도
모듈성과 응집도
결합도와 의존성 품질
변경 용이성과 변경 증폭
추상화와 API 설계
프로젝트 및 파일 구조
중복과 재사용
유지 보수성
테스트 가능성과 테스트 품질
신뢰성과 오류 처리
보안
일관성과 규칙
문서화와 설명 가능성

컨텍스트에 따른 차원

다음 차원은 관련 증거를 확인할 수 있을 때만 평가합니다.

성능과 리소스 효율성
확장성과 유연성
호환성과 API 안정성
관찰 가능성과 운영성

제공된 컨텍스트만으로 특정 차원을 평가할 수 없으면 결과에 { "applicable": false }가 사용됩니다. 평가자는 더 짧은 함수, 더 작은 파일, 추가 계층, 더 많은 주석, 중복 제거 또는 더 많은 테스트가 자동으로 더 낫다고 가정하지 않습니다.

고급 팁

검토 컨텍스트를 집중적으로 구성하기

작업과 구현을 담은 가장 작고 일관된 diff를 보내세요. 컨텍스트를 생략하면 신뢰할 수 있는 평가가 불가능한 경우에만 전체 파일을 포함하세요. 집중된 제출은 코딩 에이전트가 피드백을 해석하기 쉽게 만듭니다.

Jev Review는 자체적인 문자 수, 토큰 수 또는 파일 수 제한을 추가하지 않습니다. 그러나 jev-latest API의 실제 동작에 따르면 제출 상태의 한도는 약 32,768토큰입니다. 이 제한은 API 문서에 공개되어 있지 않으며 변경될 수 있습니다. API가 max_tokens_exceeded를 반환하면 관련 없는 컨텍스트를 제거하거나 작업을 일관된 검토 단위로 나누세요.

제어된 반복 작업에 이전 평가 사용하기

재평가할 때 전체 이전 결과를 previousEvaluation으로 전달하세요. Jev Review는 이전 결과를 로컬에서 비교하고 지표별 차이, 개선 사항, 회귀 및 해결되지 않은 취약점을 보고합니다. 이전 평가는 Jev에 전송되는 현재 코드 컨텍스트에 포함되지 않습니다.

수정하기 전에 진단하기

낮은 점수는 신호일 뿐 근본 원인에 대한 설명은 아닙니다. 코딩 에이전트에게 구현을 검토하고 취약점의 근거를 식별한 뒤 최소한의 수정안을 제안하도록 요청하세요. 단순히 숫자를 올리기 위해 코드를 다시 작성하지 마세요.

점수보다 요구 사항을 우선하기

올바른 동작과 사용자 요구 사항은 항상 점수 향상보다 우선합니다. 더 높은 점수는 동작을 깨뜨리거나, 범위를 확대하거나, 의미 없는 테스트를 추가하거나, 추측에 기반한 추상화를 도입하거나, 불필요한 계층을 만드는 일을 정당화하지 않습니다.

전용 보안 도구도 함께 사용하세요

보안은 평가 기준 중 하나이지만, Jev Review는 의존성 스캐너, 비밀 정보 탐지, 정적 분석, 침투 테스트 및 기타 전용 보안 제어 기능을 대체하지 않고 보완합니다.

보안 및 개인정보 보호

로컬 MCP 프로세스는 JEV_API_KEY를 읽고, 이를 https://api.typesafe.ai/v1/systemone으로 직접 전송되는 TLS Authorization 헤더에만 사용합니다. Jev Review는 키를 저장하거나 로그에 기록하지 않습니다.

도구에 명시적으로 제공된 task, diff, files, repositoryContext만 Jev로 전송됩니다. 서버는 저장소 파일을 자동으로 검색하거나 업로드하지 않습니다.

검토 컨텍스트는 TypeSafe의 Jev API를 통해 사용자의 컴퓨터 밖으로 전송됩니다. 비밀 정보나 관련 없는 독점 자료는 제출하지 마세요.

원격 서비스가 제출된 데이터를 처리하는 방법은 TypeSafe의 개인정보 보호정책을 참조하세요.

로컬에서 Jev Review 개발하기

프로젝트 자체를 작업하려면 저장소를 복제하고, 의존성을 설치한 다음, 검증을 실행하세요.

git clone https://github.com/NiazMorshed2007/jev-review.git
cd jev-review
npm install
npm run validate

유용한 개발 명령어는 다음과 같습니다.

npm run check
npm test
npm run build
npx plugins discover .
claude plugin validate . --strict

npm run build는 커밋된 dist/server.js 번들을 생성합니다. 단위 테스트와 MCP 프로토콜 테스트는 로컬 가짜 구현을 사용하므로 Jev API 할당량을 소모하지 않습니다. 실제 Jev 요청에는 JEV_API_KEY가 필요합니다.

결론

Jev Review는 구현을 직접 제어하지 않으면서 지원되는 AI 코딩 클라이언트에 체계적인 품질 피드백 루프를 추가합니다. 로컬 MCP 서버를 설치하고, 의미 있는 변경 후 집중된 컨텍스트를 제출하며, 차원별 결과를 활용해 신중한 개선을 이끌고, 반복 작업 간 평가를 비교하세요. 점수를 목표가 아닌 근거로 보고, 요구사항과 검사 및 실제 품질 요구가 충족되면 멈추세요.