2편에서 목표와 증거를 작은 컨텍스트 패킷으로 정리했다. 그런데 컨텍스트가 좋아도 도구를 아무 순서로나 쓰면 결과가 흔들렸다. 검색 결과가 많다는 이유로 첫 파일을 원인으로 지목하거나, 빌드 명령이 성공했다는 이유로 실제 화면도 정상이라고 판단하는 일이 생겼다.
AI에게 도구는 손과 눈에 가깝다. 문제는 도구를 호출할 수 있다는 사실과 올바르게 사용한다는 사실이 다르다는 점이다. 그래서 각 도구에 무엇을 넣고, 무엇을 증거로 받고, 그 결과로 어디까지 말할 수 있는지를 정했다.
검색 도구의 계약
검색은 빠르지만 가장 쉽게 범위가 커지는 도구였다. 처음에는 오류 문구 하나로 전체 작업 폴더를 검색했다. 결과가 수백 개 나오면 비슷한 이름의 오래된 구현이 현재 경로처럼 보이기도 했다.
이후 검색 순서를 좁혔다.
1. 사용자가 본 화면 또는 API 경로
2. 그 경로를 등록하는 라우터와 진입 컴포넌트
3. 실제로 호출되는 서비스와 설정
4. 관련 커밋과 변경 이유
5. 공통 모듈과 다른 저장소의 영향
명령도 가능한 한 구체적으로 만들었다.
rg -n "redirectToLogin|sessionExpired" src
git log --oneline -- src/path/to/example.cs
git show --stat <example-commit>
검색 결과의 계약은 “문자열이 존재한다”까지다. 그 코드가 현재 실행된다는 결론은 호출 관계나 런타임 증거가 추가로 있어야 한다. 이 한계를 적어 두니 검색 결과 하나로 원인을 확정하는 일이 줄었다.
Git 도구의 계약
Git은 단순히 변경 파일을 보는 도구가 아니었다. 현재 코드가 왜 이런 구조가 됐는지를 찾는 기록이자, AI가 건드려도 되는 범위를 확인하는 안전장치였다.
git status --short --branch
git diff -- path/to/example
git log --follow --oneline -- path/to/example
git blame -L 40,80 path/to/example
각 명령의 질문을 분리했다.
| 명령 | 답하려는 질문 |
|---|---|
git status |
현재 작업에 섞이면 안 되는 변경이 있는가 |
git diff |
이번 작업이 실제로 무엇을 바꿨는가 |
git log |
비슷한 문제를 언제 어떤 이유로 고쳤는가 |
git blame |
현재 줄이 들어온 변경을 어디서 추적할 것인가 |
커밋 메시지가 항상 정확한 것은 아니기 때문에 Git 기록만으로 현재 동작을 확정하지 않았다. Git은 좋은 가설을 만드는 증거이고, 최종 기준은 현재 코드와 실행 결과였다.
빌드 도구의 계약
빌드는 강한 증거처럼 보이지만 실제로 보장하는 범위는 제한적이다. 컴파일 성공은 문법과 의존성 일부가 맞다는 뜻이지, 사용자 흐름이 정상이라는 뜻은 아니다.
내가 구분한 단계는 아래와 같다.
코드 검사 성공
≠ 테스트 성공
≠ 빌드 성공
≠ 배포 파일 반영
≠ 실제 서버 적용
≠ 사용자 화면 정상
예를 들어 프런트엔드 번들이 정상 생성돼도 서버가 이전 파일을 제공할 수 있다. 서버가 새 번들을 제공해도 브라우저 캐시 때문에 이전 화면이 보일 수 있다. 따라서 빌드 도구의 출력은 다음 검증으로 이동할 근거이지, 작업 전체의 종료 조건은 아니었다.
브라우저와 로그 도구의 계약
브라우저는 사용자가 보는 결과에 가장 가깝지만, 화면만 보면 내부 원인을 알기 어렵다. 로그는 내부 흐름을 보여 주지만, 오래된 파일이나 다른 서버의 로그라면 현재 요청의 증거가 아니다.
그래서 두 도구를 연결했다.
브라우저 요청 시각과 요청 ID 확보
-> 접근 로그에서 도착 확인
-> 애플리케이션 로그에서 처리 확인
-> 필요하면 외부 연동 로그 확인
-> 화면 응답과 비교
로그를 보기 전에는 파일의 수정 시각과 프로세스가 실제로 쓰는 경로부터 확인했다. “해당 문자열이 없다”는 결과는 활성 로그라는 사실이 확인된 뒤에야 의미가 있었다.
도구 결과를 표준화한 이유
도구마다 출력 형식이 다르면 AI가 중요한 내용을 놓치기 쉽다. 그래서 결과를 아래 형태로 요약했다.
tool: git-diff
target: client-app/path/to/example.cs
observed_at: 2026-04-19T11:20:00+09:00
result: success
evidence:
- 변경 파일 1개
- 상태 초기화 호출 순서 변경
claim_limit:
- 로컬 파일 변경만 확인
- 빌드와 실제 화면은 미확인
claim_limit가 의외로 중요했다. 도구가 성공한 뒤 말할 수 없는 범위를 함께 남기면, 다음 단계에서 과장된 완료 보고가 줄어든다.
도구가 많아질수록 필요한 단순함
하네스에 도구를 계속 추가하는 건 어렵지 않다. 어려운 건 어떤 상황에서 어떤 도구를 쓰지 않을지 정하는 일이다. 코드 검색만 필요한데 브라우저를 열거나, 현재 파일만 보면 되는데 전체 저장소 이력을 훑으면 맥락만 늘어난다.
내 기준은 간단해졌다.
도구는 답을 만드는 장치가 아니라, 한 단계의 주장을 증명하는 장치다.
검색은 위치를, Git은 변경 범위를, 빌드는 산출물을, 브라우저는 사용자 결과를 증명한다. 각 도구의 계약을 분리하자 AI의 답변도 “무엇을 확인했고 무엇은 아직 모르는지”가 보이기 시작했다.
이전 글: Codex AI 하네스 엔지니어링 설계 2 — 컨텍스트 구조