AI가 코드를 바꾸기 전에 무엇을 확인해야 할까?
이름 하나를 받는 함수에 공백 처리와 기본값을 더합니다. 같은 세 테스트의 실패와 통과를 따라가며 요구, 설계 판단, 실행 근거를 연결합니다.
사례판 발행 수정
사례판 검증: 2026-11-08, macOS 27.2 arm64 · Node.js 26.5.1 · node:test. 이 글에 실린 두 구현에 동일한 세 테스트를 실행해 수정 전 1개 통과·2개 assertion 실패, 수정 후 3개 통과를 확인합니다. 함수 동작의 단위 검증이며 Holmes-Kit 설치, 현재 세션의 MCP 연결 또는 실제 훅 강제를 증명하는 시험은 아닙니다.
먼저, 무엇을 유지하고 바꿀까?
기존 greet는 이름을 그대로 문장에 넣습니다. 새 요구는 문자열 양끝의 공백을 제거하고, 이름이 비었으면 World를 사용하는 것입니다. 정상 이름의 기존 응답은 유지해야 합니다. 구현에 앞서 이 세 가지를 관찰 가능한 결과로 적습니다.
이 표는 문자열 입력에 대한 계약입니다. null이나 객체를 처리하거나 사람 이름의 표기·언어 규칙을 정규화하는 요구까지 포함하지 않습니다.
| 입력 | 수정 전 응답 | 기대 응답 |
|---|---|---|
| "Ada" | Hello, Ada! | Hello, Ada! |
| " Ada " | "Hello, Ada !" — 공백 포함 | Hello, Ada! |
| "" — 빈 문자열 | Hello, ! | Hello, World! |
기준 구현을 먼저 실행하기
새 실습 폴더에서 아래 내용을 greet.mjs에 저장합니다. 문법과 실행 환경이 정상인데도 원하는 새 동작이 없는 상태를 재현하는 것이 목적입니다. 기존 프로젝트를 덮어쓰는 예제가 아닙니다.
greet.mjs · 수정 전 구현
export function greet(name) {
return `Hello, ${name}!`;
}
바뀌지 않을 검증 기준 만들기
다음 내용을 같은 폴더의 greet.test.mjs에 저장하고 node --test greet.test.mjs로 실행합니다. 별도 npm 의존성은 필요 없습니다. 첫 테스트는 기존 동작을 지키고, 나머지 두 테스트가 새 요구를 구분합니다.
수정 전에는 정상 이름 테스트만 통과하고 나머지는 ERR_ASSERTION으로 실패합니다. 파일을 못 찾거나 import가 깨져 실패했다면 동작 검증이 시작되지 않은 것입니다. 그 오류를 이 사례의 RED로 계산하지 않습니다.
greet.test.mjs · 두 구현에 동일하게 실행하는 테스트
import test from "node:test";
import assert from "node:assert/strict";
import {greet} from "./greet.mjs";
test("preserves a normal name", () => {
assert.equal(greet("Ada"), "Hello, Ada!");
});
test("trims surrounding whitespace", () => {
assert.equal(greet(" Ada "), "Hello, Ada!");
});
test("uses World for an empty name", () => {
assert.equal(greet(""), "Hello, World!");
});
계약을 만족하는 최소 변경
입력 문자열을 trim한 결과를 한 번 저장하고, 그 결과가 비었을 때만 World를 사용합니다. 입력 변수를 바꾸거나 불필요한 외부 라이브러리를 추가하지 않습니다. greet.mjs만 아래 구현으로 바꾸고 같은 테스트 명령을 다시 실행합니다.
greet.mjs · 수정 후 구현
export function greet(name) {
const normalized = name.trim();
return `Hello, ${normalized || "World"}!`;
}
무엇이 실제로 달라졌나?
이 글의 회귀 시험은 위 코드와 테스트를 그대로 임시 폴더에서 실행합니다. 아래 수치는 해당 세 테스트의 결과이며 성능 향상률이나 모든 입력에 대한 정확도는 아닙니다. 첫 테스트가 계속 통과해야 기존 계약을 지켰다는 근거가 됩니다.
| 구현 | 통과 | assertion 실패 | 명령 종료 코드 |
|---|---|---|---|
| 수정 전 | 1 / 3 | 2 / 3 | 1 |
| 수정 후 | 3 / 3 | 0 / 3 | 0 |
Holmes-Kit에서는 어디에 연결할까?
요구에는 유지할 동작과 새 성공 조건을, 설계에는 문자열만 받는 범위와 trim·기본값 결정을 남깁니다. 승인된 설계 아래 테스트를 작성하고 assertion RED를 확인한 뒤 대응 테스트 명세 승인과 구현·GREEN으로 이어갑니다. 실제 명세 ID와 도구의 다음 단계 안내를 사용하세요.
명세 링크는 판단을 찾는 수단입니다. 링크만으로 테스트 통과나 현재 CLI의 훅 작동이 입증되지는 않습니다. 실제 설치와 첫 변경을 따라 하려면 기본편에서 시작하고, 이 글의 단위 실행 결과를 네이티브 연결 증거로 사용하지 마세요.
내 변경에 적용할 체크리스트
지금 예제는 실패를 구분하기 위한 작은 실험입니다. 탭·공백만 있는 이름, 비문자열 입력, 유니코드 표기, 길이 제한은 별도 요구와 테스트가 필요합니다. 작은 GREEN을 제품 전체 검증으로 확대 해석하지 않습니다.
- 유지할 기존 동작을 테스트로 남겼는가?
- 새 입력과 기대 응답을 구체적으로 적었는가?
- 수집 오류가 아닌 실제 assertion 실패를 봤는가?
- 같은 테스트를 수정 후 다시 실행했는가?
- 설치·MCP 연결·훅 관측을 별도로 확인했는가?
출처와 검증
기존 소개글을 사례형으로 확장한 버전입니다. 위 검증 근거와 출처의 버전이 이 글의 확인 범위를 정합니다.
이 자료 공유하기
링크나 소개문을 복사하세요. 외부 서비스에 자동 게시하지 않습니다.
https://holmes-lab.web.app/ko/notes/spec-first-ai-development/
외부 게시용 소개문 초안
AI가 코드를 바꾸기 전에 무엇을 확인해야 할까? 이름 하나를 받는 함수에 공백 처리와 기본값을 더합니다. 같은 세 테스트의 실패와 통과를 따라가며 요구, 설계 판단, 실행 근거를 연결합니다. https://holmes-lab.web.app/ko/notes/spec-first-ai-development/