막기 전에 알려 주는 것이 개발자 경험이다

한 줄 요약

가드레일은 "막는다" 와 "알려 준다" 를 나눠서 배치해야 합니다. 규칙은 한 곳에 정의하고 여러 자리에서 실행하며, 각 규칙에는 식별자와 고치는 방법 이 함께 붙어야 지표도 되고 안내도 됩니다.

왜 이게 필요했나

플랫폼 팀이 규칙을 강제하기로 하면 대개 어드미션 웹훅부터 답으로 나옵니다. 그런데 어드미션은 가장 마지막 자리 입니다. 개발자는 코드를 쓰고, 커밋하고, 파이프라인을 돌리고, 이미지를 만들고, 배포를 눌러서, 그제야 "리소스 요청이 없습니다" 를 듣습니다. 고치는 데 1분 걸리는 문제를 알아내는 데 30분이 걸립니다.

반대로 전부 앞에서 막으면 다른 문제가 생깁니다. 규칙 하나하나가 다 필수가 되면, 시제품을 하루 만에 띄우려던 팀은 플랫폼을 우회할 방법을 찾습니다. 우회가 시작되면 규칙의 수는 늘어나는데 실제 준수율은 떨어지고, 플랫폼 팀은 그 사실조차 모릅니다.

그래서 질문을 두 개로 나눠야 합니다. 이 규칙은 어겼을 때 무엇이 위험한가, 그리고 어디에서 알려 주는 것이 가장 싼가 입니다.

어떻게 동작하나

규칙에는 식별자·심각도·고치는 법이 붙습니다

규칙을 문장으로만 쓰면 세지도 못하고 안내하지도 못합니다. 규칙 하나를 다음 세 가지와 함께 정의합니다.

| 항목 | 왜 필요한가 |
| --- | --- |
| 식별자(예: PR001) | 준수율을 규칙별로 셀 수 있고, 예외를 규칙 단위로 줄 수 있다 |
| 심각도(block · warn) | 막을 것과 알려만 줄 것을 갈라 놓아야 우회가 줄어든다 |
| 고치는 법 | 진단 결과를 읽은 사람이 다음에 무엇을 할지 알게 된다 |

심각도를 가르는 기준은 취향이 아닙니다. 어겼을 때 다른 사람에게 피해가 가는가 를 봅니다. 태그가 latest 인 이미지는 롤백을 불가능하게 만들고 클러스터 전체의 재현성을 깨뜨리므로 막을 값어치가 있습니다. 반면 준비 프로브가 없는 것은 그 서비스 자신의 가용성 문제라서, 알려 주고 팀이 판단하게 하는 편이 낫습니다.

같은 규칙을 여러 자리에서 실행합니다

규칙의 정의는 한 곳에 두고, 실행은 여러 자리에서 합니다.

1. 편집기와 로컬 명령 — 가장 싸고 가장 빠릅니다. 다만 실행 여부가 사람에게 달려 있습니다.
2. 커밋 훅 — 커밋 직전에 돕니다. 로컬 파일이라 우회할 수 있으므로 마지막 방어선이 될 수 없습니다.
3. CI — 저장소 밖에서 도는 첫 자리입니다. 여기서부터는 우회가 기록에 남습니다.
4. 어드미션 — 클러스터에 들어오는 마지막 관문입니다. 여기서만 막으면 피드백이 가장 늦습니다.

앞자리는 빠른 피드백 을 담당하고 뒷자리는 보장 을 담당합니다. 앞자리만 두면 지켜지지 않고, 뒷자리만 두면 늦게 알게 됩니다.

출력은 사람용과 기계용을 함께 냅니다

진단기가 사람에게는 읽기 좋은 줄을, 프로그램에는 JSON 을 주면 같은 도구가 여러 자리에서 쓰입니다. 종료 코드도 규약입니다. 위반이 하나라도 있으면 0 이 아닌 값으로 끝나야 파이프라인이 그것을 신호로 쓸 수 있습니다. 이런 계약이 없으면 자리마다 다른 도구를 만들게 되고, 자리마다 규칙이 조금씩 달라집니다.

준수율은 채택 지표가 됩니다

같은 진단기를 저장소 전체에 돌리면 규칙별 준수율 이 나옵니다. 이 숫자는 플랫폼 팀이 다음에 무엇을 만들지 정하는 근거가 됩니다. 특정 규칙만 유독 준수율이 낮다면, 그 팀들이 게으른 것이 아니라 그 규칙을 지키기 어렵게 만든 우리 잘못 일 가능성이 큽니다. 기본값으로 넣어 주거나, 스캐폴드에 미리 채워 주거나, 문구를 고쳐야 할 신호입니다.

다만 분모를 조심해야 합니다. 진단 대상 목록이 바뀌면 준수율은 아무도 아무 일을 하지 않아도 움직입니다. 숫자를 볼 때는 분모가 무엇이었는지 함께 기록해야 합니다.

현장에서 만나는 모습

LabHub 의 채점기가 정확히 이 구조로 되어 있습니다. 채점 스크립트는 실패할 때 "확인에 실패했습니다" 라고 쓰지 않고 지금 값이 무엇이고 무엇이어야 하는지 를 함께 말하도록 규칙이 정해져 있습니다. 이유는 같습니다. 무엇이 틀렸는지 모르는 사람에게 남은 선택지는 추측뿐이고, 추측이 두세 번 빗나가면 그 사람은 떠납니다.

반대 방향의 사고도 있었습니다. 이 저장소에는 한때 "어떤 답을 넣어도 통과하는" 채점기가 여러 개 있었습니다. 아무도 신고하지 않았기 때문에 오래 남아 있었습니다. 진단기도 같습니다. 아무것도 잡아내지 못하는 진단기는 없는 것보다 나쁩니다. 준수율이 100% 로 보이는데 실제로는 아무 검사도 하지 않고 있기 때문입니다. 그래서 진단기는 일부러 어긴 표본 으로 반대 방향까지 시험해야 합니다.

다음 실습에서 할 것

골든 패스 규칙 다섯 개를 식별자와 심각도가 붙은 값으로 정의하고, 그 규칙을 실제로 판정하는 진단기를 만듭니다. 준수하는 표본과 특정 규칙만 어긴 표본을 각각 만들어 양쪽으로 시험하고, 결과를 JSON 으로도 내보낸 뒤, 서비스 전체의 준수율을 계산합니다. 마지막으로 커밋 훅에 붙여 block 규칙만 실제로 막히는지 확인합니다.