Validator 메시지 형태
개요
validator는 단순한 검사기가 아니다.
실무에서는 validator 출력이 곧 수정 인터페이스가 된다.
메시지가 약하면 팀은 규칙을 이해하지 못하고, AI는 같은 위반을 다른 형태로 반복한다. 그래서 validator message는 로그 문장이 아니라 행동을 유도하는 계약으로 설계해야 한다.
validator 출력이 가져야 할 최소 정보
좋은 validator 메시지는 보통 다음 정보를 담는다.
- 위반 코드나 규칙 식별자
- 위반된 대상의 위치
- 무엇이 관측되었는가
- 무엇이 허용되는가
- 어디를 보면 되는가
예를 들어 invalid access보다
BOUNDARY-012: feature/foo may not import core/internal/bar; use core/public/baz가 훨씬 낫다.
핵심은 설명이 길어지는 것이 아니라, 수정 경로가 하나로 좁혀지는 것이다.
규칙 식별자는 생각보다 중요하다
규칙 이름이나 code가 없으면 다음 문제가 생긴다.
- 같은 위반을 검색하고 묶기 어렵다
- 리뷰 코멘트가 매번 새 문장으로 흩어진다
- 문서, lint, runtime guard를 같은 규칙으로 연결하기 어렵다
- AI가 같은 실패를 사례로 학습하기 어렵다
validator는 가능하면 stable identifier를 가져야 한다. 그래야 실패가 기록과 분석의 단위가 된다.
위치 정보는 최대한 정확해야 한다
위반 위치가 흐리면 수정 범위가 급격히 넓어진다.
좋은 위치 정보의 예:
- 파일과 import 구문
- 잘못된 field나 parameter 이름
- 금지된 transition의 출발/도착 상태
- 우회된 API entry point
반대로 validation failed in module X 같은 메시지는
실패를 알리기는 하지만 수정엔 거의 도움이 되지 않는다.
허용되는 대안을 같이 보여줘야 한다
validator가 나쁜 점을 말하는 데서 멈추면, 사람도 AI도 주변 코드에서 대안을 추측한다. 이때 가장 가까운 shortcut이 다시 선택되기 쉽다.
그래서 가능한 경우 다음을 같이 알려주는 것이 좋다.
- 사용해야 하는 public API
- 합법적인 import path
- 허용되는 state transition
- canonical helper 혹은 facade
- 관련 문서나 rule 설명 위치
validator의 목적은 처벌이 아니라 복귀 경로 안내다.
사람과 AI가 모두 읽기 쉬운 형태
AI 코딩이 섞이면 메시지는 더 구조적일수록 좋다.
- 규칙 식별자는 짧고 안정적이어야 한다
- 위치 정보는 파싱 가능한 형태가 좋다
- 허용 대안은 애매한 서술보다 명시적 이름이 낫다
- 한 메시지에 여러 위반을 섞기보다 개별 항목으로 분리하는 편이 낫다
이런 형태는 사람에게도 좋고, AI가 수정 계획을 세울 때도 훨씬 유리하다.
나쁜 validator 메시지 패턴
- 위반 이유 없이
not allowed만 말한다 - 내부 구현 용어만 나열하고 수정 지점을 알려주지 않는다
- 여러 규칙을 한 문장에 뭉개서 보여준다
- 허용 대안이 없어서 결국 문서를 뒤지게 만든다
- warning으로 끝나서 구조 위반이 중요하게 느껴지지 않는다
validator가 애매하면 규칙은 존재해도 작동하지 않는다.
실무 질문
- 같은 위반을 code 하나로 묶어 추적할 수 있는가
- 메시지만 보고 수정 위치를 바로 찾을 수 있는가
- 허용 경로가 명시되어 있는가
- 문서, lint, runtime guard가 같은 규칙 명칭을 공유하는가
- AI가 이 메시지를 보고 더 넓은 우회가 아니라 올바른 수정으로 수렴할 수 있는가
요약
좋은 validator message shape는 다음을 가진다.
- stable rule identifier
- 정확한 위치 정보
- 현재 관측값과 허용 대안
- 사람이든 AI든 다음 행동을 좁힐 수 있는 구조
validator 출력은 로그가 아니라, 규칙 위반을 수정 행동으로 번역하는 인터페이스다.