이해 가능성은 아키텍처 품질 속성이다
코드 자동화가 빠르게 확산되면서 팀의 코드 생산 속도는 높아지고 있지만, 역설적으로 시스템에 대한 인간의 이해도는 조용히 낮아지고 있다. 기능은 동작하고 테스트도 통과하지만, 왜 그 설계 결정이 내려졌는지, 어떤 트레이드오프가 있었는지를 아는 사람이 점점 줄어드는 상황이다. 이 글은 이런 현상을 "인지 부채(Cognitive Debt)" 로 정의하고, 시스템의 이해 가능성(Comprehension)을 성능·확장성과 동등한 아키텍처 품질 속성으로 다뤄야 한다고 주장한다.
4년차 이상 개발자라면 이미 경험했을 것이다. 새 팀원이 합류해 "이 모듈은 왜 이렇게 설계됐나요?"라고 물었을 때, 아무도 자신 있게 답하지 못하는 순간. 그 침묵이 바로 인지 부채가 표면화되는 지점이다. 시스템이 이해되지 않으면, 변경은 점점 더 조심스럽고 느려지며 결국 안전한 아키텍처 진화 자체가 불가능해진다.
설계 의도(Intent)를 어떻게 보존할 것인가
시스템 이해 가능성이 낮아지는 핵심 원인은 설계 의도가 코드베이스 어디에도 명시적으로 남지 않는다는 점이다. 결정 사항은 슬랙 메시지, 구두 논의, 혹은 작성자의 기억 속에만 존재하다가 사라진다. 이를 해결하기 위한 실천 전략으로 다음을 제안할 수 있다.
- Architecture Decision Records(ADR): 결정 배경, 고려한 대안, 선택 이유를 코드 저장소와 함께 버전 관리
- 설계 체크포인트(Design Checkpoint): PR 리뷰 시 기능 정확성뿐 아니라 "이 변경이 기존 설계 의도와 일치하는가"를 명시적으로 검토
- 의도 주석(Intent Comment): 단순한 동작 설명이 아닌 "왜 이 방식을 선택했는가"를 코드 내에 기록
// [INTENT] 외부 결제 API 타임아웃을 3초로 고정.
// 5초 이상 허용 시 DB 커넥션 풀 고갈 발생 (2024-03 장애 참고)
// 대안(retry 무제한)은 cascade failure 위험으로 제외
int PAYMENT_TIMEOUT_MS = 3_000;
이 수준의 맥락이 코드 옆에 존재하면, 미래의 변경자는 타임아웃 값을 섣불리 올리거나 삭제하지 않는다.
소셜-기술적 지표로 인지 부채를 측정하라
인지 부채는 추상적인 개념처럼 보이지만, 측정 가능한 지표로 구체화할 수 있다. 단순한 코드 메트릭(복잡도, 커버리지)을 넘어 소셜-기술적(socio-technical) 관점의 지표가 필요하다.
- 지식 집중도(Knowledge Concentration): 특정 모듈의 커밋 이력이 1~2명에게 집중되어 있는가 (버스 팩터)
- 온보딩 소요 시간: 신규 팀원이 특정 도메인 영역에서 첫 의미 있는 기여를 하기까지 걸리는 시간
- 변경 실패율(Change Failure Rate): 이해도가 낮은 모듈일수록 수정 후 버그 발생률이 높아지는 경향
- 리뷰 코멘트 패턴: "왜 이렇게 했나요?"류의 질문이 반복되는 모듈은 이해 가능성이 낮다는 신호
// 버스 팩터 낮은 모듈 탐지 예시 (git log 활용)
git log --format="%ae" -- src/payment/core/ | sort | uniq -c | sort -rn
이런 지표들을 정기적으로 모니터링하면, 어느 모듈에 인지 부채가 쌓이고 있는지를 리팩터링 전에 포착할 수 있다.
정리
- 시스템 이해 가능성은 성능·보안과 동등하게 아키텍처 품질 속성으로 명시적으로 관리해야 한다
- ADR, 설계 체크포인트, 의도 주석을 통해 설계 결정의 맥락을 코드베이스와 함께 보존하라
- 버스 팩터, 온보딩 시간, 변경 실패율 같은 소셜-기술적 지표로 인지 부채를 조기에 탐지하고 대응하라