표준이 없는 React 프로젝트를 인계받았을 때 실제로 느끼는 기분
요약
표준화되지 않은 React 프로젝트를 인계받았을 때 발생하는 인지적 부하와 문제점을 다룹니다. 문서화만으로는 해결할 수 없는 코드 일관성의 중요성을 강조하며, 개발자가 실무에서 어떻게 점진적으로 표준을 적용해 나가는지 설명합니다.
핵심 포인트
- 표준 없는 코드베이스는 높은 인지적 부하를 유발함
- 문서화는 '무엇'을 설명하지만, 표준은 '어떻게'를 결정함
- AI가 생성한 코드는 규칙이 없으면 일관성이 결여됨
- 점진적인 리팩터링을 통해 코드의 예측 가능성을 높일 수 있음
모든 파일이 조금씩 다르게 보였습니다.
정확히 틀린 것은 아니었습니다. 그저 달랐을 뿐입니다. 어떤 컴포넌트는 화살표 함수 (arrow functions)를 사용했습니다. 그다음 컴포넌트는 함수 선언문 (function declarations)을 사용했습니다. 상태 (State)는 어떤 기능에서는 훅 (hooks)에 존재했고, 다른 기능에서는 UI 내부에 인라인 (inline)으로 존재했습니다. 명명 규칙 (Naming conventions)은 폴더마다 바뀌었습니다. 임포트 (Import) 패턴은 마지막으로 파일을 만진 사람이 누구냐에 따라 달라졌습니다.
저는 코드베이스 (codebase)에 대한 소개를 요청했습니다. 돌아온 답변은 이랬습니다: "그냥 어떻게 되어 있는지 보면 알 수 있어요."
어떻게 되어 있는지는 볼 수 있었습니다. 문제는 제가 보는 곳마다 방식이 제각각이었다는 점입니다.
표준이 없는 코드베이스가 실제로 주는 느낌
마치 서로 대화해 본 적 없는 서로 다른 작가들이 각 장을 쓴 책을 읽는 기분입니다.
각 장은 그 자체로는 말이 됩니다. 이야기는 기술적으로 존재합니다. 하지만 목소리가 바뀌고, 스타일이 변하며, 규칙이 초기화됩니다. 내용을 따라갈 수는 있지만, 다음 페이지가 어떻게 생겼을지 알 수 없기 때문에 결코 편안하게 몰입할 수 없습니다.
이것이 표준이 없는 React 프로젝트를 물려받은 개발자가 느끼는 감정입니다. 모든 파일을 능동적으로 읽어야 합니다. 자동화된 것은 아무것도 없습니다. 새로운 것을 만들기 전에 무엇이 존재하는지 이해하는 데 드는 인지적 부하 (mental overhead)가 엄청납니다.
그리고 대부분의 경우 AI가 그 상당 부분을 구축했습니다. 한 번의 세션씩 말이죠. 규칙이 존재하지 않아 매번 조금씩 다른 결정을 내리며 세션이 진행되었습니다.
아무도 말하지 않는 인계 (handover) 문제
React 프로젝트 인계에 관한 대부분의 대화는 문서화 (documentation)에 집중됩니다. 더 나은 주석을 작성하세요. README를 만드세요. 아키텍처 (architecture)를 문서화하세요.
문서화는 도움이 됩니다. 하지만 문서화는 존재하는 것을 설명할 뿐입니다. 존재하는 것들 사이에 일관성 (consistency)을 만들어주지는 않습니다.
좋은 문서화가 되어 있지만 표준이 없는 프로젝트를 맡게 된 개발자는 여전히 모든 파일을 주의 깊게 읽어야 합니다. 여전히 어떤 패턴이 진짜인지 파악해야 합니다. 여전히 일관성 없게 구축된 무언가를 어떻게 확장할지에 대해 판단을 내려야 합니다.
표준이 있는 프로젝트를 인계받는 개발자는 즉시 업무에 착수할 수 있습니다. 패턴이 어디에서나 동일하기 때문입니다. 명명 규칙 (Naming convention)은 하나의 관례를 따릅니다. 구조는 예측 가능합니다. 코드베이스가 어디를 가든 똑같이 생겼기 때문에, 코드베이스가 어떻게 구성되어 있는지 알려주는 문서 (Documentation)가 굳이 필요하지 않습니다.
문서 (Documentation)는 다음 개발자에게 프로젝트가 '무엇을 하는지' 알려줍니다. 표준 (Standards)은 프로젝트가 '어떻게 생각하는지'를 알려줍니다. GitHub Copilot은 표준을 따를 수 있습니다. 하지만 표준이 없는 것을 보완해 줄 문서를 작성할 수는 없습니다.
대신 내가 한 일
나는 나만의 표준을 가져왔습니다.
요란하게 하지 않았습니다. 리팩터링 (Refactor) 제안으로 내밀지도 않았습니다. 그저 내가 손대는 모든 파일에 조용히 적용했을 뿐입니다. 모든 새로운 컴포넌트 (Component)는 동일한 구조를 따랐습니다. 모든 훅 (Hook)은 동일한 패턴을 따랐습니다. 모든 임포트 (Import)는 기능 인덱스 (Feature index)를 거쳤습니다.
내가 작업한 코드베이스의 부분들은 아직 손대지 않은 부분들과 다르게 보이기 시작했습니다. 더 일관적이고, 더 예측 가능하며, 확장하기 더 쉬워졌습니다.
다른 개발자들이 이를 알아차렸습니다. 내가 시스템에 대해 말했기 때문이 아니라, 코드가 스스로를 증명했기 때문입니다.
실제로 적용된 모습은 다음과 같습니다:
첫날부터 적용한 표준:
1. 모든 컴포넌트는 프레젠테이션 (Presentational) 또는 컨테이너 (Container) 중 하나여야 한다. 결코 둘 다여서는 안 된다.
2. 상태 로직 (State logic)은 기능 폴더 (Feature folder) 내의 전용 훅 (Hook)에 위치한다.
...
세 가지 규칙입니다. 일관되게 적용되었습니다. 코드베이스 전체에 표준이 없더라도, 내가 손댄 영역만큼은 표준이 생기기 시작했습니다.
인계 시 표준이 없을 때 발생하는 비용
표준이 없는 프로젝트를 물려받는 개발자는 모든 작업마다 '세금'을 지불합니다.
읽는 시간. 컨텍스트 구축 (Context building). 패턴 인식. 그리고 무언가를 수행하는 세 가지 방식 중 어떤 것이 확장하기에 올바른 방식인지 판단하는 과정 말입니다.
그 세금은 복리로 쌓입니다. 표준 없이 프로젝트가 존재하면 존재할수록, 불일치 (Inconsistency)는 더 많이 축적되고, 그 뒤에 오는 모든 개발자가 지불해야 할 세금은 더 높아집니다.
AI가 이 문제를 만든 것은 아닙니다. 하지만 AI는 이 문제를 가속화했습니다. 규칙이 없는 매 세션마다, 이미 너무 많은 결정이 내려져 있는 코드베이스 (Codebase)에 조금씩 다른 결정이 하나씩 더 추가되었기 때문입니다.
프롬프트 (Prompt)는 중요하지 않습니다. 규칙 (Rules)이 중요합니다.
React 프로젝트 인계가 실패하는 이유는 문서화 (Documentation)가 부족해서가 아닙니다.
다음 개발자가 코드베이스를 열었을 때, 동일한 작업을 수행하는 다섯 가지 서로 다른 방식이 발견되고 그중 어떤 것이 올바른지 알 수 있는 표시가 없을 때 프로젝트는 실패합니다.
표준 (Standards)이 이를 해결합니다. 인계가 끝난 후가 아니라, 첫 세션 전부터 말입니다. 첫 번째 컴포넌트 (Component)를 만들기 전부터, 그리고 AI가 이 프로젝트가 어떻게 작동하는지에 대해 첫 번째 결정을 내리기 전부터 말입니다.
당신의 React 프로젝트에서 인계 시에도 유지될 수 있는 표준이 어디에서 누락되었는지 알고 싶습니까?
저는 바로 그 부분을 정확히 찾아낼 수 있도록 도와주는 24가지 항목의 무료 체크리스트를 만들었습니다. 모든 인계를 불필요하게 어렵게 만드는 구조적 격차 (Structural gaps)를 찾아보세요.
AI 자동 생성 콘텐츠
본 콘텐츠는 Dev.to AI tag의 원문을 AI가 자동으로 요약·번역·분석한 것입니다. 원 저작권은 원저작자에게 있으며, 정확한 내용은 반드시 원문을 확인해 주세요.
원문 바로가기