입사 10일, AI로 인프라팀 온보딩을 다시 설계한 이야기

date

slug

author

status

tags(최대 3개)

summary

type

thumbnail

들어가며

입사 첫날부터 할 일이 많았습니다. 여러 팀·스쿼드 OJT와 인프라팀 OJT에 더해 개인 환경 설정도 병행해야 했죠. AWS SSO 프로필 설정, EKS kubeconfig 등록, 서비스 레포 클론, 정책 파일 설정까지. 기존에는 Notion 문서를 보며 혼자 따라가는 방식이었는데, 막상 해보면 aws configure sso 프롬프트에 뭘 입력해야 하는지, 에러가 났을 때 어디서부터 다시 해야 하는지 같은 순간마다 멈추게 됐습니다.

다행히 아임웹 인프라팀은 이미 Claude Code를 실무에 적극 활용하고 있었습니다. 특히 AI Guardrails Platform이라는 레포에 팀·스쿼드별 정책과 규칙이 구조화돼 있었고, Claude Code가 이 정책을 읽고 따르며 작업하는 방식이었습니다.

이 고도화된 팀의 AI 활용 수준을 빨리 따라잡고 싶었고, 마침 온보딩을 직접 겪던 터라 막히는 지점부터 하나씩 개선하기 시작했습니다.

이제 아임웹 인프라팀에 입사하면, 터미널에서 Claude를 실행하고 인프라 온보딩을 해달라고 입력하기만 하면 됩니다.

이번 글에서는 입사 후 10일간 AI로 온보딩을 어떻게 다시 설계했는지 그 과정을 공유합니다.

기존 온보딩의 문제점

첫날 온보딩을 진행하며 몇 가지 문제를 직접 겪었습니다.

Notion 가이드가 AI 도구 초기 셋업에 집중돼 있어, AWS SSO나 EKS kubeconfig처럼 실제로 막히는 지점이 빠져 있었습니다.

절차서를 읽다 막히면 팀원에게 직접 물어봐야 했습니다.

어디까지 완료했는지 추적이 안 돼, 중간에 다른 일을 하고 돌아오면 처음부터 다시 확인해야 했습니다.

팀원마다 레포 클론 경로가 달라, 문서에 적힌 경로가 맞지 않는 경우도 있었습니다.

이걸 겪고 나니 다음 사람도 똑같이 막히겠구나 싶었고, 직접 개선하기로 했습니다.

해결 접근: 3계층 구조

온보딩 프로세스를 문서, 자동 검증, AI 대화라는 세 레이어로 나눠 설계했습니다.

1계층 — 사람이 따라가는 절차서

사전 준비부터 첫 주 권장 액션까지, 각 단계마다 목표 / 사전 조건 / 실행 명령 / 검증 / 트러블슈팅을 구조화한 절차서를 작성했습니다.

핵심은 신규 입사자가 이거 뭐 입력하지 하는 순간마다 답을 바로 찾게 하는 것이었습니다. 그래서 SSO 프로필별 프롬프트 입력값, 클러스터 정보, 레포별 핵심 진입점 등을 표로 정리했습니다. 단순히 레포를 클론하는 데서 끝내지 않고 이 레포가 왜 필요한지까지 이해할 수 있도록, 배포 파이프라인 전체 흐름도 함께 담았습니다.

2계층 — read-only 환경 검증 스크립트

셋업 스크립트를 실행하면 내부적으로 환경 검증을 수행합니다. CLI 도구 설치 여부, SSO 인증 유효성, 정적 IAM 키 잔존 여부, kubeconfig 등록 상태, 레포 클론 여부 등 22개 항목을 자동 점검합니다.

이때 스크립트는 환경을 바꾸지 않고 검증만 합니다. 실패한 항목에는 해결 명령어를 함께 안내하고, 레포 경로도 하드코딩 대신 대화형으로 입력받아 각 팀원의 환경 차이를 인식해 적절한 방안을 알려줍니다.

3계층 — AI의 대화형 온보딩 세션

핵심은 이 레이어입니다. 신규 입사자가 인프라 온보딩을 해달라고 입력하면, Claude가 페어 프로그래밍하듯 온보딩을 진행합니다. 여기에 몇 가지 설계 원칙을 적용했습니다.

한 호흡에 완료: 사용자가 중간에 돌아오지 않고 끝까지 완수할 수 있는 단위로 구성합니다.

명령어 추측 금지: AI가 응답하는 모든 값은 절차서에서 실시간으로 읽어옵니다. AI의 기억에 의존하면 이미 수정·갱신된 값이 잘못 전달될 수 있기 때문입니다.

AI가 할 수 있는 건 AI가 실행: read-only 진단이나 검증 명령은 사용자에게 떠넘기지 않고 AI가 직접 실행합니다.

Phase 경계에서 검증 강제: 다음 단계로 넘어가기 전 반드시 이전 단계의 검증 명령을 실행하고 결과를 확인합니다.

각 단계가 끝나면 이해도 퀴즈를 자동 출제해, 단순히 따라 하기에 그치지 않고 실제로 이해했는지 점검하게 했습니다.

직접 온보딩을 만들어 보니 보이는 것들

글로벌 정책 적용 문제

온보딩 프로세스를 구축했어도 과제가 남았습니다. DevOps로서 서비스 애플리케이션 레포에서도 Claude Code를 켜서 작업할 때가 있는데, 여러 레포에서 실행해도 동일한 인프라팀 정책이 적용돼야 한다는 점이었습니다.

처음엔 홈 디렉토리 설정 파일에서 상대 경로로 정책을 import했는데, 이 경로가 프로젝트 루트 기준으로 인식돼 정책 파일을 찾지 못하는 문제가 있었습니다. 절대 경로로 바꿔 해결했고, 여러 레포에서 같은 질문으로 테스트해 정상 동작을 확인했습니다.

Phase 자동 전환 버그

온보딩 guided session에서 Phase 1이 통과되면 Phase 2로 자동 전환돼야 하는데, 분기 로직 버그로 수동으로 넘겨야 하는 상황이 있었습니다. 같은 날 입사한 팀원이 제가 만든 온보딩을 직접 돌려보다 발견한 문제라, 바로 고칠 수 있었습니다.

Multi-Agent 온보딩 실습 설계

아임웹 인프라팀은 Claude를 중심으로 Gemini, Codex를 보조 AI로 병렬 활용하는 Multi-Agent 체제를 실무에 쓰고 있었습니다. (관련 내용은 인프라팀 리드 용현 님이 쓴 블로그를 참고해 주세요.)

Multi-Agent가 잘 구성돼 실무에 쓰이고 있었지만, 신규 입사자가 이 workflow를 빠르게 익힐 방법은 따로 없었습니다. 그래서 이것도 온보딩 시스템에 실습으로 녹였습니다.

사전 조건부터 설계

실습 콘텐츠를 만들기 전에 사전 조건을 네 단계로 설계했습니다.

CLI 도구 설치

각 AI 서비스 브라우저 OAuth 로그인

로그인 상태 파일 존재 확인

실제 모델 응답 검증

설치했는데 안 된다는 상황을 미리 막기 위해, 로그인 여부만 확인하는 게 아니라 실제로 모델이 응답하는지까지 검증하는 단계를 넣었습니다.

6 Step 실습

실습은 단순 → 복합 순서로 6단계를 진행합니다. 공통 과제는 긴급장애 채널의 최근 에러 메시지 분석입니다.

Step 1 — 위임 스크립트 구조 파악: 모드별 역할, 자동 승인 방식, 임시 파일 흐름

Step 2 — 단일 AI 위임: Gemini에게 클러스터 네임스페이스별 Pod 현황 요약 요청

Step 3 — 정밀 분석 위임: Codex에게 보안 스캔 스크립트 OWASP 분석 요청

Step 4 — 병렬 실행: 두 AI가 동시에 비정상 앱 분석

Step 5 — 순차 파이프라인: Codex 분석 → Gemini 영향도 리뷰 → Claude 종합

Step 6 — 자동 라우팅: 작업 특성에 따라 모드가 자동 전환되는 것을 확인

정책 문서의 자동화

정책 파일이 50개를 넘으면서, 이를 사람이 읽기 편하게 보여줄 Docs 사이트가 필요해졌습니다.

먼저 정책 레포의 특정 디렉토리에 변경이 생기면 docs 사이트가 자동으로 빌드·배포되는 CI/CD 파이프라인을 구축했습니다. 정책 파일의 헤딩을 동적으로 파싱해 manifest를 생성하고, 이를 기반으로 nav와 overview 페이지가 자동 갱신됩니다.

새 정책을 추가하거나 기존 정책의 섹션을 바꾸면 별도 작업 없이 CI를 통해 문서 사이트에 반영되므로, 신규 입사자가 어떤 정책이 있는지 궁금할 때 항상 최신 문서를 볼 수 있습니다. 분산 운영되던 두 개의 문서 사이트도 하나의 통합 포털로 합쳤습니다. 진입점이 하나로 줄면서 온보딩 중 이 문서는 어디서 보지 하는 혼란도 사라졌습니다.

AI가 장애 대응을 돕는 방식

입사 일주일쯤 지나니 장애 대응에도 참여하게 됐습니다. 이슈는 특정 서비스에서 빈 화면이 지속적으로 노출되는 문제였습니다.

평소 스타일대로 트러블슈팅을 했다면 어디서부터 봐야 하지 하며 문맥 파악에 시간을 많이 썼을 겁니다. 하지만 정책 파일에 정의된 트래픽 조사 가이드, 서비스 조사 가이드를 따라가며 원인을 빠르게 추적할 수 있었고, 상황에 맞는 가이드를 Claude가 자동으로 참조하며 분석을 진행했습니다.

이게 온보딩 관점에서 의미 있는 이유는, 팀의 장애 대응 노하우가 정책 파일에 축적돼 있기 때문입니다. 신규 입사자가 경험이 부족해도 AI가 팀의 축적된 지식을 기반으로 조사 방향을 제시해 줍니다. 덕분에 어디서부터 봐야 할지 모르겠다는 상황이 크게 줄고, 히스토리를 빠르게 파악해 원인 파악 시간을 상당히 아낄 수 있었습니다.

10일간 배운 것들

10일간 직접 겪고 만들며 정리한 원칙입니다.

정책은 코드처럼 관리해야 합니다. Git에 커밋하고, PR로 리뷰하고, CI로 검증합니다. AI에게 알아서 해달라고 맡기는 게 아니라, 명확한 규칙을 파일로 정의하고 그 안에서 일하게 합니다.

실습 없는 정책은 의미가 없습니다. Multi-Agent 온보딩을 만들 때 직접 6단계를 실행하며 위임 스크립트 버그를 발견했고, Phase 자동 전환 버그도 온보딩을 끝까지 돌려보며 찾았습니다. 끝까지 돌려보고 검증하지 않으면 막히는 지점을 알 수 없습니다.

AI에게 추측하게 하면 안 됩니다. 클러스터 이름, SSO 프로필, 레포 경로 같은 값을 AI의 기억에 의존하면 만료된 정보가 전달됩니다. 항상 원본 파일에서 실시간으로 읽어오는 구조가 필요합니다.

guardrail이 있어야 AI가 진짜 업무 파트너가 됩니다. 모든 것을 AI에게 맡기는 게 아니라, 도구 우선순위를 두고 Phase별로 점진적으로 접근합니다. 이 구조가 견고해야 AI가 도움이 되는 파트너로 동작합니다.

앞으로의 방향

현재 이 온보딩 시스템은 인프라팀에서 활발히 쓰이고 있고, 다른 스쿼드로의 확장을 준비하고 있습니다. 스쿼드별 정책 설정은 이미 추가됐고, 챕터별 AI 명령어도 구성 중입니다.

온보딩 이후에는 ECS에서 EKS로의 서비스 마이그레이션을 진행하고 있는데, 전체 서비스 조사, TOBE 아키텍처 분석, GitOps 레포 구조 개선까지 모든 과정에서 AI를 적극 활용하고 있습니다.

마무리

대부분 인프라 영역에서 AI 활용은 대부분 보수적입니다. 프로덕션 환경을 다루는 팀이 AI에게 kubectl을 실행하게 하고, 장애 대응 runbook을 AI 정책으로 관리한다는 건 쉽게 납득되는 이야기가 아닙니다.

하지만 아임웹 인프라팀은 분위기가 달랐습니다. 팀 리드 용현 님은 약 5개월 전부터 AI 도입을 직접 주도해 왔습니다. 처음엔 개인 생산성을 높이는 데서 시작해, 팀 전체가 하나의 CLAUDE.md를 공유하는 단계로, 그리고 Claude + Gemini + Codex를 조합한 Multi-Agent 체제까지. 그 여정을 기술블로그로 공개해 왔습니다.

CTO도 인프라팀의 AI 활용에 적극적인 관심을 갖고 계십니다. 비용 검증이나 의사결정 과정에서 직접 엔지니어링 채널에서 질문하고, 팀의 판단을 신뢰하면서도 수치적 근거를 요구하는 방식으로 관여하셨습니다.

AI를 쓴다가 아니라 AI를 어떻게 쓰고 있는지를 묻는 리더십이 있었기에, 팀은 더 체계적으로 guardrail을 만들 수밖에 없었습니다.

본문에 다 담지는 못했지만 같은 팀의 승민A님, 상원님, 종은님도 초기엔 정답이 정리되지 않은 상태라 대부분의 시도가 말 그대로 맨땅에 헤딩이었습니다. (모두 shout out 합니다 🫡) 각자 다른 접근으로 도구를 시험하고, 실패한 방식과 성공한 방식을 공유하며 점차 팀의 기준이 만들어졌습니다.

이런 환경이 있었기에 입사 10일 차인 제가 온보딩 시스템을 새로 설계하고, Multi-Agent 실습을 구성하고, 문서 자동화 파이프라인을 구축할 수 있었습니다. 인프라팀이 매주 진행하는 AI Syncup 미팅에서 팀원들이 각자의 AI 활용 경험을 공유하고, 사내 데이터 조회 도구를 자체 개발해 AI의 1순위 도구로 쓰고, AI 권한을 팀 전원에게 열어두는 문화가 없었다면 신입이 온보딩을 설계한다는 것 자체가 불가능했을 겁니다.

10일간의 경험을 한 문장으로 줄이면 이렇습니다.

AI에게 자유를 주는 게 아니라 좋은 울타리를 만들어 주는 것이 진짜 활용입니다. 그리고 그 울타리는 혼자 만드는 게 아니라 팀, 나아가 조직이 함께 쌓아가는 것입니다.