아키텍처 의사결정을 잊지 마세요: 실행 가능하게 만들자

Source: Dev.to

문제: 사라진 아키텍처 결정

대부분의 소프트웨어 프로젝트가 실패하는 이유는 개발자가 코드를 작성하지 못해서가 아니다. 결정이 사라지기 때문이다.

몇 달 혹은 몇 년이 지나도 코드는 여전히 실행되고, 테스트는 통과하며, 시스템은 건강해 보이지만 핵심 선택의 이유는 사라졌다.

• 왜 이 라이브러리를 선택했는가?
• 왜 이 서비스가 이렇게 동작하는가?
• 성능 최적화였는가, 비즈니스 제약이었는가, 아니면 영구화된 임시 해결책이었는가?

남는 것은 코드의 명료함이 아니라, 처음에 있었던 사람들만 기억하는 쓰여지지 않은 규칙이다. 이것은 조직 기억의 문제다. 의도가 사라지면 모든 변경이 더 위험하고, 느려지며, 비용이 많이 든다.

팀이 아키텍처를 깨는 이유는 부주의 때문이 아니라, 원래 결정을 이해하던 사람이 떠나고, 마감일이 지속적인 압박을 만들며, 문서가 오래돼 버리고, 중요한 결정이 채팅 스레드와 풀 리퀘스트에 파묻혀 공식적으로 기록되지 않기 때문이다.

왜 무언가가 만들어졌는지를 아는 것은 어떻게 동작하는지를 아는 것만큼 중요하다. 그 지식이 없으면 팀은 추측하게 되고, 시스템은 점점 유지보수가 어렵고 위험해진다.

결정이 코드와 멀어지면 결국 잊혀진다. 아키텍처 결정 레코드(ADR)는 개발자의 일상 워크플로에 포함되고, 코드와 가깝게 위치하며, 리뷰 중에 보이고, 규칙이 깨질 위험이 있을 때 드러날 때만 효과가 있다. 그렇지 않으면 역사적 문서가 될 뿐 살아있는 제약이 아니다.

비전: 실행 가능한 아키텍처

프로젝트에 이렇게 물어볼 수 있다고 상상해 보라:

왜 여기서 ORM 사용이 금지되었는가?

그리고 사람 대신 시스템 자체가 명확하고 일관된 답을 제공한다. 이는 반복적인 설명을 줄이고, 온보딩을 원활하게 하며, “아키텍처 전설”을 감소시킨다.

PHPDecide 소개

PHPDecide는 아키텍처 결정을 다음과 같이 다루는 CLI 도구이다:

• 버전 관리된 아티팩트로 저장소에 보관
• 구조화된, 기계가 읽을 수 있는 지식
• 설명 가능한 제약
• 선택적으로 강제할 수 있는 규칙

각 결정은 다음을 포함한다:

왜 결정 파일을 작성해야 할까?

일부 팀에서는 리더나 시니어 개발자가 통제력을 잃는 느낌이라 반대한다. 지식이 그들의 머리 속에만 있다면 그들은 게이트키퍼가 된다. 회의와 기억에만 의존하면 숨겨진 위험이 생긴다:

• 지식 사일로와 단일 실패 지점
• 주니어 개발자가 질문을 주저함
• 결정이 잊혀지거나 의도치 않게 위반됨
• 리뷰가 구현이 아니라 의도에 대한 논쟁이 됨

결정 파일은 권한을 개인에서 팀과 저장소로 이동시킨다: 투명하고, 설명 가능하며, 공유 가능하게 만든다.

시작하기

1. PHPDecide를 사용해 저장소에 3~5개의 고신호 결정을 기록한다.
2. CI에서 lint 단계를 실행해 결정 파일을 검증한다.
3. 한 달 동안 코드 리뷰에서 explain을 사용해 관련 결정을 드러낸다.
4. 영향을 측정한다 – 반복 질문이 줄어들고, 온보딩이 빨라지며, 리뷰가 더 일관되는지 확인한다.

아키텍처 결정을 실행 가능하고 탐색 가능하게 만들면, 팀은 조직 기억을 보존하고 위험을 줄이며 장기적으로 시스템을 건강하게 유지할 수 있다.