Claude Code로 대화형 DevOps 온보딩 만들기
온보딩을 만든 계기
회사 서비스에 Alloy와 Loki, Grafana를 도입하고 직접 운영했다.
스택을 세우고 구현하는 것까지는 내가 했지만, 나 말고도 다른 사람이 이 업무를 무리 없이 진행할 수 있어야 했다.
그리고 신규 팀원이 들어왔을 때 파일을 하나씩 뒤져 보며 감을 잡는 수고를 하도록 두고 싶지 않았다.
그래서 실제 업무 단계까지 빠르게 올라올 수 있는 온보딩이 필요했다.
문서형 온보딩에서 대화형 온보딩으로
처음에는 평범한 문서형 온보딩으로 만들었다.
커리큘럼 문서를 순서대로 읽고, 실습 VM에서 명령을 따라 치는 방식이다.
| # | 문서 | 다루는 것 |
|---|---|---|
| 01 | 아키텍처 개요 | 스택 전체 그림, 한 호스트 systemd 운용을 고른 이유 |
| 02 | Day 1: 실습 환경 세팅 | VMware 이미지 기동, 사전 조건 점검 |
| 03 | Day 2: 로그 발생과 파일 회전 | stdout → 파일, copytruncate, 웹 로그 규칙 |
| 04 | Day 3: Loki | auth_enabled, 로컬 listen, 보관 기간, LogQL 기초 |
| 05 | Day 4: Alloy | tail·파싱·라벨 승격, 카디널리티, 발생 시각 |
| 06 | Day 5: Grafana | provisioning, 권한 경계 |
| 07 | Day 6: 운영 | 기동·정지 순서, 상태 판정, 로그 반출 |
| 08 | 조용한 실패 진단 | 오류 없이 어긋나는 구간을 일부러 만들어 관찰 |
| 09 | 실습 과제 | PostgreSQL 로그 파이프라인 따라가기와 확장 |
Day 번호가 곧 설치 의존 순서다.
받는 쪽(Loki)을 먼저 세우고 보내는 쪽(Alloy)을 붙여야 문서 순서대로 따라갔을 때 동작한다.
스크립트·설정·RPM은 모두 실습용 VM 이미지 안에 미리 배포해 두었고, 저장소에는 문서만 둔다.
모든 문서를 작성하고, 내가 직접 학습자가 되어 온보딩을 따라가 봤는데 불편한 점이 있었다.
- 중간중간 궁금한 게 생기면 내가 직접 찾아봐야 하고, 그 과정에서 비용이 든다.
- 만약 내가 모르는 용어가 나오면 그걸 직접 찾아봐야 한다.
학습을 하는 데 있어 직접 찾아보는 품이 드는 것조차 나는 러닝 커브를 가파르게 만드는 요소라고 생각했다.
따라서 단순히 문서만 읽고 따라하기보다는, 학습자와 상호작용하면서 용어나 주변 정보를 찾아보는 시간을 줄일 방법이 필요했다.
그러다 최근 개발 컨퍼런스를 몇 군데 다니면서 AI로 온보딩을 진행하는 사례를 봤던 것이 떠올랐다.
여기서 영감을 받아, 같은 문서를 두고 Claude와 대화하며 배우는 온보딩을 설계했다.
저장소 구성
온보딩 저장소에서 Claude Code와 관련된 부분은 이것뿐이다.
.claude/
├─ settings.json 세션 시작 안내 훅, 프롬프트 제안 끄기
├─ hooks/
│ ├─ onboarding-welcome.json 시작 안내 문구
│ └─ README.md 문구 수정 방법
└─ skills/onboard/SKILL.md 대화형 튜터 스킬 (/onboard)
.onboarding/progress.md 학습자 개인 진도 (gitignore)
학습자는 저장소 루트에서 claude를 실행하고, /onboard 3처럼 Day 번호를 넣어 튜터를 부른다.
튜터 스킬 /onboard 설계
기본 형태는 단순하다.
문서의 절(##)마다 Claude가 내용을 보여 주고, 절이 끝날 때마다 학습자에게 이해했는지 묻고, 궁금한 점을 받아 답한다.
단순한 만큼 Claude가 마음대로 굴 여지가 많아서, 스킬 대부분은 “하지 말아야 할 것”을 정하는 데 썼다.
규칙 1: 문서를 읽고 답할 수 있는 것만 질문해라
튜터가 가장 먼저 지켜야 할 원칙은 문서 밖으로 나가지 않는 것이다.
- 설명하기 전에 해당 절을
Read로 읽는다. 기억이나 일반 지식으로 대신하지 않는다. - 문서를 Claude의 말로 요약하거나 의역하지 않고 원문 그대로 보여 준다.
- 보여 줄 때는
docs/04-day3-loki.md:112처럼 출처 위치를 붙여, 편집기에서 바로 열 수 있게 한다. - VM 안의 경로·설정값·명령은 문서에 적힌 것만 쓴다. 문서에 없으면 없다고 밝힌다.
- 문서에 없는 용어나 개념은 문서가 링크한 공식 문서를 근거로 설명한다. 우리 환경에만 있는 내용은 짐작하지 않는다.
- 문서와 실제 출력이 어긋나면 문서를 고쳐 말하지 않고, 어긋난 지점을 학습자에게 보여 준 뒤 “문서 개선 후보”로 기록한다.
요약을 금지한 이유는 온보딩의 단일 진실 원천이 문서이기 때문이다.
Claude가 매번 다르게 풀어 설명하면 학습자마다 배운 내용이 달라지고, 문서에 빈틈이 있어도 Claude의 설명에 가려 드러나지 않는다.
확인 질문을 잘 묻는 규칙
절이 끝날 때마다 던지는 확인 질문도 이 원칙을 따른다.
시범 운영에서 가장 많이 고친 부분이 확인 질문이다.
처음에는 “왜를 묻는다” 정도만 적어 두었는데, 실제로 돌려 보니 질문이 모호하거나 답이 질문 안에 들어 있는 경우가 계속 나왔다.
지금은 이런 규칙을 둔다.
- 관점을 밝힌다. 예: 접근 제한, 데이터 흐름, 설정 적용 순서.
- “어떻게”는 방식과 절차 양쪽으로 읽히므로 피하고, “무엇 때문에”, “어떤 조건에서”로 묻는다.
- 필요한 배경은 질문에 한 문장으로 넣되, 답을 짐작할 수 있는 결론은 전제에 넣지 않는다.
- 답의 근거는 지금까지 보여 준 문서 안에 있어야 한다.
- 셸 문법처럼 학습 목표와 거리가 먼 부분은 질문하지 않고 한 줄로 안내만 한다.
스킬에는 좋은 예와 피할 예를 같이 적어 두었다.
좋은 예: Loki는 127.0.0.1에만 묶여 있어서 다른 PC에서는 접근할 수 없어요.
그런데 Alloy의 loki.write는 이 주소로 로그를 보낼 수 있어요.
접근 제한 관점에서, 무엇 때문에 가능할까요?
피할 예: Loki HTTP 포트 번호는? (외우기 질문)
피할 예: loki.write는 어떻게 127.0.0.1:3100으로 보낼 수 있을까요?
(전달 방식인지 접근 제한인지 모호함)
피할 예: 플러그인이 없어도 Grafana는 로그에 오류를 남기지 않아요.
그럼 왜 로그가 아니라 플러그인 목록으로 확인할까요? (전제가 곧 답)
질문을 보내기 전에 “전제만 읽어도 답이 나오는가?”, “답의 근거가 보여 준 절 안에 있는가?”를 스스로 점검하게 했다.
하나라도 걸리면 질문하지 않고 넘어간다.
규칙 2: 절 단위로 진행해라
한 절은 이 순서로 진행한다.
- 절 원문을 보여 준다. 한 응답에 40줄 안팎까지만 보여 주고, 길면
###하위 절이나 문단 경계에서 나눈다. 코드 블록은 중간에서 자르지 않는다. - 바로 확인 질문을 던지지 않는다. 먼저 “이해되셨나요? 궁금한 점이 있으면 편하게 물어보세요.”라고 묻고 기다린다.
- 학습자가 궁금한 점을 말하면 그 질문을 먼저 다룬다. 근거는 문서에서 찾는다.
- 이해했다고 하면 그 절의 “왜”를 묻는 확인 질문을 하나 던진다.
- 답이 맞으면 한 줄로 확인하고 다음 절로 간다.
넓은 표나 40줄이 넘는 설정 예시는 터미널에서 깨져 보이기 쉽다.
이런 부분은 “대화창에서는 읽기 불편할 수 있는데, 문서에서 볼까요?”라고 먼저 묻고, 원하면 편집기 위치와 GitLab 웹 링크를 함께 준다.
규칙 3: 학습자가 막히면 정답 대신 힌트로 유도해라
학습자가 막혔을 때 바로 정답을 주면 온보딩이 문서 낭독으로 끝난다.
그래서 도움을 한 단계씩만 올리도록 했다.
- 질문으로 되묻기: “지금 Loki가 어떤 설정으로 떠 있을까요?”
- 문서 위치 안내: “‘RPM이 먼저 띄운다’ 절을 다시 보세요.”
- 구체적 힌트: 확인할 명령이나 비교할 값을 짚어 준다.
- 정답 설명: 학습자가 “답을 알려 줘”라고 요청할 때만.
실습도 같은 태도로 진행한다.
명령을 실행하기 전에 “이 명령이 무엇을 확인하는지” 학습자가 먼저 말해 보게 하고, 출력을 받으면 학습자가 먼저 해석하게 한다.
예상과 다른 출력이 나와도 원인을 바로 말하지 않고, 다음에 무엇을 확인할지 함께 정한다.
훅과 가드레일
세션 시작 안내 훅
저장소에서 claude를 실행하면 커리큘럼 목록과 진행 방법이 먼저 뜨도록 SessionStart 훅을 걸었다.
{
"promptSuggestionEnabled": false,
"hooks": {
"SessionStart": [
{
"matcher": "startup",
"hooks": [
{
"type": "command",
"command": "cat \"${CLAUDE_PROJECT_DIR}/.claude/hooks/onboarding-welcome.json\""
}
]
}
]
}
}
훅은 JSON 파일을 출력하기만 하고 다른 명령은 실행하지 않는다.
Claude Code는 출력된 JSON의 systemMessage를 학습자 화면에 안내로 보여 준다.
matcher를 startup으로 두어 resume·clear·compact 때는 다시 띄우지 않는다.
한 가지 함정이 있었다.
Windows에 Git Bash가 없으면 훅이 PowerShell로 실행되는데, PowerShell을 거친 출력은 한글이 깨진 채 Claude Code에 전달된다.
그래서 안내 문구의 한글을 전부 \uXXXX로 이스케이프해 파일을 ASCII로만 저장했다.
출력 바이트가 모두 ASCII라 어떤 셸에서 실행돼도 같은 문구가 나온다.
대신 문구를 고칠 때는 이스케이프를 풀고, 고치고, 다시 이스케이프하는 절차를 hooks/README.md에 남겨 두었다.
# 마지막에 ASCII가 아닌 바이트가 남지 않았는지 확인한다. 0이 나와야 한다.
LC_ALL=C tr -d '\000-\177' < .claude/hooks/onboarding-welcome.json | wc -c
프롬프트 제안 끄기
Claude Code는 응답 뒤 입력창에 다음 입력을 회색으로 제안한다.
평소에는 편한 기능이지만, 튜터가 확인 질문을 던진 직후라면 이 제안이 질문의 답을 미리 보여 줄 수 있다.
그래서 promptSuggestionEnabled를 false로 꺼 두었다.
도구 권한 좁히기
튜터 스킬이 승인 없이 쓸 수 있는 도구는 읽기와 진도 파일 편집뿐이다.
allowed-tools:
- Read
- Glob
- Grep
- Edit(./.onboarding/**)
튜터의 역할은 문서를 읽고 대화하는 것이라, 저장소의 다른 파일을 고치거나 셸을 실행할 이유가 없다.
진도 파일
절 하나의 확인 질문을 통과하거나 실습 명령 하나의 출력을 확인할 때마다 .onboarding/progress.md를 갱신한다.
학습자가 예고 없이 터미널을 닫아도, 다음에 /onboard를 실행하면 마지막으로 마친 지점 다음부터 이어 간다.
처음에는 진도 파일을 .claude/ 아래에 두려고 했다.
그런데 Claude Code는 .claude/를 민감 경로로 보고 저장할 때마다 승인을 요구해서, 절마다 승인 창이 떴다.
그래서 .onboarding/으로 옮기고 .gitignore에 넣어 개인 기록이 저장소에 올라가지 않게 했다.
진도 파일은 이런 구조다.
# 온보딩 진도
- 배경: <Linux·systemd 경험, VM 준비 상태>
- 읽는 곳: <대화창 / 편집기>
- 마지막 위치: <문서 경로> / <절 제목>
## 완료한 Day
## 다시 볼 개념
## 문서 개선 후보
시범 운영에서 배운 것: 질문하는 방법이 주는 차이
공식 시범 범위는 Day 3(Loki)였지만, 실제로는 같은 절차로 09번 과제까지 이어서 진행해 봤다.
이렇게 진행하면서 가장 크게 느낀 건 질문하는 순서였다.
처음 설계에서는 절마다 바로 확인 질문을 던졌는데, 학습자 입장에서는 시험을 보는 느낌이 강했다.
“궁금한 점 있으세요?”를 먼저 묻도록 바꾸고 나서야 시험을 보는 기분이 아니라 함께 학습하는 느낌을 줄 수 있었다.
마치며
Claude를 온보딩에 붙이면서 가장 신경 쓴 건 Claude가 내 문서와 공식 문서를 기반으로 답하게 하는 것, 그리고 정답을 바로 말하지 않게 하는 것이었다.
그렇게 제약을 걸어 두니 Claude가 문서를 같이 읽으며 질문을 던지는 동료의 역할을 하고 있었다.
덤으로 학습자와 튜터가 대화하며 문서의 빈틈이 드러나, 문서 개선 후보가 그대로 이슈 목록이 됐다.
댓글남기기