합법 경로 중심 API 설계

개요

하네스는 금지 규칙만으로 유지되지 않는다. 합법 경로가 우회보다 불편하면, 사람도 AI도 결국 더 짧은 우회를 다시 만든다.

이 섹션은 그 문제를 API 설계 관점에서 다룬다. 핵심 질문은 다음과 같다.

어떻게 API 표면을 설계해야 정상 경로가 가장 짧고 가장 명확한 선택이 되는가

이 섹션의 위치

architecture 섹션이 하네스를 가능하게 하는 구조 조건을 다뤘다면, 이 섹션은 그 구조 위에 어떤 API surface를 얹어야 하는지 다룬다.

즉 여기서 보는 것은 아름다운 API 스타일이 아니라, 우회보다 정상 사용이 더 쉽도록 만드는 API 설계다.

핵심 질문

좋은 하네스 친화적 API를 보려면 다음을 물으면 된다.

• 합법 경로가 정말 가장 짧은가
• entry point 수가 불필요하게 많지 않은가
• 호출자가 내부 구현 세부를 알지 않아도 되는가
• convenience가 경계를 우회하지 않는가
• 잘못된 사용이 조용히 통과되지 않는가

이 질문들은 ergonomics를 보는 동시에 control strength를 본다.

이 섹션의 구성

legal-path-first ^{합법 경로 우선}

왜 정상 경로를 먼저 설계해야 하는지 본다.

narrow-surface ^{표면 축소}

entry point를 좁히고 surface를 단순하게 유지하는 이유를 본다.

contract-shape ^{계약 형태}

command, DTO, facade, result shape를 어떻게 잡아야 우회가 줄어드는지 본다.

convenience-without-bypass ^{우회 없는 편의}

편의 API를 제공하되 경계를 우회하지 않게 만드는 방법을 본다.

checklist ^점검표

실제 API surface를 빠르게 점검하기 위한 체크리스트다.

읽는 순서

1. legal-path-first
2. narrow-surface
3. contract-shape
4. convenience-without-bypass
5. checklist

이 순서는 정상 경로를 먼저 만들고, 그 경로를 단순화하고, 계약을 정교화하고, 편의를 붙인 뒤, 마지막에 점검하는 흐름이다.

요약

좋은 하네스 친화적 API는 다음 조건을 가진다.

• 정상 경로가 가장 먼저 보인다
• surface가 좁고 단순하다
• 계약이 내부 구현을 숨긴다
• convenience가 우회가 되지 않는다
• 잘못된 사용은 조용히 통과되지 않는다

즉 이 섹션이 다루는 것은 API 미학이 아니라, 우회보다 정상 경로가 더 짧게 느껴지도록 만드는 설계다.