10. 버그픽스

시작 상태

npm test && git status --short

9단계의 e2e 검증 커밋(test: 카운터 위치 e2e 검증) 이후여야 합니다. 첫 명령이 통과하고, 두 번째 명령의 출력이 비어 있어야 합니다. git status --short는 작업 트리가 더러워도 exit 0을 내므로, 종료 코드가 아니라 출력을 봅니다. 아니면 9. 검증으로 돌아갑니다.

이 단계에서 하는 것

결함 주입, /clear, 증상만 제시, 격리 재현, 원인 확정, 수정, 재검증 순서로 갑니다. 9단계 이후 실제 버그가 나타났다면 주입 대신 그 버그를 그대로 씁니다. 초록 테스트를 그대로 완료의 증거로 믿으면 안 되는 이유는 Bug Fix가 다룹니다.

따라하기

1단계에서 글자를 코드 유닛(.length)으로 골랐다면 아래 1번이 주입할 결함이 이미 현재 구현과 같습니다. 그 경우 먼저 스펙과 테스트를 기본 경로에 맞춥니다. 이모지 U+1F600을 1로 세는 계약으로 스펙을 고치고, 구현과 테스트를 그에 맞게 바꾸고, 게이트를 통과시킨 뒤 커밋합니다. <날짜>는 실제 스펙 파일 이름으로 바꿉니다. 그다음 1번으로 갑니다.

docs/specs/<날짜>-charcount.md 의 "글자" 정의를 "이모지 U+1F600 하나는 1로 센다"로 고치고,
src/countChars.ts 와 그 테스트를 새 정의에 맞게 바꿔 주세요.
npm run lint && npm test && npm run build 출력을 보여 주세요.

git add src docs/specs && git commit -m "docs: 글자 정의를 기본 경로로 정렬"

주입 세션입니다. 결함과 함께 테스트도 맞춰 고치게 합니다. 초록인데 깨져 있는 상태를 의도적으로 만드는 것입니다.

src/countChars.ts 의 세는 방식을 문자열의 .length 로 바꿔 주세요.
그 결과 실패하는 테스트가 있으면 기대값을 .length 결과에 맞춰 수정해서 npm test 를 초록으로 만들어 주세요.
"chore: 글자 수 계산 단순화" 메시지로 커밋해 주세요.

결함 커밋 SHA와 구현 파일 경로를 터미널 변수에 남깁니다. 주입 세션의 끝 비용과 컨텍스트 사용률을 읽어 docs/tutorial-log.md의 주입 세션 행에 적은 뒤 /clear합니다. 실제 버그를 골랐다면 그 결함이 있는 커밋과 파일로 바꿔 씁니다.

tutorial_defect_sha=$(git rev-parse HEAD)
tutorial_impl_file=src/countChars.ts

새 세션에는 증상만 줍니다. <날짜>는 실제 스펙 파일 이름으로 바꿉니다.

글자 수 세기에 이모지 하나를 넣으면 2로 셉니다. 스펙(docs/specs/<날짜>-charcount.md)은 1이어야 한다고 합니다.
고치기 전에, 이 증상을 재현하는 실패 테스트를 먼저 써서 실패 출력을 보여 주세요.
그다음 원인을 한 문장으로 말하고, 고친 뒤 npm test 출력을 보여 주세요.

관찰할 것 네 가지입니다.
- 기존 테스트가 초록이었다는 사실에 속아 “버그가 아니다”라고 하는지 확인합니다.
- 테스트 기대값이 바뀐 커밋을 git log -p로 찾아내는지 확인합니다.
- 실패하는 테스트가 수정보다 먼저 나오는지 확인합니다.
- 원인 설명이 “.length는 코드 유닛을 센다”는 메커니즘까지 닿는지 확인합니다.
커밋 직전에 수정 세션의 끝 비용과 컨텍스트 사용률을 읽어 docs/tutorial-log.md의 수정 세션 행에 적습니다. 메모 열에는 결함 SHA, 구현 파일 경로, 회귀 테스트 명령을 남깁니다. 수정 SHA는 바로 다음 커밋이므로 기록표에 적지 않고 $tutorial_fixed_sha로만 들고 갑니다. 11단계에서 이 커밋을 둘로 나누면 값이 달라집니다.
회귀 테스트와 기록표를 함께 커밋합니다.

git add src e2e docs/specs docs/tutorial-log.md
git commit -m "fix: 글자 수 계산 회귀 수정"
tutorial_fixed_sha=$(git rev-parse HEAD)

같은 터미널에서 아래 완료 확인을 실행합니다. 다른 터미널을 쓴다면 위에서 남긴 SHA를 그 터미널의 변수에 다시 지정합니다.

완료 확인

구현 파일만 주입 커밋 상태로 되돌리고, 테스트는 고친 상태로 둔 채 돌립니다. 주입 커밋이 테스트 기대값도 함께 바꿨으므로 src 전체를 되돌리면 초록이 나와 아무것도 확인하지 못합니다.

git status --short                               # 비어 있어야 합니다
git restore --source="$tutorial_defect_sha" --worktree -- "$tutorial_impl_file"
npm test; echo "injected exit=$?"
git restore --source="$tutorial_fixed_sha" --worktree -- "$tutorial_impl_file"
npm test; echo "fixed exit=$?"
git status --short

첫 exit은 0이 아닌 값이어야 합니다. 고친 테스트가 결함 구현 앞에서 실패하기 때문입니다. 둘째 exit은 0이어야 하고, 마지막 git status --short는 다시 비어 있어야 합니다. 실제 버그 경로에서는 이 회귀 테스트 명령을 그 버그의 재현 명령으로 바꿔 씁니다.

계측 기록

값은 2번과 5번에서 이미 적었습니다. “10. 버그픽스” 행은 주입 세션과 수정 세션 두 행으로 나눕니다. 시작 상태를 확인한 직후 시작 비용을, 커밋 직전에 끝 비용과 컨텍스트 사용률을 각각 적고 차액으로 읽습니다. 세션 수는 이 단계에서 연 세션 개수입니다. 실제 버그 경로를 택해 연 세션 개수가 다르다면 그 개수를 그대로 적습니다.

어긋났을 때

새 세션이 테스트가 초록이라는 근거로 “버그가 아니다”라고 하면 테스트 기대값을 바꾼 커밋을 보여 주고 다시 시킵니다. 이 상태의 판정 기준은 검사는 통과하는데 실제로는 깨져 있을 때에 있습니다.
재현 테스트 없이 바로 고치면 멈추고 실패 테스트부터 요구합니다. 순서의 근거는 Testing에 있습니다.