합법 경로 우선
개요
많은 시스템이 금지 규칙부터 쌓는다. 하지만 합법 경로가 먼저 설계되지 않으면, 금지는 곧 불편한 절차가 되고 사람과 AI는 다시 shortcut을 만든다.
하네스 친화적 API 설계는 금지보다 정상 경로를 먼저 본다.
왜 합법 경로가 먼저인가
우회는 대개 악의가 아니라 마찰에서 나온다.
- 정상 경로가 길고
- 어디로 들어가야 할지 모호하고
- 필요한 정보가 여러 곳에 흩어져 있으면
사람도 AI도 결국 더 짧은 길을 만든다.
그래서 중요한 것은 먼저 무엇을 막을지가 아니라, 무엇을 가장 쉽게 하게 만들 것인가다.
좋은 합법 경로의 조건
발견 가능해야 한다
문서나 코드 구조만 봐도 어디로 들어가야 하는지 알 수 있어야 한다.
짧아야 한다
정상 경로가 wrapper 다섯 개를 거치고, shortcut은 한 줄이면 대부분 shortcut이 이긴다.
충분히 표현력이 있어야 한다
정상 경로로 처리할 수 없는 예외가 많으면, 우회는 다시 생긴다.
실패 조건이 분명해야 한다
정상 경로를 벗어났을 때 조용히 통과되면, 경계는 약해진다.
금지부터 시작할 때 생기는 문제
- 정상 경로가 불명확하다
- 팀은 review마다 같은 설명을 반복한다
- helper나 util이 비공식 entry point가 된다
- 테스트와 production이 다른 길을 학습한다
- AI는 기존 우회 코드를 참조 예시로 복제한다
금지가 먼저고 합법 경로가 나중이면, 규칙은 늘고 구조는 약해진다.
합법 경로를 설계할 때 보는 질문
- 가장 먼저 떠오르는 호출 경로는 하나인가
- 새 팀원이 봐도 entry point가 명확한가
- AI가 주변 코드만 보고도 그 경로를 찾을 가능성이 높은가
- 예외 처리가 필요해도 공식 경로 안에서 해결 가능한가
- 정상 경로가 정말 우회보다 덜 귀찮은가
이 질문에 아니오가 많으면,
문제는 enforcement 이전에 API 설계에 있다.
좋은 구조의 예시 방향
- direct constructor 대신 factory 하나
- 여러 mutation 함수 대신 command entry 하나
- raw query 여러 개 대신 scoped facade 하나
- renderer direct call 대신 pipeline entry 하나
핵심은 API 수를 줄이는 게 아니라, 정상 사용을 하나의 명확한 선택으로 만드는 것이다.
요약
합법 경로 first 원칙은 단순하다.
- 금지보다 합법 경로를 먼저 설계하고
- 그 경로를 가장 짧게 만들고
- 대부분의 작업이 그 경로 안에서 끝나게 만든다
하네스 친화적 API의 시작점은 무엇을 금지할지보다 무엇을 가장 쉽게 하게 만들지에 있다.