주니어 개발자로 시작할 때는 소프트웨어 엔지니어링이 코드를 작성하는 것이라고 생각합니다. 몇 년이 지나면 적절한 아키텍처 (Architecture)와 프레임워크 (Frameworks)를 선택하는 것이라고 생각하게 되죠.

기능을 출시하고, 온콜 (On-call) 재난 상황에서 살아남으며, "완벽한" 코드베이스가 유지보수 불가능한 괴물로 변하는 것을 지켜본 10년 이상의 실전 경험 끝에, 당신은 진실을 깨닫게 됩니다. 소프트웨어 엔지니어링은 대부분 복잡성 관리, 인간 간의 의사소통, 그리고 트레이드오프 (Trade-offs)에 관한 것입니다.

다음은 지난 10년 동안 제가 직접 저질렀거나, 목격했거나, 혹은 수습해야 했던 25가지 실수입니다. 이 글을 읽는 것이 여러분의 고통스러운 시행착오 시간을 몇 년은 줄여줄 수 있기를 바랍니다.

1. 코드 및 아키텍처 (Code & Architecture)

1. 너무 이른 추상화 (Abstracting Too Early)

DRY (Don't Repeat Yourself) 원칙은 초보자들에게 매우 강조되지만, 성급한 추상화 (Premature abstraction)는 중복 코드보다 훨씬 더 나쁩니다. 3~4개의 구체적인 유스케이스 (Use cases)가 확보되기 전에 추상화하는 것은 변경하기 매우 까다로운, 경직되고 과도하게 설계된 (Over-engineered) 추상화로 이어집니다. 중복은 잘못된 추상화보다 훨씬 비용이 저렴합니다.

2. "영리한" 코드와 사랑에 빠지는 것

단 한 줄을 해석하기 위해 3분 동안 혼잣말을 하거나 복잡한 다이어그램 (Diagram)이 필요하다면, 그 코드는 똑똑한 것이 아니라 부채 (Liability)입니다. 명확하고, 깨끗하며, 지루한 코드를 작성하세요. 새벽 2시 장애 대응 (Incident response) 전화를 받고 있는 미래의 당신이 당신에게 고마워할 것입니다.

3. 의존성 (Dependencies) 비용에 대한 오해

작은 문제를 해결하기 위해 서드파티 라이브러리 (Third-party library)를 추가하는 것은 빠른 승리처럼 느껴집니다. 하지만 실제로 모든 의존성은 외부 팀과 체결하는 계약과 같습니다. 당신은 그들의 버그, 보안 취약점, 중단적 업데이트 (Breaking updates), 그리고 유지보수 주기를 물려받게 됩니다. 스스로에게 물어보세요:

우리가 실제로 필요한 이 라이브러리의 5% 기능을 20줄의 코드로 직접 만들 수 있는가?

4. 존재하지 않는 규모를 위한 과도한 아키텍처 설계 (Over-Architecting for Scale You Don't Have)

현재 사용자가 500명인데 일일 활성 사용자(DAU) 1,000만 명을 목표로 시스템을 설계하는 것은 전형적인 함정입니다. 결국 분산 마이크로서비스 (Distributed Microservices), 메시지 큐 (Message Queues), 그리고 복잡한 캐싱 전략 (Caching Strategies)을 도입하게 되어 개발 속도를 10배나 늦추게 됩니다. 오늘의 규모에 맞춰 구축하되, 내일 리팩터링 (Refactor)할 수 있을 만큼 경계(Boundary)를 깔끔하게 유지하세요.

5. 장애 모드(Failure Modes) 및 예외 케이스(Edge Cases) 무시

해피 패스 (Happy-path) 엔지니어링은 주니어의 특징입니다.

시니어 엔지니어는 정신적 대역폭의 80%를 다음과 같은 질문을 던지는 데 사용합니다:

• 데이터베이스 타임아웃 (Database Timeout)이 발생하면 어떻게 되는가?
• 이 서드파티 API (Third-party API)가 null을 반환하면 어떻게 되는가?
• 트랜잭션 (Transaction) 도중에 네트워크 연결이 끊어지면 어떻게 되는가?

2. 테스트 및 리팩터링 (Testing & Refactoring)

6. 동작(Behavior) 대신 구현 세부 사항(Implementation Details)을 테스트하기

최종 사용자의 동작은 변하지 않았음에도 내부 클래스를 리팩터링했을 때 30개의 유닛 테스트 (Unit Tests)가 깨진다면, 당신의 테스트는 구현에 너무 밀접하게 결합(Tightly Coupled)되어 있는 것입니다. 단계별 내부 상태가 아니라 입력(Input)과 출력(Output)을 테스트하세요.

7. 테스트 없는 리팩터링

통합 테스트 (Integration Tests)나 회귀 테스트 (Regression Tests)라는 견고한 안전망 없이 대규모 리팩터링을 시도하는 것은 용기가 아니라 무모함입니다. 리팩터링이 기존 동작을 유지했는지 몇 초 내에 검증할 수 없다면, 테스트를 먼저 작성하세요.

8. 100% 테스트 커버리지(Test Coverage) 목표하기

100% 코드 커버리지는 허영 지표 (Vanity Metric)입니다. 이는 종종 게터 (Getters), 세터 (Setters), 그리고 자동 생성된 보일러플레이트 (Boilerplate)를 위한 가치 낮은 테스트를 작성하게 만드는 반면, 중요한 예외 케이스 (Edge Cases)와 비즈니스 워크플로우 (Business Workflows)는 테스트되지 않은 채로 남겨둡니다. 높은 퍼센트가 아니라 높은 신뢰도를 목표로 하세요.

9.

혼자서 문제를 해결하려고 사흘 동안 방에 틀어박혀 있는 것은 거의 효과가 없습니다. 몇 시간 이상 막혀 있다면, 이를 겉으로 드러내세요. 진정한 엔지니어링 성숙도란 언제 도움을 요청해야 하는지 알고, 팀에 조기에 상황을 공유하는 것입니다.

11. 코드 리뷰를 자존심 싸움으로 취급하는 것

코드 리뷰 (Code reviews)는 코드베이스를 보호하고 지식을 공유하기 위한 것이지, 방 안에서 누가 가장 똑똑한지 증명하기 위한 것이 아닙니다. (어차피 자동화되어야 할) 코드 포맷팅을 트집 잡거나 수동적-공격적인 (passive-aggressive) 댓글을 남기는 것은 신뢰를 빠르게 무너뜨립니다.

12. 제품(Product) 및 디자인 팀을 조기에 참여시키지 않는 것

기능이 왜 존재하는지 이해하지 못한 채 모호한 Jira 티켓에만 의존하여 코드를 작성하는 것은 필연적인 재작업 (rework)으로 이어집니다. 가설에 의문을 제기하고, 비즈니스 맥락을 명확히 하며, 노력의 10%만으로 가치의 90%를 전달할 수 있는 더 단순한 기술적 대안을 제시하세요.

13. 기술 전문 용어로 과도하게 소통하는 것

기술적 이해관계가 없는 이해관계자(non-technical stakeholders)에게 데이터베이스 잠금 전략 (database lock strategies)이나 가비지 컬렉션 스파이크 (garbage collection spikes)를 사용하여 기술적 장애물을 설명하는 것은 마찰을 일으킵니다. 엔지니어링 제약 사항을 리스크, 지연, 신뢰성, 비용과 같은 비즈니스 지표 (business metrics)로 번역하는 법을 배우세요.

4. 디버깅 및 운영 (Debugging & Operations)

14. 추측에 의존한 디버깅

운영 환경 (production)에서 오류가 발생했을 때, 해결책을 추측하고 맹목적으로 커밋을 푸시하는 것은 어둠 속에서 다트를 던지는 것과 같습니다. 단 한 줄의 코드를 작성하기 전에 가설을 세우고, 로그 (logs)를 확인하며, 메트릭 (metrics)을 체크하고, 체계적으로 재현하여 근본 원인 (root cause)을 확인하세요.

15. 로그를 사후 고려 사항으로 취급하는 것

로그 (Logs)는 단순히 오류만을 위한 것이 아닙니다. 로그는 애플리케이션 실행의 과정을 이야기해 줍니다. 불충분한 구조화된 로깅 (structured logging), 서비스 경계를 넘나드는 트레이스 ID (trace IDs)의 누락, 그리고 정보가 없는 오류 메시지 (Error: something went wrong)는 운영 환경의 장애 (production incidents) 디버깅을 10배 더 어렵게 만듭니다.

16. 로컬 환경이 운영 환경과 같다고 가정하는 것

"내 컴퓨터에서는 잘 돌아가요"라는 말은 수년 전에 그 유효성을 상실했습니다. 네트워크 지연 (Network latency), 메모리 제한 (memory limits), 동시 부하 (concurrent load), 오염된 데이터 (dirty data), 그리고 운영 환경 (production)에서의 권한 (permissions) 문제는 로컬에서는 절대 재현할 수 없는 버그들을 드러낼 것입니다. 실제 환경을 고려하여 설계하세요.

17. 시스템을 침몰시키기 전까지 데이터베이스 성능을 무시하는 것

50개의 더미 데이터가 있는 스테이징 (staging) 환경에서는 N+1 쿼리 문제 (N+1 query problem)나 데이터베이스 인덱스 (database index) 누락이 앱을 망가뜨리지 않을 것입니다. 하지만 운영 환경 (production)에서는 부하가 걸릴 때 시스템을 완전히 멈추게 만들 것입니다. 사용 중인 ORM이 생성하는 쿼리를 이해하고, 실행 계획 (execution plans)을 조기에 점검하세요.

5. 마인드셋 및 커리어 성장 (Mindset & Career Growth)

18. 유행에 기반하여 도구를 선택하는 것

단순히 소셜 미디어에서 유행한다는 이유만으로 완전히 새로운 프레임워크 (framework), 데이터베이스 (database), 또는 상태 관리 라이브러리 (state management library)를 채택하는 것은 실수입니다. 핵심 비즈니스 로직에는 지루하지만 검증된 기술을 선택하고, 실험적인 기술은 리스크가 낮은 사이드 프로젝트나 격리된 마이크로 실험 (micro-experiments)을 위해 남겨두세요.

19. 코드에 대한 매몰 비용 오류 (Sunk Cost Fallacy)

단순히 코드를 작성하는 데 3일을 썼다는 이유만으로 복잡한 솔루션을 고수하는 것은 위험합니다. 더 간단한 접근 방식이 나타나거나 요구 사항이 변경된다면, 후회 없이 코드를 삭제할 수 있어야 합니다. 코드는 자산 (asset)이 아니라 부채 (liability)입니다.

20. 문서를 귀찮은 일로 취급하는 것

좋은 문서화 (documentation)는 아무도 읽지 않는 장황한 매뉴얼이 아닙니다. 그것은 간결한 아키텍처 결정 기록 (ADRs, architecture decision records), 명확한 온보딩 가이드 (onboarding guides), 그리고 자기 문서화 (self-documenting)되는 API입니다. 당신이 프로젝트를 떠날 때, 당신의 문서는 당신의 유산 (legacy)이 됩니다.

21. 비즈니스 도메인을 이해하지 못하는 것

당신이 만드는 제품의 핵심 지표 (core metrics), 비즈니스 목표 (business goals), 그리고 고객의 페인 포인트 (customer pain points)를 이해하지 못한다면, 당신은 언제나 그저 티켓 실행자 (ticket executor)에 머물 것입니다. 영향력이 큰 소프트웨어 엔지니어는 깊은 도메인 지식 (domain knowledge)을 쌓습니다. 이는 당신이 내리는 모든 아키텍처 선택의 근거가 됩니다.

22. 단기적인 최적화에만 집중하는 것

마감 기한을 맞추기 위해 편법을 쓰는 것이 때로는 필요할 수도 있지만, 기술 부채 (technical debt)를 추적하지 않는 것은 개발 속도 (velocity)의 서서히 진행되는 죽음을 보장합니다. 만약 기술적 대출을 받았다면, 즉시 상환 계획을 세우세요.

23. 단순한 CRUD 앱을 과하게 설계하는 것 (Over-Engineering)

모든 애플리케이션에 이벤트 소싱 (Event Sourcing), 마이크로 프론트엔드 (Micro-frontends), 또는 커스텀 상태 머신 엔진 (Custom state-machine engines)이 필요한 것은 아닙니다. 때로는 표준 REST 또는 GraphQL 엔드포인트를 갖춘 깔끔하고 단순한 모놀리스 (Monolith) 구조만으로도 충분합니다. 솔루션의 복잡도를 문제 자체의 내재된 복잡도에 맞추세요.

24. 소프트웨어가 인간을 위해 만들어졌다는 사실을 잊는 것

스택 트레이스 (Stack traces), 컴파일러 (Compilers), 클라우드 파이프라인 (Cloud pipelines)의 끝에는 특정 과업을 완수하려는 인간 사용자가 있으며, 그리고 6개월 뒤에 당신의 코드를 읽게 될 팀원이 있습니다. 이 두 대상 모두에 대한 공감 능력은 엔지니어링에서 가장 과소평가된 단 하나의 기술입니다.

25. 학습이 끝났다고 믿는 것

소프트웨어 엔지니어링을 마스터했다고 생각하는 순간이 바로 당신이 도태되기 시작하는 순간입니다. 기술 환경은 끊임없이 진화하지만, 더 중요한 것은 당신이 프로젝트를 구축하고 무너뜨릴 때마다 문제를 해결하는 방식에 대한 당신의 관점 또한 진화해야 한다는 점입니다.

마무리

만약 이 실수들 중에서 자신의 모습이 보인다면 걱정하지 마세요. 당신이 존경하는 모든 시니어 엔지니어들도 이 25가지 실수를 모두 저질렀으며 (아마도 수십 가지를 더 저질렀을 것입니다).

목표는 실수를 전혀 하지 않는 것이 아닙니다. 실수로부터 배우고, 그 교훈을 팀과 공유하며, 오늘보다 더 나은 소프트웨어를 내일 만들기 위해 충분히 빠른 피드백 루프 (Feedback loops)를 구축하는 것입니다.

커리어 초기에 했던 실수 중 당신의 코딩 방식을 바꿔놓은 엔지니어링 실수는 무엇인가요?

아래 댓글로 알려주세요!