---
kind: CASE
slug: the-guides-broke-at-the-first-command
title: 가이드 26편을 순서대로 따라가니 첫 명령부터 막혔다
topic: when-the-measurement-lies
topicName: 주입이 걸렸는지 무엇으로 아는가
project: keycloak-session-store
status: 게시 전
lastVerifiedOn: 2026-09-11
sourceRevision: cdac9b8178391311d8eca1ebc6cac15bb62d79af
source:
  - final/document.md#재현-가이드-26편과-그것을-따라가다-드러난-결함
---

# 가이드 26편을 순서대로 따라가니 첫 명령부터 막혔다

기반 7단계를 끝낸 독자가 실험 가이드의 첫 명령에서 막혔다. 2026-09-11 에 가이드 26편을 순서대로 따라가 보니 sudo kubectl 905건 가운데 게스트에서 돌아야 하는 명령은 0건이었다. sudo 는 root 환경이라 lab host 의 ~/.kube/config 를 못 본다. 명령 자체가 아니라 그 명령이 놓인 위치가 틀렸다.

## 관계

- **주입이 아홉 번 조용히 실패했고 전부 아무 일도 없는 것처럼 보였다**
  가이드마다 주입 검증 단계를 따로 둔 근거가 이 아홉 건이다.
- **산문으로 적힌 측정 장치를 실행 가능하게 고쳤더니 한 건이 깨졌다**
  그 기록은 명령이 산문이라 돌지 않았고, 이 기록은 명령이 도는데 놓인 위치가 틀렸다.
- **예측을 먼저 적고, 주입이 걸렸는지 결과와 따로 확인하고, 대조군 없이 귀속하지 않는다**
  가이드의 다섯 단계 가운데 주입 검증이 이 규칙을 절차로 옮긴 단계다.

## 문제

발견을 적은 문서와 별개로, 직접 쳐서 다시 만드는 가이드가 26편 있다. 각 편은 같은 다섯 단계로 적혀 있고 그중 주입 검증이 핵심인 편이 많다. 이 실험대에서 주입은 아홉 번 조용히 실패했고, 실패한 주입은 아무 일도 없었던 것처럼 보여서 영향이 없는 주입과 구별되지 않기 때문이다.

가이드를 쓴 다음 그것을 처음부터 순서대로 따라가 본 적은 없었다. 2026-09-11 에 실제로 쳐 보니 기반 7단계를 끝낸 독자가 실험 가이드의 첫 명령에서 막혔다.

## 결론

2026-09-11 감사에서 재현을 막는 결함이 계열로 나왔다.

sudo kubectl 을 쓰는 명령 : 905건
그중 게스트에서 도는 것 : 0건
저장소 클론 단계가 없는 편 : 05·06
그 단계에 없는 리소스를 조회하는 편 : 05

kubeconfig 는 lab host 의 ~/.kube/config 에 있고 sudo 는 root 환경이라 그 파일을 못 본다. 그래서 기반 7단계를 끝낸 독자가 첫 명령부터 막힌다. 905건 가운데 게스트에서 돌아야 해서 sudo 가 맞는 것은 0건이었고 전부 잘못된 것이었다.

개별 명령은 전부 실제로 돌았던 것이라 명령만 읽어서는 틀려 보이지 않는다. 틀린 것은 명령이 아니라 그 명령이 놓인 위치다.

## 검증 환경

감사 대상 : 재현 가이드 26편
가이드 위치 : ../source/docs/guides/experiments/
kubeconfig 위치 : lab host 의 ~/.kube/config
감사일 : 2026-09-11

## 재현 조건

1. 기반 가이드 7단계를 끝낸 상태에서 실험 가이드를 첫 편부터 순서대로 따라간다.

2. 각 편의 명령을 읽지 말고 실제로 쳐 보고, 막힌 곳과 막힌 이유를 적는다.

3. 26편에서 sudo kubectl 로 적힌 명령이 몇 건인지 세고, 그중 게스트에서 돌아야 하는 것이 몇 건인지 가른다.

4. 05·06 편의 kubectl apply -f deploy/... 가 가리키는 저장소가 lab host 에 있는지, 그 앞 단계에 클론이 있는지 확인한다.

5. 05 편의 -l app=bff 가 조회하는 리소스가 그 단계에 떠 있는지, 함께 실린 출력이 그 단계에서 나온 것인지 확인한다.

## 본문

<!-- body:start -->
실험 26건의 결과를 적은 문서와 별개로, 같은 실험을 직접 쳐서 다시 만드는 가이드가 26편 있다. 실험 26건을 다 끝낸 뒤 2026-09-11 에 그 26편을 처음부터 순서대로 따라가며 감사했다. 따라가는 동안 실험 계획서에 미해결로 남아 있던 항목 하나가 풀렸고, 재현을 막는 결함도 그때 나왔다 — 기반 가이드 7단계를 끝낸 독자가 실험 가이드의 첫 명령에서 막혔다. 막힌 곳은 네 군데였고, 한 편에서만 나온 실수가 아니라 계열로 나왔다.

## 가이드 한 편은 다섯 단계로 적혀 있다

각 편이 따르는 순서는 같다.

```text label="가이드 한 편의 구조"
기준선 → 주입 → 주입 검증 → 관찰 → 복구
```

다섯 단계 가운데 주입 검증이 핵심인 편이 많다. 이 실험대에서 주입은 아홉 번 조용히 실패했는데, 실패한 주입은 아무 일도 없었던 것처럼 보여서 영향이 없는 주입과 구별되지 않는다. 그래서 주입한 다음 그것이 실제로 걸렸는지 확인하는 단계를 따로 둔다.

## sudo 가 kubeconfig 를 못 본다

실험 가이드는 26편 전체가 `sudo kubectl` 로 적혀 있고, 세어 보니 905건이었다. 그런데 기반 가이드는 kubeconfig 를 lab host 의 `~/.kube/config` 에 두고, `sudo` 는 root 환경이라 그 파일을 못 본다. 그래서 기반 7단계를 끝내고 실험 가이드로 넘어온 독자는 첫 명령에서 바로 막힌다.

905건 가운데 게스트(lab host 위에서 도는 VM)에서 돌아야 해서 `sudo` 가 맞는 것은 0건이었다. 905건 전부 잘못 적힌 명령이었다. 이 905건과 0건은 2026-09-11 에 26편을 한 번 따라가며 센 값이고, 그 뒤 다시 세지 않았다.

## 05·06 편은 아직 없는 것을 가리킨다

05 편과 06 편은 `kubectl apply -f deploy/...` 를 쓴다. 이 경로는 상대경로인데 기반 가이드에는 저장소를 lab host 에 클론하는 단계가 없어서, 독자의 lab host 에는 그 경로가 가리킬 파일이 없다.

05 편에는 `-l app=bff` 로 리소스를 조회하는 명령도 있다. BFF(Backend For Frontend) 는 B-0 실험에서 처음 뜨므로 05 편 시점에는 조회할 리소스가 없고, 가이드에 실린 출력도 나중 단계에서 복사해 온 것이었다.

## 왜 명령만 읽어서는 틀린 곳이 안 보이나

막힌 네 곳을 나란히 놓으면 이렇다.

| 무엇이 재현을 막나 | 몇 건인가 |
|---|---|
| 실험 가이드 전편이 `sudo kubectl` 을 쓴다 | 905건 |
| 그중 게스트에서 도는 것 | 0건 |
| 기반 가이드가 저장소를 lab host 에 클론하지 않는다 | 05·06 |
| 그 단계에 아직 없는 리소스를 조회한다 | 05 |

네 결함의 원인은 하나로 모인다. 가이드를 쓰면서 순서대로 따라갔을 때 도는지를 검증하지 않고, 나중 시점의 환경에서 확인한 명령과 출력을 그 단계에 적었다.

개별 명령은 전부 실제로 돌았던 것이라 틀려 보이지 않는다. `-l app=bff` 의 출력도 지어낸 값이 아니라 나중 단계에서 실제로 나온 값을 옮겨 적은 것이었다. 틀린 것은 명령이 아니라 그 명령이 놓인 위치다.

## 이 감사가 확인하지 않은 것

고친 가이드를 처음부터 다시 따라가 끝까지 도는지는 확인하지 않았다. 905건과 0건도 2026-09-11 감사 한 번에서 나온 계수다.

이 감사의 결론을 「가이드를 쓴 뒤 처음부터 순서대로 한 번 따라간다」는 규칙으로 세우려면 어떤 가이드에 적용되고 어떤 가이드에는 적용되지 않는지를 대야 하는데, 그 적용 조건도 예외도 이 26편에서는 나오지 않았다.
<!-- body:end -->