수정 사항을 무엇으로 입증할까요

점수 계산을 수정했습니다. 답변에는 터미널 출력, 점수판 스크린샷, 짧은 "완료" 메시지가 있고 파일도 많습니다. 하지만 간단한 질문이 남습니다. 이 중 무엇이 작업 요구 사항을 충족했음을 보여 줄까요?

증거란 수정 사항 옆에 놓인 아무 파일이나 뜻하지 않습니다. 무엇을 검사했고, 어떤 코드 상태에서 검사했으며, 결과가 어땠는지 보여 주는 구체적인 검사 결과입니다. 자료마다 답하는 질문이 다르며, 하나의 자료가 모든 질문에 답해 주지는 않습니다.

요구 사항을 검증 가능한 주장으로 바꾸는 법, 명령 실행에 관해 무엇을 기록할지, 그리고 로그와 diff, 화면 캡처가 각각 무엇을 입증하는지 살펴보겠습니다. 그런 다음 여섯 필드로 된 짧은 EVIDENCE_LOG에 정보를 모으고, 자료 묶음이 충분한지도 따져 보겠습니다.

검사 기준이 확인 방법을 정합니다

글 전체에서 사용할 예시는 점수판이 있는 간단한 보너스 게임입니다. 시작 점수는 0이고, 세 번 맞추면 3점을 받아야 하지만 수정 전에는 30점을 받았습니다. 점수 규칙은 이 게임을 위해 정한 것입니다. 다른 프로젝트에서는 규칙이 다를 수 있으니 그대로 적용하면 안 됩니다.

"점수 계산을 수정했다"는 말만으로는 검증할 수 없습니다. 무엇을 실행하고 무엇을 확인해야 하는지 알 수 없기 때문입니다. 검증 가능한 주장은 초기 상태, 동작, 기대 관찰 결과라는 세 부분으로 이루어집니다. 예를 들면 "점수가 0일 때 세 번 맞추면 3점을 얻고, 점수판에 3이 표시된다"입니다. 이제 확인 방법이 분명해졌습니다.

이 주장은 다시 각각의 관찰 결과로 나뉩니다. 계산 결과와 플레이어가 보는 화면은 서로 다르므로, 각각 다른 자료로 확인해야 합니다. 표의 세 번째 행은 리더보드에 점수가 반영되는 경우입니다. 작업 요구 사항에 이 항목이 없다면 상관없지만, 있다면 이를 확인할 관찰 결과도 따로 있어야 합니다.

여기서는 세 번째 열이 가장 중요합니다. 증거가 입증하는 내용은 거의 언제나 기대보다 적으며, 그 경계는 실제로 수행한 동작이 끝나는 지점에 있습니다. 이 예시에서 계산 테스트는 점수판을 확인하지 않고, 점수판 캡처에는 변경된 코드 행이 나오지 않습니다.

두 가지를 따로 보세요. 요구 사항은 마지막에 사실이어야 하는 내용이고, 결과는 실제로 얻은 내용입니다. 한 문단에서 두 가지를 섞으면 "3점을 더해야 한다"가 어느새 "3점을 더한다"로 바뀝니다. 실제로는 아무도 아무것도 실행하지 않았는데도 말입니다.

명령과 실행 결과

검사 실행은 다섯 가지 정보로 설명할 수 있습니다. 일주일 뒤에 검사를 다시 수행할 사람에게는 어느 하나도 자명하지 않습니다.

• 명령을 실행한 폴더
• 명령 자체, 그대로
• 코드 상태: 수정 전인지 후인지, 어떤 커밋하지 않은 변경 사항이 있었는지
• 종료 결과: 종료 코드와 최종 카운터
• 실제로 실행된 검사와 실행되지 않은 검사

"npm test를 실행해야 한다"와 "npm test를 실행했고, 결과는 이렇다"는 구분해야 합니다. 앞의 문장은 앞으로 할 일에 대한 지시이고, 뒤의 문장은 사실입니다. 특히 무엇을 검사해야 하는지 답변에 잘 정리되어 있으면 의도를 결과인 것처럼 말하기 쉽습니다.

npm test는 "모든 테스트"를 실행하는 명령이 아닙니다. 선택한 npm 프로젝트의 package.json에서 scripts 섹션의 test 필드에 지정된 내용을 실행합니다. 어떤 프로젝트인지 추측하지 않도록 해당 프로젝트의 루트에서 명령을 실행하고 그 폴더를 기록하세요. 다른 프로젝트에서는 같은 이름에 다른 도구나 다른 단계가 연결되어 있을 수도 있고, 아무것도 연결되어 있지 않을 수도 있습니다.

명령은 종료 코드와 함께 끝납니다. 0은 보통 "도구가 실행을 성공으로 판단했다"는 뜻입니다. bash에서는 명령 직후 echo $?로 확인할 수 있고, PowerShell에서 npm 같은 외부 프로그램은 $LASTEXITCODE에 저장됩니다. 하지만 종료 코드가 0이라고 해서 필요한 테스트가 실행된 것은 아닙니다. 테스트를 건너뛰었거나, 이름으로 필터링했거나, 아예 작성하지 않았을 수도 있습니다. 그러므로 종료 코드와 함께 카운터와 확인하려는 테스트 이름도 기록해야 합니다.

로그에서 무엇을 보관할까요

실행 출력은 길 수 있으므로 전체 내용을 증거 기록에 옮기지는 않습니다. 짧은 발췌에는 실패한 테스트 이름, 기대값과 실제값, 실패 원인, 최종 카운터라는 네 가지 정보가 들어갑니다. 나머지는 링크를 걸어 둘 파일에 보관합니다. 아래는 실행 기록이 아닌 축약된 학습용 출력 예시입니다.

✖ three matches give 3 points (2.4108ms)
  AssertionError [ERR_ASSERTION]: Expected values to be strictly equal:
  30 !== 3
      at TestContext.<anonymous> (src/bonus-game/score.test.js:8:10)
ℹ tests 1
ℹ pass 0
ℹ fail 1
ℹ skipped 0

이것은 발췌본이며 전체 출력은 예를 들어 logs/test-fail.txt 파일에 저장되어 있습니다. 이 발췌만으로도 핵심을 알 수 있습니다. 세 번 맞추는 테스트가 실패했고, 기대값은 3이었지만 30이 나왔으며, 건너뛴 검사는 없습니다.

원본 출력은 그대로 증거 기록에 넣습니다. "잘못된 배율 때문에 테스트가 실패했다"고 바꿔 쓰면 이해하기는 쉽지만, 이는 관찰 결과가 아니라 해석이므로 기록만 보고는 확인할 수 없습니다. 둘을 나란히 두세요. 먼저 도구가 출력한 줄을 보여 주고, 그다음 설명을 덧붙이면 됩니다.

스택 트레이스의 주소는 검사가 실패를 알린 위치, 즉 테스트 파일을 가리킵니다. 원인은 게임 코드에서 찾습니다. 그곳에서 발견한 배율은 코드를 읽어서 알아낸 결과이지 로그에 적힌 내용이 아닙니다. 나중에 숫자 10이 어디서 나왔는지 헷갈리지 않도록 증거 기록에서는 이 두 출처를 서로 다르게 표시하세요.

diff가 입증하는 내용

Diff는 파일의 두 상태가 어떻게 다른지 보여 줍니다. 수정 후 코드를 한 번이라도 실행했는지, 기대한 대로 동작이 바뀌었는지는 알려 주지 않습니다.

--- a/src/bonus-game/score.js
+++ b/src/bonus-game/score.js
@@ -1,5 +1,5 @@
-const POINTS_PER_MATCH = 10;
+const POINTS_PER_MATCH = 1;

 function calcScore(matches) {
   return matches * POINTS_PER_MATCH;
 }

이 발췌 아래에는 어떤 상태끼리 비교했는지 한 줄로 적어야 합니다. 예를 들면 "수정 전 커밋 a1b2c3d와 작업 트리를 git diff HEAD로 비교"라고 쓸 수 있습니다. 여기서 식별자는 학습용이므로 실제 로그에는 본인의 식별자를 적으세요. 이 명령은 커밋을 위해 스테이징한 변경 사항까지 포함해 현재 추적 중인 파일과 HEAD를 비교합니다. HEAD가 없는 일반 git diff는 스테이징 영역과의 차이만 보여 주므로 git add 뒤에는 출력이 없을 수도 있습니다. 설명이 없으면 diff는 "이것과 저것의 차이"처럼 보일 뿐이라 비교를 다시 수행할 수 없습니다.

테스트의 기대값이 여전히 3인지도 확인하세요. 코드와 함께 기대값도 바뀌었다면 이야기가 달라집니다. 요구 사항에 맞게 동작을 고친 것이 아니라 검사 기준을 동작에 맞춘 것입니다.

여기서 실수하기 쉬운 기술적인 부분이 하나 있습니다. 수정 사항을 아직 커밋하지 않았다면 작업 트리와 마지막 커밋을 비교해 변경을 확인할 수 있습니다. 커밋한 뒤에는 같은 비교 결과가 비어 있습니다. 작업에서 아무것도 바뀌지 않았다는 뜻이 아니라, 변경 사항이 이력에 들어갔으므로 커밋을 이전 상태와 비교해야 한다는 뜻입니다. 빈 diff만으로는 아무것도 입증되지 않습니다. 어떤 두 상태를 비교하는지가 중요합니다.

스크린샷에서 확인할 수 있는 것

상태와 동작

점수판에 3이 나온 캡처가 입증하는 것은 하나뿐입니다. 캡처한 순간 점수판에 3이 표시되었다는 사실입니다. "세 번 맞춰서 3점을 얻었다"는 말과는 다릅니다. 초기 점수가 얼마였는지, 실제로 무엇을 했는지는 화면에 나오지 않습니다.

캡처가 증거가 되려면 옆에 시나리오를 기록해야 합니다.

1. 무엇을 열었는지: 페이지 주소나 실행 방법, 수정된 버전인지 여부
2. 초기 상태: 시작 점수가 0이고 이전 데이터가 불러와지지 않았음
3. 동작: 세 번 맞춤
4. 관찰 결과: 동작 직후 캡처한 점수판에 3이 표시됨

이 기록이 없으면 어떤 캡처든 여러 방법으로 만들 수 있습니다. 어제 열어 둔 이전 버전의 탭, 다른 실행 환경, 이미 0이 아니었던 점수도 그럴듯하지만 아무것도 입증하지 못하는 화면을 만들 수 있습니다.

이 글에는 의도적으로 점수판 스크린샷을 넣지 않았습니다. 검사용 스크린샷은 필요한 버전에서 시나리오를 재현한 뒤 직접 또는 자동화 도구로 촬영해야 합니다. 그림으로 그리거나 설명을 위해 만든 점수판은 실제 화면과 똑같아 보여도 증거가 될 수 없습니다. 직접 캡처할 때는 점수판 전체를 담고, 시나리오 기록에 페이지 주소를 적은 다음 기록과 함께 보관하세요. 그래야 일주일 뒤에도 어떤 실행에서 나온 화면인지 알 수 있습니다.

모델이 읽어 낼 수 있는 것

이미지를 세션에 전달하고 내용을 읽어 달라고 요청할 수 있습니다. 요청 문구가 중요합니다. 미리 정한 결론을 확인해 달라고 하기보다, 화면에 보이는 숫자와 의문점을 말해 달라고 하세요. 예를 들어 "초기 상태가 보이나요", "어떤 버전인지 알 수 있나요"라고 물을 수 있습니다. "버그가 수정됐는지 확인해 줘"라고 요청하면 아무것도 검사하지 않은 정중한 동의가 돌아오기 쉽습니다.

이미지를 전달할 수 있는지는 사용하는 모델과 환경에 따라 다릅니다. Claude Code에서는 저장된 이미지의 경로를 지정하고 읽어 달라고 요청할 수 있습니다. 이미지가 로드되지 않으면 먼저 경로와 파일 접근 권한을 확인하세요. 모델만 바꾼다고 문제가 해결되는 것은 아닙니다.

같은 시나리오를 수정 전후에 실행하기

유용한 비교는 같은 검사가 결함이 있는 구현에서는 실패하고 수정된 구현에서는 통과하는 경우입니다. 실패는 검사가 해당 결함을 찾아낸다는 것을 보여 주고, 통과는 검사한 시나리오에서 수정 후 결함이 사라졌음을 보여 줍니다.

단, 같은 초기 데이터와 기대값으로 비교해야 합니다. 시작 점수, 맞춘 횟수, 기대값 3이 모두 같아야 합니다. 수정 후 같은 테스트를 실행한 결과는 다음과 같습니다.

✔ three matches give 3 points (1.3983ms)
ℹ tests 1
ℹ pass 1
ℹ fail 0
ℹ skipped 0

두 번의 실행 사이에는 구현만 바뀌고 테스트, 입력 데이터, 기대값, 실행 조건은 그대로여야 합니다. 요구 사항이나 테스트의 기대값을 바꿔야 했다면, 변경된 기준으로 새 비교 실행을 해야 합니다. 두 상태에서 모두 실행하지 않고 말로 설명하는 것만으로는 충분하지 않습니다. 이런 상황에서 "빨간색에서 초록색이 됐다"고만 하면 오해를 부릅니다.

before.txt와 after.txt라는 이름의 파일 두 개가 있다고 해서 그 자체로 무엇이 입증되지는 않습니다. 파일 이름은 증거가 아닙니다. 내부를 확인하세요. 같은 명령인지, 테스트와 기대값이 같은지 봐야 합니다. 결함 상태를 다시 만드는 확인 작업(git stash를 사용하는 방법)은 별도 규칙이 있는 검사입니다. 여기서는 수정 전 실패가 기억에 의존한 것이 아니라 실제 실행에서 나온 결과여야 한다는 점만 기억하면 됩니다.

간단한 EVIDENCE_LOG

EVIDENCE_LOG는 이 글에서 여섯 필드를 다음 순서로 적는 일반 텍스트 로그입니다. 증상, 로그 증거, 결함 상태에서의 실패, 수정, 정직한 통과 결과, 스크린샷. 이렇게 하면 증상, 수정, 결과를 쉽게 연결할 수 있습니다. 다만 필드 순서만으로 기록의 신뢰성이 보장되지는 않습니다.

앞에서 모은 내용은 이 필드에 나눠 적으면 됩니다. 명령과 폴더는 실패 필드에, 비교할 상태는 수정 필드에, 전체 파일 링크는 그 파일이 나온 필드에 넣습니다. 별도의 문서 묶음을 더 만들 필요는 없습니다.

아래는 각 필드에 무엇을 적을지 보여 주는 학습용 예시입니다. 실제로 검사를 수행했다고 주장하는 보고서가 아닙니다. 본인의 로그에는 예시 문구 대신 실제 결과를 적으세요.

증상: 보너스 게임에서 시작 점수가 0일 때 세 번 맞추면 3점이 아니라
30점을 얻습니다. 매번 재현됩니다. 게임을 열고, 세 번 맞춘 다음,
점수판을 확인합니다.

로그 증거: 실행 출력의 테스트 "three matches give 3 points"에서
"30 !== 3"이 나옵니다. 전체 출력은 logs/test-fail.txt에 있습니다.
코드를 읽어 확인한 별도 내용: src/bonus-game/score.js에서
POINTS_PER_MATCH 값은 10입니다. 이는 코드를 읽은 결과이며
테스트 출력에는 숫자 10이 없습니다.

결함 상태에서의 실패: HEAD a1b2c3d (학습용 식별자), 작업 트리는
깨끗합니다. 커밋에는 잘못된 계산과 테스트가 포함되어 있습니다.
폴더: /project/bonus-game, 명령: npm test.
package.json의 scripts.test = node --test입니다. "three matches give 3 points"가
실패합니다. 원인은 "30 !== 3", tests 1, pass 0, fail 1, skipped 0,
종료 코드 1입니다. 위는 출력 발췌이며 전체 내용은 logs/test-fail.txt에 있습니다.

수정: src/bonus-game/score.js의 POINTS_PER_MATCH를 10에서 1로
변경했습니다. 다른 변경 사항은 없습니다. HEAD는 a1b2c3d로 동일합니다.
Diff: git diff HEAD로 이 커밋과 작업 트리를 비교했습니다.
diffs/score-fix.diff에 저장했습니다.
테스트의 기대값은 기존과 같이 3입니다.

정직한 통과 결과: 수정 후 같은 폴더에서 같은 npm test 명령을
실행했습니다. 같은 테스트가 통과했습니다. tests 1, pass 1,
fail 0, skipped 0, 종료 코드 0입니다.
전체 출력은 logs/test-pass.txt에 있습니다.
다섯 번 맞추는 시나리오는 실행하지 않았습니다.

스크린샷: screenshots/bonus-score-3.png. 수정 후 같은 작업 트리에서
http://localhost:3000 주소로 게임을 새로 열었습니다.
시작 점수는 0이고 세 번 맞춘 뒤 점수판에 3이 표시됩니다.
결과가 리더보드에 저장되는지는 확인하지 않았습니다.

예시에 나온 경로는 단지 예시일 뿐입니다. 전체 로그, diff, 이미지는 프로젝트에 비슷한 파일이 있는 위치에 보관하면 됩니다. 이를 위한 별도의 필수 폴더 구조는 없습니다.

다섯 번째와 여섯 번째 필드의 마지막 문장에 주목하세요. 실행하지 않았거나 확인하지 않은 내용은 "실행하지 않음", "확인하지 않음"처럼 한 문장으로 분명히 표시합니다. 게으르다는 고백이 아니라 결론의 범위를 나타내는 말입니다. 이런 문장이 없으면 로그가 더 완전해 보일 수 있지만, 실제로 하지 않은 일을 그저 언급하지 않은 것뿐입니다.

직접 확인해 보세요

작업에는 두 가지 기준이 있습니다. 시작 점수가 0일 때 세 번 맞추면 3점을 얻고, 세 번 맞춘 뒤 인터페이스에 3이 표시되어야 합니다. 다음 여섯 가지 자료가 있습니다.

1. 에이전트의 "완료, 버그를 수정했습니다"라는 메시지
2. npm test를 실행하라는 지시
3. 같은 테스트의 실제 실행 결과: 수정 전 실패, 수정 후 통과
4. 배율 변경 사항이 담긴 diff
5. 실행 설명 없이 숫자 3만 나온 화면 캡처
6. 재현한 시나리오 기록과 연결된 화면 캡처

어떤 자료가 두 기준을 충족하기에 충분하며, 무엇이 아직 확인되지 않았을까요? 다음 내용을 읽기 전에 먼저 답을 생각해 보세요.

해설입니다. 첫 번째 기준은 3번 자료로 확인할 수 있습니다. 같은 테스트를 실제로 수정 전후에 실행한 결과입니다. 4번의 diff는 코드가 어떻게 바뀌었는지 설명하지만 실행을 대신하지는 않습니다. 변경과 실행은 별개의 일입니다. 두 번째 기준은 시나리오 기록과 캡처가 함께 있는 6번 자료로 확인합니다. 초기 상태와 동작이 모두 드러납니다. 1번과 2번은 아무것도 입증하지 못합니다. 완료 메시지에는 검증 가능한 근거가 없고, 지시는 앞으로 할 일을 설명할 뿐입니다. 5번은 숫자 3을 보여 주지만 점수가 어떻게 계산되었는지는 알 수 없습니다. 여섯 자료가 모두 있어도 리더보드 저장은 확인되지 않은 채 남습니다. 저장된 값을 다시 읽는 시나리오가 없기 때문입니다.

세션에서 이런 로그를 작성할 수도 있습니다. 다음 프롬프트를 사용해 보세요.

여섯 필드로 EVIDENCE_LOG를 작성해 줘. 각 결론에 실제 검사,
코드 상태, 결과의 출처를 적어 줘.
실행하지 않은 항목은 따로 표시해 줘. 스크린샷에서는 실제로
보이는 내용만 말하고 내부 계산이 맞다고 추론하지 마.

Claude Code로 증거 수집하기

작업 순서는 다음과 같습니다.

1. 에이전트가 각 기준을 구체적인 검사와 연결합니다. 무엇을 실행할지, 어떤 코드 상태에서 실행할지, 어떤 결과를 확인할지 정합니다.
2. 현재 환경에서 가능한 검사를 실행하고 명령과 원본 출력을 보여 줍니다.
3. 관찰 결과를 첨부합니다. 출력 발췌, 전체 파일 링크, 재현한 시나리오 설명 등이 포함됩니다.
4. 한계를 분명히 밝힙니다. 실행하지 않은 항목과 현재 자료만으로 주장할 수 없는 내용을 적습니다.

증거 자체를 확인하는 일은 여러분에게 남습니다. 첨부된 파일을 열어 내용을 보고, 시나리오가 기준에 적힌 내용과 맞는지 대조한 다음, 검사 흔적이 보이지 않는 항목에 대해 불편한 질문 하나를 던지세요. 보통 이 정도면 실제 증거와 그럴듯하게 정리한 요약을 구분할 수 있습니다.

기술 참고 자료: git diff, git stash, Node.js test runner, npm test, Claude Code의 이미지.