경계 형태
개요
하네스는 경계가 보일 때만 설계할 수 있다. 경계가 흐리면 우회도 흐려지고, 우회가 흐려지면 실패도 강제하기 어렵다.
이 문서는 하네스 친화적 아키텍처의 가장 기본 조건인
경계의 형태를 다룬다.
1. 명시적 경계가 있어야 한다
좋은 경계는 문서에만 존재하지 않는다. 폴더, 모듈, 타입, 프로세스, 인터페이스처럼 실제 구조 안에서 드러나야 한다.
좋은 신호:
- 레이어 책임이 파일 구조에서 보인다
- 외부 진입점과 내부 구현이 분리되어 있다
- 어떤 모듈이 무엇을 소유하는지 드러난다
나쁜 신호:
- 어디서나 어디든 접근 가능하다
- 같은 기능이 여러 위치에서 중복 구현된다
- 레이어는 설명으로만 존재한다
경계가 보이지 않으면 rule도 흐려진다.
2. 합법 진입점이 좁고 분명해야 한다
하네스는 정상 경로가 있을 때 강해진다.
정상 경로가 여러 개면 우회와 정상 경로를 구분하기 어렵다.
좋은 구조:
- 파일 시스템 접근은 한 레이어를 통해서만 가능
- 상태 변경은 한 인터페이스를 통해서만 가능
- 렌더링은 한 파이프라인을 통해서만 가능
- 외부 호출은 하나의 facade나 command surface로 수렴된다
나쁜 구조:
- helper, util, shortcut, convenience path가 계속 늘어난다
- 직접 접근도 되고 wrapper도 되고 factory도 된다
- 팀마다 다른 합법 경로를 사용한다
합법 진입점은 적을수록 강하다.
3. 캡슐화는 하네스의 전제조건이다
내부 구현이 넓게 노출되면 우회는 거의 필연적이다. 접근 가능한 것은 결국 사용된다.
필요한 조건:
- 내부 모듈 export 최소화
- 직접 생성 경로 차단
- raw object 대신 command / DTO / interface 사용
- 내부 상태의 직접 mutation 차단
- 구현 세부보다 계약이 먼저 보이게 설계
캡슐화는 미학이 아니라 경계 보호 장치다.
4. 계약이 구조를 대신 설명해야 한다
하네스 친화적 구조는 계약이 먼저 드러난다. 계약이 약하면 사람도 AI도 내부 구현을 직접 만지려 한다.
좋은 계약의 특징:
- 입력과 출력이 명확하다
- 책임이 한정되어 있다
- 예외 경로를 숨기지 않는다
- 호출자가 내부 상태를 만지지 못한다
즉 경계는 import 제한만으로 끝나지 않는다. 계약이 실제로 사용 가능한 형태여야 한다.
5. 경계는 문장보다 구조가 강하다
다음 두 규칙을 비교하면 차이가 분명하다.
- “UI는 backend를 직접 호출하지 않는다”
- “UI는 backend assembly를 참조할 수 없다”
둘 다 같은 의도를 담을 수 있다. 하지만 두 번째는 구조가 직접 개입한다. 하네스는 항상 두 번째 방향을 선호한다.
6. 경계가 너무 많아도 문제다
모든 것을 세세하게 나누는 것이 항상 좋은 것은 아니다. 너무 많은 경계는 다음 문제를 만든다.
- 합법 경로가 지나치게 복잡해진다
- wrapper가 wrapper를 부르는 구조가 생긴다
- 규칙은 늘어나는데 강제력은 약해진다
하네스 친화적 구조는 경계의 수보다
경계의 명확성과 진입점의 단순성을 더 중시한다.
7. 경계가 약한 구조의 전형적인 증상
- 내부 객체를 직접 들고 다닌다
- service locator나 전역 registry가 넓게 퍼져 있다
- 같은 기능의 진입점이 여러 개다
- 테스트가 production과 다른 진입점을 쓴다
- 계약보다 구현 예시가 더 많이 참조된다
이 증상은 곧 하네스를 붙이기 어렵다는 신호다.
실무 판단 기준
아키텍처를 볼 때 다음 질문에 답하면 된다.
- 이 기능의 유일한 진입점은 어디인가
- 내부 구현을 직접 만질 수 있는가
- import나 생성 경로만 봐도 경계 위반을 식별할 수 있는가
- 호출자가 계약을 우회할 짧은 길이 남아 있는가
이 질문에 답하기 어려우면, 먼저 경계 형태를 정리하는 편이 맞다.
요약
하네스 친화적 경계는 다음 조건을 가진다.
- 명시적이다
- 진입점이 좁다
- 캡슐화가 강하다
- 계약이 선명하다
- 설명보다 구조가 먼저 개입한다
즉 좋은 boundary shape는 보기 좋은 분리가 아니라, 우회가 어디서 시작되는지 바로 보이는 구조다.