점검표

개요

이 문서는 앞선 architecture 섹션을 실무 점검표로 압축한 것이다. 길게 읽지 않고도 현재 구조가 하네스 친화적인지 빠르게 판단할 수 있게 만든다.

1. 경계 형태 ^boundary

• 경계가 폴더, 모듈, 타입 수준에서 드러나는가
• 외부 진입점이 분명한가
• 어떤 책임이 어디에 있는지 구조만 봐도 읽히는가
• 같은 기능의 진입점이 여러 개로 퍼져 있지 않은가

아니오가 많다면 먼저 경계 형태부터 정리하는 편이 맞다.

2. 합법 경로 ^{legal path}

• 합법 경로가 1~2개 수준으로 좁혀지는가
• direct path보다 합법 경로가 더 찾기 쉬운가
• helper나 util이 사실상 우회 통로가 되지 않는가
• 팀이 공식 진입점 이름을 바로 말할 수 있는가

아니오가 많다면 금지보다 합법 경로 설계가 먼저다.

3. 캡슐화 ^{encapsulation}

• 내부 구현이 쉽게 직접 import되지 않는가
• raw object보다 command / DTO / interface가 먼저 보이는가
• 내부 상태를 직접 mutation할 짧은 경로가 없는가
• 직접 생성 대신 factory나 facade를 통해 수렴하는가

아니오가 많다면 캡슐화 부족이 우회 원인일 가능성이 크다.

4. 우회 원천 ^{shortcut sources}

• fallback이 구조 위반을 덮지 않는가
• singleton이나 global access가 넓게 퍼져 있지 않은가
• 테스트에서만 허용되는 shortcut이 없는가
• debug용 bypass path가 남아 있지 않은가
• convenience API가 경계를 우회하지 않는가

아니오가 많다면 구조보다 우회 원천 정리가 먼저다.

5. 강제 준비도 ^{enforcement readiness}

• 이 규칙을 lint, analyzer, type check 중 하나로 검사할 수 있는가
• 정적으로 못 막으면 runtime guard를 둘 entry point가 있는가
• 위반 시나리오를 테스트로 고정할 수 있는가
• 실패 지점을 로그나 진단으로 식별할 수 있는가
• test/dev/prod가 같은 경계를 따르는가

아니오가 많다면 enforcement 기법보다 강제 준비도가 부족한 상태다.

6. 도입 순서 ^{retrofit priority}

다음 항목 중 무엇이 가장 심각한지 먼저 표시하면 된다.

• 가장 위험한 direct path
• 가장 넓은 fallback
• 가장 자주 쓰이는 global access
• 가장 많이 복제되는 test shortcut
• 가장 먼저 막을 수 있는 정적 규칙

점검표의 목적은 전체 점수를 매기는 것이 아니라, 다음으로 닫아야 할 경로를 고르는 것이다.

요약

하네스 친화적 아키텍처는 다음 질문에 예가 많다.

• 경계가 명시적인가
• 합법 경로가 좁은가
• 캡슐화가 강한가
• shortcut source가 적은가
• enforcement를 붙일 준비가 되어 있는가

반대로 아니오가 많은 항목이 곧 다음 설계 우선순위다.