피드로 돌아가기
Dev.toBackend
원문 읽기
Tests로 잡지 못한 API 설계 결함을 Consumer와 Docs Review로 해결
Two majors, one README, one demo: two cheap design reviews
AI 요약
Context
내부 엔진의 상태 전이와 Lifecycle Hook 설계 시 테스트 통과만으로는 발견할 수 없는 API Shape의 불일치 발생. 특히 v4에서 v6로 진화하며 Hook의 명명 규칙, Halt 상태의 세밀한 제어, Dispatch 순서의 복잡성으로 인한 인지 부하가 병목 지점으로 작용함.
Technical Solution
- Consumer-Driven Validation: 단순 Test Fixture가 아닌 실제 제품(machines-demo)을 구축하여 API 사용자의 Mental Model과 실제 구현 간의 괴리 식별
- API Semantics 정교화: 'onDebugBreak'를 'pause' 기반의 명칭으로 변경하여 사용자의 의도와 인터페이스의 일치성 확보
- State Transition 제약 강화: haltState.debug.after 할당 시 Exception을 발생시켜 논리적으로 불가능한 상태 전이를 API 수준에서 차단
- Dispatch Lifecycle 단순화: 'K+1차 yield 시 K차 스냅샷 대체'라는 복잡한 스케줄링을 제거하고 'before(K) → step(K) → after(K)'의 단일 yield 내 순차 실행 구조로 재설계
- Prose-Pressure Analysis: README 기술 시 설명이 복잡해지는 지점을 설계 결함의 신호로 간주하여 아키텍처를 단순화하는 역방향 검증 수행
실천 포인트
- Major 버전 릴리스 전, 테스트 코드가 아닌 실제 사용 시나리오를 반영한 First Consumer를 반드시 구축할 것 - Dispatch Order나 Lifecycle 설계 시, 이를 한 문장으로 명확히 설명할 수 있는지 검토할 것 - 문서 작성 중 특정 로직을 설명하기 위해 '사과하는 듯한' 긴 부연 설명이 필요하다면, 이를 설계 결함의 신호로 인식하고 리팩토링할 것