검증 기준을 개발자 에이전트의 스킬·규칙으로 — 코드를 쓰는 시점부터 기준이 적용되게 하기

개념

기준이 문서함에 있으면 배포 직전에 쓰인다

레슨 1에서 다섯 칸짜리 검증 기준을 썼다. 이 기준을 Confluence 페이지에 올려 두면 무슨 일이 생기는가. 개발자는 코드를 쓸 때 그 페이지를 열지 않는다. 개발자의 AI 에이전트는 더더욱 열지 않는다. 기준은 QA가 PR을 리뷰하거나 릴리스 게이트를 돌릴 때에야 쓰이고, 그때 발견된 누락은 이미 다 만든 코드를 되돌리는 비용 이 된다.

모듈 1에서 배운 "결함은 늦게 발견될수록 비싸다"는 원칙이 AI 시대에 새 형태로 돌아온다. 이제 코드의 상당 부분을 에이전트가 쓴다. 그렇다면 기준을 에이전트가 코드를 쓰는 그 순간에 읽게 하면 된다. 채용 공고가 "QA의 검증 기준은 개발자의 AI 에이전트에 스킬로 들어가 코드를 쓰는 시점부터 적용되고"라고 쓰는 구조가 이것이다.

에이전트가 읽는 두 종류의 파일

2025년 말부터 코딩 에이전트가 읽는 파일 형식이 사실상 두 개의 공개 표준으로 수렴했다.

도구마다 자기 이름의 규칙 파일(CLAUDE.md, Cursor 규칙 등)을 따로 갖기도 하지만, 발상은 같다. 항상 지켜야 할 것은 규칙 파일에, 특정 상황에서 따라야 할 절차는 스킬에 둔다.

QA 검증 기준에 적용하면 이렇게 나뉜다.

SKILL.md 명세에서 QA가 알아야 할 것

agentskills.io 명세의 핵심만 추리면 다음과 같다.

skill-name/
├── SKILL.md          필수: 메타데이터 + 지침
├── scripts/          선택: 실행 코드
├── references/       선택: 필요할 때 읽는 문서
└── assets/           선택: 템플릿·데이터

frontmatter 필수 필드는 둘이다.

선택 필드로 license, compatibility(500자 이내), metadata(문자열 키-값), 실험적인 allowed-tools 가 있다.

명세가 권하는 점진적 공개(progressive disclosure) 구조가 QA에게 특히 중요하다.

1. 시작 시 모든 스킬의 name·description 만 로드된다 (스킬당 약 100토큰)
2. 작업이 설명과 맞으면 SKILL.md 본문 전체가 로드된다 (5,000토큰 미만, 500줄 이내 권장)
3. scripts/·references/·assets/ 는 필요할 때만 읽힌다

이 구조의 함의는 두 가지다. 첫째, description이 곧 트리거 다. 설명이 "QA 기준"처럼 막연하면 에이전트가 API 핸들러를 고칠 때 스킬을 불러오지 않는다. 둘째, 기준 전체를 SKILL.md에 붓지 말고 절차는 본문에, 긴 기준 목록과 루브릭은 references에 둔다.

검증 기준 스킬 하나 만들어 보기

---
name: compute-api-verification
description: >-
  Compute API(서버·볼륨·포트·플레이버) 핸들러나 비동기 작업 코드를 추가·수정할 때
  반드시 사용한다. 쿼터 초과, 부분 생성 누수, 비동기 상태 수렴, 멱등성, 프로젝트 간
  권한 격리에 대한 검증 기준을 적용하고 pytest 테스트를 함께 작성한다.
metadata:
  owner: qa-platform
  criteria-version: "2026.09.2"
---
 
# Compute API 검증 기준 적용 절차
 
## 1. 변경 범위 확인
변경한 엔드포인트와 비동기 작업을 나열한다.
 
## 2. 기준 선택
references/criteria-compute.md 에서 해당 엔드포인트의 기준 ID를 모두 고른다.
결정적 기준(D-)과 해석 기준(I-)을 구분해 목록으로 적는다.
 
## 3. 테스트 작성
- 결정적 기준마다 테스트를 하나 이상 만든다. 테스트 이름에 기준 ID를 넣는다.
  예: test_create_server_quota_exceeded__D_COMP_014
- 부정 기준(일어나지 않아야 할 일)을 건너뛰지 않는다.
- 기대값은 references 의 기준에서 가져온다. 현재 구현의 동작에서 가져오지 않는다.
  기준과 구현이 다르면 테스트를 구현에 맞추지 말고 사용자에게 보고한다.
 
## 4. 해석 기준
해석 기준은 테스트로 만들지 않는다. PR 설명의 "해석 판정 대상" 절에 기준 ID와
관찰 방법만 적는다. 판정은 파이프라인의 판정자가 한다.
 
## 5. 누락 확인
scripts/check_criteria_coverage.py 를 실행해 선택한 기준 ID가 모두 테스트 이름에
나타나는지 확인하고, 결과를 PR 설명에 붙인다.

이 스킬에서 가장 중요한 줄은 3단계의 세 번째 항목이다. "기준과 구현이 다르면 테스트를 구현에 맞추지 말고 보고한다." 에이전트는 테스트가 실패하면 통과하도록 고치려는 강한 경향이 있다. 기대값을 고치는 쪽으로 가면 결함이 테스트에 봉인 된다. 스킬은 이 경향을 명시적으로 막아야 한다.

두 번째로 중요한 것은 테스트 이름에 기준 ID 를 넣게 한 것이다. 이 한 가지 규칙으로 기준 → 테스트 추적성이 기계적으로 생기고, 5단계 누락 확인과 레슨 6의 기준 커버리지 지표가 가능해진다.

AGENTS.md에는 무엇을 두는가

AGENTS.md는 항상 로드되므로 짧고 단정해야 한다. QA가 기여할 줄은 많지 않다.

## Testing
- 테스트 실행: `make test-unit`, API 계약 테스트는 `make test-contract`
- 도메인 코드를 변경하면 .agents/skills/ 의 해당 도메인 검증 기준 스킬을 따른다.
- 실패하는 테스트의 기대값을 구현에 맞춰 수정하지 않는다. 기준과 구현이 다르면 멈추고 보고한다.
- 테스트를 skip·xfail 로 바꾸려면 PR 설명에 이유와 결함 티켓 번호를 적는다.

스킬이 저장소 어디에 놓이는지는 도구마다 조금씩 다르다. 조직 공용 스킬 저장소를 두고 각 서비스 저장소가 가져다 쓰는 방식, 서비스 저장소 안에 두는 방식이 있다. 어느 쪽이든 한 곳에서 버전을 관리 하는 것이 요점이다.

버전·소유권·변경 관리

스킬은 코드처럼 다룬다. 기준이 바뀌면 에이전트가 만드는 테스트가 바뀌고, 그것은 곧 판정 기준의 변경 이기 때문이다.

기준 완화에 더 높은 승인을 거는 이유 는 모듈 18c 레슨 7의 "정책을 코드로 — 기대값을 조용히 바꾸지 못하게"와 같다. 게이트를 통과시키는 가장 쉬운 방법은 게이트를 낮추는 것이고, 에이전트든 사람이든 일정 압박을 받으면 그 길을 찾는다.

스킬이 실제로 적용됐는지 어떻게 아는가

스킬을 배포했다고 적용된 것이 아니다. description이 맞지 않아 로드되지 않았을 수도, 로드됐지만 절차를 건너뛰었을 수도 있다. QA는 이것을 가설로 세우고 확인 한다.

마지막 방법은 모듈 18c 레슨 6 과제 3 "게이트를 의도적으로 속여보기"의 스킬 버전이다. 스킬도 테스트 대상 이다.

실무에서 왜 필요한가

AI 에이전트로 개발 속도가 빨라진 팀에서 QA가 PR 끝단에서만 검증하면 두 가지가 무너진다. 리뷰 대기열이 QA 앞에 쌓여 병목이 되고, 늦게 발견된 기준 누락이 재작업으로 돌아온다. DORA 2025 보고서가 다섯 번째 지표로 배포 재작업률 을 전면에 올린 배경도 AI가 처리량을 올리면서 불안정성을 함께 키운다는 관찰이었다.

기준을 스킬로 배포하면 QA의 영향력이 PR 한 건 단위에서 에이전트가 쓰는 모든 코드 단위로 커진다. 한 번 잘 쓴 스킬이 수십 명의 개발자와 그들의 에이전트에 동시에 적용된다. 대신 스킬의 결함도 그만큼 넓게 퍼진다. 그래서 스킬에 버전·소유권·변경 리뷰가 필요하고, 스킬 자체를 시험해야 한다.

우대사항의 "에이전트가 쓰는 스킬·규칙을 만들어 본 경험"은 SKILL.md를 써 봤다는 뜻보다, 스킬이 적용됐는지 어떻게 확인했고 어떤 실패를 막았는지 를 설명할 수 있느냐로 평가된다.

실습 과제

과제 1 — 스킬과 규칙 나누기 (10분)

아래 항목을 AGENTS.md·스킬 본문·스킬 references·스킬 scripts 중 어디에 둘지 분류하고 이유를 적는다.

1. 테스트 실행 명령
2. 학습 작업 API 의 체크포인트 재개 검증 기준 23개
3. 로그 요약 품질 판정 루브릭
4. "실패 테스트의 기대값을 구현에 맞춰 고치지 않는다"
5. 기준 ID 누락 검사 스크립트
6. 추론 엔드포인트 변경 시 따라야 할 테스트 작성 5단계

과제 2 — description 다시 쓰기 (15분)

description이 QA 검증 기준 모음 인 스킬을, 에이전트가 올바른 작업에서 불러오도록 1024자 이내로 다시 쓴다. 무엇을 하는지·언제 쓰는지·트리거 키워드가 모두 들어가야 한다. 스킬을 불러오면 안 되는 작업도 한 문장 넣어 본다.

과제 3 — 검증 기준 스킬 작성 (30분)

레슨 1 과제 2에서 쪼갠 "추론 엔드포인트 삭제" 기준으로 inference-endpoint-verification 스킬을 만든다. 명세의 name 규칙을 지키고, 기대값을 구현에서 가져오지 않게 하는 지침과 기준 ID를 테스트 이름에 넣는 규칙을 포함한다.

과제 4 (선택) — 스킬 적용 시험 설계 (15분)

과제 3의 스킬이 "기준과 구현이 다르면 멈추고 보고"를 실제로 지키는지 확인할 시험을 설계한다. 에이전트에게 줄 과제 문장, 일부러 심을 결함, 통과·실패 관찰 기준을 적는다.

자가 체크리스트

• 기준이 문서함에 있을 때와 에이전트 스킬로 배포될 때 적용 시점이 어떻게 달라지는지 설명할 수 있다
• AGENTS.md와 Agent Skills의 역할 차이와 로드 시점을 구분할 수 있다
• SKILL.md의 필수 필드 두 개와 name 규칙을 말할 수 있다
• 점진적 공개 구조에 맞춰 절차·기준 목록·루브릭·스크립트를 나눠 둘 수 있다
• description이 트리거 역할을 한다는 것을 알고 키워드를 넣어 쓸 수 있다
• 기대값을 구현에 맞춰 고치지 못하게 하는 지침을 스킬에 넣는다
• 테스트 이름에 기준 ID를 넣어 추적성을 만드는 이유를 안다
• 스킬의 버전·소유권·기준 완화 승인 규칙을 설계할 수 있다
• 스킬이 실제로 적용됐는지 확인하는 방법을 두 가지 이상 말할 수 있다

흔한 실수

모든 기준을 SKILL.md 본문에 붓는다. 스킬이 불려올 때마다 컨텍스트를 채운다. 긴 목록은 references로.

description을 짧고 추상적으로 쓴다. 로드되지 않는 스킬은 없는 스킬이다.

"테스트를 통과시켜라"라고만 쓴다. 에이전트는 기대값을 고쳐서 통과시킨다. 기대값의 출처를 기준으로 못 박는다.

스킬을 QA 개인 저장소에 둔다. 버전·소유권·리뷰 없이 바뀐 기준은 판정 기록과 어긋난다.

배포했으니 적용됐다고 가정한다. 스킬도 가설이다. 적용 여부를 지표와 의도적 시험으로 확인한다.

참고 자료

• Agent Skills Specification (agentskills.io)
• agentskills/agentskills — 명세와 skills-ref 검사기 (GitHub)
• Linux Foundation Announces the Formation of the Agentic AI Foundation — MCP·goose·AGENTS.md 기증 (2025-12)
• The DORA 4 key metrics become 5 (CD Foundation, 2025-10)
• 이 커리큘럼 안: 모듈 18a 레슨 8 「QA를 위한 Claude Skills」, 모듈 18c 레슨 6 「에이전트 하네스와 품질 게이트」·레슨 7 「정책을 코드로」, 모듈 38 레슨 1