온보딩 문서를 준비하며 다시 본 내부 플랫폼의 복잡성

처음에는 단순히 신규 엔지니어를 위한 온보딩 문서를 정리하려고 했다. 필요한 도구를 적고, 어떤 권한이 필요하고, 개발 환경은 어떻게 맞추는지 순서대로 정리하면 된다고 생각했다.

그런데 막상 문서를 쓰기 시작하니, 문제는 문서의 빈칸이 아니었다. 문서가 어려운 이유는 그 문서가 설명해야 하는 시스템 자체가 이미 꽤 복잡했기 때문이다.

내부 플랫폼이 많고, 권한이 세분화되어 있고, 팀마다 의존하는 도구와 절차가 다른 조직에서는 온보딩이 원래 어렵다. 새 엔지니어가 배우는 것은 단순한 개발 환경이 아니라, 그 조직이 어떻게 기술과 권한과 책임을 나눠 운영하는지에 가깝다.

그래서 이 글은 “좋은 온보딩 문서는 어떻게 쓰는가”를 설명하기보다, 온보딩 문서를 준비하면서 다시 보게 된 내부 플랫폼의 복잡성을 회고하는 글에 가깝다.

온보딩이 어려운 이유는 세팅 문서가 부족해서만이 아니었다

새 엔지니어가 처음 마주하는 어려움은 흔히 코드베이스라고 생각하기 쉽다. 하지만 실제로는 코드보다 먼저 배워야 할 것이 훨씬 많다.

• 어디에서 권한을 신청해야 하는가
• 어떤 내부 시스템이 무엇을 담당하는가
• 배포는 어디서 되고, 로그는 어디서 보고, 시크릿은 어디서 관리되는가
• 내가 지금 막힌 이유가 코드 문제인지 권한 문제인지 플랫폼 문제인지

이 질문에 답할 수 없으면, 코드를 읽을 수 있어도 실제로는 일을 시작하기 어렵다.

그래서 온보딩에서 가장 중요한 것은 “설치 명령어 모음”이 아니라, 새로운 사람이 내부 플랫폼의 구조를 얼마나 빨리 이해할 수 있게 도와주느냐였다.

내부 플랫폼이 많을수록 먼저 배워야 할 것이 늘어난다

플랫폼이 잘 갖춰진 조직은 분명 강점이 있다. 공통 인증, 배포, 모니터링, 보안 점검, 권한 관리, 시크릿 관리가 어느 정도 일관된 방식으로 굴러간다. 문제는 그 일관성이 신규 입장에서는 곧 학습 비용이 된다는 점이다.

새 엔지니어는 애플리케이션 하나를 실행하기 전부터 이미 여러 층의 내부 시스템을 이해해야 한다.

즉 도구가 많다는 것은 단순히 화면이 많다는 뜻이 아니다. 하나의 작업을 시작하기 위해 선행되어야 하는 이해의 층이 많다는 뜻이다.

예를 들어 신규 엔지니어가 마주하는 시스템을 대표적인 것만 나열해도 이 정도가 된다.

• 소스 코드 관리 시스템
• 권한 신청 시스템
• 시크릿 관리 시스템
• 내부 인증서 체계
• 클라우드 계정 접근 도구
• CI/CD 플랫폼
• 작업 관리 시스템
• 보안 검사 도구
• 코드 품질 검사 도구
• 로그 플랫폼
• 메트릭 대시보드
• 내부 문서 시스템

이 각각은 개별적으로 보면 합리적인 분리다. 문제는 신규 입장에서는 이 분리가 한 번에 닥친다는 점이다. 저장소 접근이 열려도 시크릿 권한이 없으면 실행이 안 되고, 실행이 되어도 로그 접근이 없으면 문제를 볼 수 없고, 배포 권한이 없으면 실제 운영 흐름을 따라가기 어렵다.

게다가 복잡성은 여기서 끝나지 않았다. 도구 수가 많은 것만이 아니라, 각 도구 안에서도 권한이 다시 잘게 나뉘어 있었다. 어떤 시스템은 팀 단위로 접근이 갈렸고, 어떤 시스템은 환경별로 권한이 나뉘었고, 로그 플랫폼은 인덱스별로 조회 권한이 따로 열리는 식이었다. 그래서 “이 도구에 접근할 수 있다”와 “내가 지금 필요한 데이터까지 볼 수 있다”는 전혀 다른 문제였다.

결국 새 엔지니어가 처음 마주하는 것은 하나의 애플리케이션이 아니라, 그 애플리케이션을 둘러싼 여러 내부 시스템과 권한의 조합이었다.

권한이 세분화된 조직에서는 온보딩이 더 느려진다

권한이 촘촘하게 나뉜 조직은 대체로 보안과 감사 측면에서는 강하다. 하지만 그 구조는 신규 엔지니어에게는 또 다른 진입 장벽이 된다.

특히 이런 상황이 자주 생긴다.

• 저장소 접근 권한은 있는데 배포 시스템 권한은 아직 없음
• 로그 조회 권한은 있는데 시크릿 접근 권한은 아직 없음
• 기본 개발 도구는 쓸 수 있는데, 실제 운영과 비슷한 환경에는 붙을 수 없음

이런 상태에서는 문서대로 따라 해도 중간중간 멈춘다. 그리고 그 멈춤은 보통 “문서를 안 읽어서”가 아니라, 권한 체계가 단계적으로 열리기 때문에 생긴다.

그래서 권한이 세분화된 조직에서 온보딩 문서는 단순 절차 안내문으로는 부족하다. 무엇을 언제 요청해야 하고, 왜 이 권한이 필요한지, 어디서 막히기 쉬운지까지 함께 설명해야 실제로 도움이 된다.

결국 내가 만들고 싶었던 것도 그런 문서였다. 어떤 일을 하려면 어떤 도구들이 연결되는지, 개발 라이프사이클이 실제로 어떤 시스템들을 거쳐 굴러가는지, 그래서 지금 내가 막힌 지점이 전체 흐름 안에서는 어디쯤인지 인식할 수 있게 만드는 문서 말이다.

문서를 쓰면서 보게 된 것은 도구 목록이 아니라 조직 구조였다

온보딩 문서를 정리하면서 가장 크게 느낀 점은, 좋은 온보딩 문서는 도구 설명서가 아니라 조직의 기술 구조를 압축한 지도에 가깝다는 것이었다.

문서를 쓰다 보면 자연스럽게 이런 질문을 하게 된다.

• 이 도구는 왜 필요한가
• 이 권한은 왜 이렇게 분리되어 있는가
• 새 엔지니어가 처음부터 이것까지 알아야 하는 이유는 무엇인가
• 이 과정은 정말 필요한 복잡성인가, 아니면 축적된 관성인가

즉 온보딩 문서를 준비하는 일은 단순히 신규 입사자를 돕는 작업이 아니었다. 오히려 평소 당연하게 쓰던 내부 시스템을 다시 낯설게 바라보게 만드는 작업에 가까웠다.

좋은 온보딩 문서는 설치 가이드보다 내부 플랫폼의 구조 설명에 가까워야 한다

돌아보면 신규 엔지니어에게 제일 먼저 필요한 것은 “이 명령을 실행하세요”보다 “이 조직은 이런 식으로 굴러간다”는 감각이었다.

그래서 온보딩 문서도 이런 순서가 더 좋다고 느꼈다.

이 순서를 뒤집으면 문서는 길어지는데 이해는 잘 안 된다. 반대로 내부 플랫폼의 구조가 먼저 보이면, 세부 절차는 조금 헷갈려도 어디를 다시 봐야 할지 감이 잡힌다.

내부 플랫폼은 조직의 성숙함이면서 동시에 온보딩 비용이기도 하다

내부 플랫폼이 많다는 것은 한편으로는 조직이 이미 많은 문제를 체계화했다는 뜻이다. 공통 도구가 있고, 표준이 있고, 보안과 운영 방식이 정리되어 있다는 뜻이기도 하다.

하지만 그 성숙함은 신규 엔지니어에게는 곧 복잡성으로 들어온다. 기존 구성원에게는 당연한 시스템이, 처음 들어온 사람에게는 이름도 역할도 모르는 추상적인 벽처럼 느껴진다.

그래서 온보딩이 어렵다는 말은 단순히 문서가 부족하다는 뜻이 아닐 수 있다. 오히려 그 조직이 이미 복잡한 운영 체계를 갖고 있다는 신호일 수도 있다.

중요한 것은 그 복잡성을 없애는 것이 아니라, 새로운 사람이 그 복잡성을 이해할 수 있는 순서로 보여주는 것이다.

결론

온보딩 문서를 준비하면서 다시 느낀 것은, 신규 엔지니어 온보딩은 결국 개발환경 세팅의 문제가 아니라 시스템과 조직을 이해하는 문제라는 점이었다.

내부 플랫폼이 많고 권한이 세분화된 조직에서 온보딩이 어려운 것은 자연스러운 일이다. 문제는 그 복잡성이 존재한다는 사실보다, 그것이 새 사람에게 어떤 순서로 전달되는가에 있다.

좋은 온보딩 문서는 복잡성을 없애지 못하더라도, 적어도 그 복잡성을 길 잃지 않고 통과할 수 있는 지도는 되어야 한다. 그리고 온보딩 문서를 쓰는 과정은, 그 지도를 처음부터 다시 그려 보는 일이기도 했다.