당신은 코드를 테스트합니다. 왜 AI 지시를 테스트하지 않나요?

발행: 7시간 전 (2026년 4월 4일 AM 06:38 GMT+9)

12 분 소요

원문: Dev.to

Source: Dev.to

왜 모델 선택보다 지시문의 품질이 더 중요한가, 그리고 이를 측정하는 도구

AI 코딩 도구를 사용하는 모든 팀은 지시문 파일을 작성합니다:

CLAUDE.md (Claude Code용)
AGENTS.md (Codex용)
copilot‑instructions.md (GitHub Copilot용)
.cursorrules (Cursor용)

여러분은 이 파일들을 만들기에 시간을 투자하고, 문단을 바꾸고, 푸시한 뒤 최선을 기대합니다.

여러분의 코드베이스에는 테스트가 있습니다. 여러분의 API에는 계약이 있습니다. 여러분의 AI 지시문에는… 기대가 있습니다.

저는 이를 해결하기 위해 agenteval 를 만들었습니다.

아무도 테스트하지 않는 변수

최근 연구에서는 731개의 코딩 문제에 동일한 모델을 실행하는 세 가지 에이전트 프레임워크를 테스트했습니다. 같은 모델. 같은 작업. 차이점은 오직 지시문 구조뿐이었습니다.

그 차이는 17점이었습니다.

우리는 어떤 모델을 사용할지—Sonnet vs Opus vs GPT‑5.4—에 집착합니다. 하지만 모델에 제공하는 지시문이 모델 자체보다 결과에 더 큰 영향을 미칩니다. 그리고 그 지시문은 아무도 테스트하지 않습니다.

생각해 보세요. 테스트 없이 API를 배포하지 않을 겁니다. CI 없이 기능을 출시하지 않을 겁니다. 그런데 AI가 코드를 작성하도록 제어하는 파일은? 텍스트 편집기로 수정하고 기대할 뿐입니다.

지시 파일에서 잘못된 점

지금까지 많은 지시 파일을 검토해 보았습니다. 동일한 문제가 어디서든 나타납니다.

죽은 참조

6개월 전 src/auth.ts를 src/authentication.ts로 이름을 바꿨습니다. 그런데 아직도 지시 파일에 “인증 모듈은 src/auth.ts를 참고하세요.” 라고 적혀 있습니다. AI는 그 지시를 읽고 존재하지 않는 파일을 찾으려다 혼란스러워합니다.

가장 흔한 문제 – 3개월 이상 된 거의 모든 지시 파일에 최소 하나 이상의 죽은 참조가 있습니다.

컨텍스트 예산을 잡아먹는 불필요한 문구

“항상 모든 것을 철저히 테스트하고 모든 엣지 케이스를 포괄적으로 다루도록 보장하십시오.”

이 문장은 25 토큰을 소모하지만 모델이 이미 알고 있는 내용만을 반복합니다. 200 K 컨텍스트 창과 30 % 지시 예산을 가정하면 약 60 000 토큰을 사용할 수 있습니다. “항상 …”에 쓰인 토큰 하나하나가 실제 코드 컨텍스트에 사용할 수 없는 토큰이 됩니다.

가장 많이 쓰이는 불필요 문구: “중요한 것은”, “위해서는”, “결국”, “반드시 해야 한다”, “확인해 주세요”. 어디에나 있습니다.

모순

코드 스타일 섹션에 “항상 세미콜론을 사용한다.” 라고 적힌 뒤, 몇 섹션 뒤에 “Prettier 설정을 따르라.” 라고 적혀 있는데 Prettier는 세미콜론을 제거합니다. 모델은 서로 충돌하는 지시를 받아 무작위로 하나를 선택합니다.

여러 사람이 몇 달에 걸쳐 파일을 관리할 때 이런 일은 생각보다 흔합니다.

컨텍스트 예산 초과

CLAUDE.md가 300줄, AGENTS.md가 200줄, copilot‑instructions.md가 150줄입니다. 이들을 모두 합치면 코드 한 줄도 로드되지 않은 상태에서 **40 %**의 모델 컨텍스트 창을 차지합니다.

지시가 많아질수록 AI 성능은 균일하게 저하됩니다. 나중에 있는 지시가 무시되는 것이 아니라, 모든 지시가 덜 정확하게 수행됩니다.

파일 간 중복

CLAUDE.md에 “TypeScript strict mode 사용, 들여쓰기는 탭.” 라고 적히고, AGENTS.md에도 같은 내용이 반복됩니다. 토큰이 중복되어 실제 가치는 0입니다. 더 나아가 한 파일을 수정하고 다른 파일을 잊어버리면 두 파일이 서로 달라져 모순이 생깁니다.

agenteval이 하는 일

agenteval은 CLI 도구입니다. 설치하고, 한 번의 명령을 실행하면 무엇이 잘못됐는지 확인할 수 있습니다.

curl -fsSL https://raw.githubusercontent.com/lukasmetzler/agenteval/main/install.sh | bash
agenteval lint

이 도구는:

당신의 instruction 파일을 읽고
마크다운을 파싱하며
토큰 수를 계산하고
파일 참조를 확인하고
실행 가능한 제안을 포함한 실제 문제를 보고합니다

LLM이 개입하지 않습니다. 결정론적이며 1초 이내에 실행됩니다.

예시 출력 (내 프로젝트에서 실행)

CLAUDE.md
  ERROR  Referenced file "docs/schema.md" does not exist
         → Remove the reference or create the missing file
  INFO   Section "Testing" contains 1 filler phrase(s)
         → Rewrite without phrases like "make sure to"
  INFO   Vague instruction: "be careful with error handling"
         → Replace with a specific example or threshold

각 문제마다 구체적인 제안이 제공되므로, 무엇을 해야 할지 고민할 필요가 없습니다.

지원되는 instruction 포맷

포맷	설명
`CLAUDE.md`	Claude Code
`AGENTS.md`	OpenAI Codex
`.github/copilot-instructions.md` & scoped `.instructions.md`	GitHub Copilot
`.cursorrules`	Cursor
`.claude/skills/*/SKILL.md`	Anthropic skills

Beyond linting: measuring instruction quality over time

Linter는 정적으로 문제를 잡아냅니다. 하지만 여러분의 instruction 변경이 실제로 AI의 성능을 향상시켰는지 알고 싶다면 어떻게 할까요?

agenteval은 보다 깊은 파이프라인을 제공합니다:

Harvest – Git 히스토리를 스캔하여 AI‑보조 커밋을 찾아냅니다. 14개의 도구(Claude, Copilot, Cursor, Devin, Aider, Amazon Q, Gemini, …)를 감지하고, 그로부터 재생 가능한 벤치마크 작업을 생성합니다. 각 작업에는 해당 커밋 시점의 instruction 파일 스냅샷이 포함됩니다. 인위적인 테스트 케이스가 필요 없으며, 여러분의 Git 히스토리가 바로 벤치마크가 됩니다.
Run – 격리된 Git worktree에서 AI 에이전트에게 작업을 주고, 생성된 결과물을 캡처한 뒤 네 가지 차원으로 점수를 매깁니다:
- Correctness (올바른 파일을 변경했는가?)
- Precision (필요한 부분만 변경했는가?)
- Efficiency (사용된 토큰 수는 얼마인가?)
- Conventions (스타일 규칙을 따랐는가?)
Compare – 두 실행을 나란히 비교합니다. instruction 파일을 수정하고 동일한 작업을 다시 실행하여 점수가 개선됐는지 확인합니다. 두 실행 모두에 instruction 스냅샷이 있으면, 점수 변화와 함께 instruction에 어떤 변화가 있었는지 정확히 보여줍니다.
CI – 모든 작업을 실행하고, instruction 품질이 저하되면 빌드를 실패시킵니다.

TL;DR

Instruction 품질은 AI‑생성 코드에 모델 선택보다 더 큰 영향을 미칩니다.
agenteval을 사용하면 instruction 파일을 lint하고, 벤치마크하며, 지속적으로 모니터링할 수 있어 코드와 동일한 수준의 엄격함을 적용할 수 있습니다.

GitHub Actions 워크플로에 Merge‑Gate 라인 추가

GitHub Actions 워크플로에 한 줄을 추가하고, 테스트와 마찬가지로 지시문 품질을 merge gate로 만드세요:

- run: agenteval ci

누군가 PR에서 지시문을 변경했는데 품질이 임계값 이하로 떨어지면 빌드가 실패합니다.

실시간 검토

실시간 검토는 커밋 전에 작업 트리 변경 사항을 점수화합니다.

변경 사항이 집중되어 있나요, 아니면 흩어져 있나요?
테스트를 업데이트했나요?
디버그 아티팩트가 남아 있나요?

--analyze를 추가하면 차이를 AI 도구에 보내 규칙 준수 점수를 매깁니다.

트렌드

Trends는 시간에 따라 점수를 추적합니다.

이번 분기에 팀이 지시문 작성에 더 능숙해지고 있나요?
어떤 작업이 개선되고 있나요?
어떤 작업이 악화되고 있나요?

불편한 질문

팀이 어떤 AI 모델을 사용할지 토론하는 데 얼마나 많은 시간을 보냈나요?
그렇다면, 여러분은 실제로 지시 파일이 작동하는지 테스트하는 데 얼마나 많은 시간을 보냈나요?

모델은 상품에 불과합니다. 지시는 여러분의 경쟁력입니다.

시도해 보기

curl -fsSL https://raw.githubusercontent.com/lukasmetzler/agenteval/main/install.sh | bash
agenteval lint

한 줄 명령어. 독립 실행형 바이너리. Linux와 macOS에서 작동합니다. 명령 파일이 있는 모든 프로젝트에 지정하고 어떤 결과가 나오는지 확인해 보세요.

Repo:

사용해 보신다면, 어떤 문제가 잡히고 어떤 검사가 누락됐는지 알려주세요.