요청을 실행 가능한 판정으로 바꾼다
“로봇 로그 변환을 고쳐 줘”라는 요청만으로는 어디까지 바꿔도 되는지, 어떤 결과가 맞는지 알 수 없다. 개발자나 AI 도구가 많은 파일을 만들었다는 사실도 그 질문의 답이 되지 않는다. 작업 명세는 작업자가 무엇을 입력받아 어디까지 바꾸고 어떤 근거를 제출해야 하는지 합의한 기록이다. 완료 기준은 그 근거를 보고 통과/실패/미확인을 결정하는 조건이다. 도구가 자신 있게 설명한 문장과 별도로 적는다.
일반 코딩을 할 수 있어도 AI/로봇 작업은 코드 밖의 조건에서 자주 어긋난다. 같은 숫자 250도 mm인지 m인지에 따라 다르고, 같은 배열도 축·좌표·시간의 계약이 다르면 다른 입력이다. 실험에 쓰는 소스·패키지·설정·데이터의 식별자와 허용 변경 범위를 함께 고정해야 결과의 원인을 좁힐 수 있다. M01.05에서 익힌 환경 기록이 여기서는 작은 작업의 시작 조건이 된다.
작업 범위는 작아도 목표는 관찰 가능해야 한다. “정확도를 높인다”보다 “제공된 거리 행을 mm에서 m로 바꾸되 행 ID와 원본을 보존하고, 거부 행의 이유를 남긴다”가 검사 가능하다. 모델 학습·실물 연결·배포처럼 이번에 하지 않는 일도 비목표로 적는다. 비목표는 나중에 할 수 없다는 뜻이 아니라 이번 결과로 증명하지 않는 범위다.
작은 명세의 다섯 칸
다음은 실제 저장소가 아니라 교육용 합성 작업이다. RevA, LockA, DataA 같은 표시는 실제 버전이나 해시가 아니다. 소스 함수의 거리 변환이 잘못되었지만 언어 문법은 이미 작성되어 있다고 가정한다.
| 칸 | 이번 작업의 합의 |
|---|---|
| 목적·입력 | DataA의 행 ID와 distance_mm을 읽어 거리 m와 거부 이유를 만든다. distance_mm은 유한한 수이며 0 이상인 거리로 정의한다. |
| 실행 환경 | 소스 RevA, 수정 전 작업 트리, 패키지 LockA, 설정 ConfigA, 입력 DataA를 기록한다. 실제 프로젝트에서는 실행 인터프리터·작업 디렉터리·명령·빌드 공간도 남긴다. |
| 변경 범위 | 거리 변환 함수 한 곳만 수정한다. 입력·기대값·판정 오차·장치 설정은 바꾸지 않는다. 더 넓은 수정이 필요하면 먼저 근거와 명세 변경을 검토한다. |
| 산출물 | 소스 차이, 사용한 입력/설정 식별자, 결과표, 실행/검증 기록, 미확인 항목을 제출한다. “완료” 한 문장은 산출물을 대신하지 않는다. |
| 완료·비목표 | 아래 정상/경계/실패 판정 모두 충족, 원본 불변. ROS·추론·GPU·실물·제어 주기 성능은 이번 검증 대상이 아니다. |
거리 계약에서 0은 정상 경계다. 반면 음수는 이 자료에서 금지한 거리 값이라 거부한다. 이 규칙을 모든 로봇 좌표에 확대하면 안 된다. 기준 원점 반대편의 위치나 부호 있는 속도는 음수일 수 있으므로 다른 자료의 계약을 다시 읽어야 한다. 텍스트나 누락을 임의로 0으로 바꾸면 측정 실패와 실제 거리 0을 구분할 수 없게 된다.
완료 기준을 먼저 고정한다
제공 입력은 다음 네 행 전부다. 행의 순서와 ID는 유지한다. 결과가 숫자인 정상 행만 변환하고, 실패 행은 삭제하지 않고 행 ID와 거부 이유를 결과에 남긴다.
| 행 ID | distance_mm | 기대 결과 | 판정의 역할 |
|---|---|---|---|
| r1 | 250 | 0.250 m | 정상 변환, 250÷1000 |
| r2 | 0 | 0 m | 허용 경계 |
| r3 | -2 | 거리 범위 오류로 거부 | 금지한 음수 거리 |
| r4 | "offline" | 숫자 형식 오류로 거부 | 측정 실패를 0으로 숨기지 않음 |
숫자 결과는 절대 오차 0.000001 m 이하를 허용한다. r1이 0.2500004 m이면 오차 0.0000004 m로 수치 조건을 통과한다. 0.250002 m이면 오차 0.000002 m로 실패한다. 이 허용오차는 자료 변환 예제의 합성 기준이며 실제 로봇의 위치 정확도 규격이 아니다. 숫자 조건 외에도 정상 2행·거부 2행, 각 ID와 이유의 대응, 원본 DataA 불변을 모두 요구한다. 수치 하나가 맞아도 거부 행을 없애면 완료가 아니다.
기대값이나 오차 기준을 결과를 본 뒤 느슨하게 바꾸면 개선과 기준 변경을 구분할 수 없다. 기준이 잘못되었다는 새 근거를 찾았다면 그 문제를 따로 기록하고 원래/수정 기준과 영향을 검토한다. 실패를 없애려고 기준 파일만 바꾼 결과를 원래 작업 통과로 보고하지 않는다.
작은 변경 루프는 근거를 좁히는 방법이다
먼저 고정 입력에서 현재 실패를 확인한다. 합성 기록의 기존 r1 출력이 2.5 m라면 0.250 m 기준과 어긋난다. 단위 변환식을 살펴볼 가설은 생기지만 이 숫자 하나만으로 모든 구현 원인을 단정하지 않는다. 실제 코드와 경로를 확인해 수정 대상을 좁힌다.
다음으로 한 논리적 변경을 적용하고 차이를 검토한다. Git diff 공식 문서는 작업 트리·인덱스·커밋 사이의 비교 대상을 구분한다. 여기서 중요한 것은 명령 암기가 아니라 무엇과 무엇을 비교했는가다. 소스 한 함수 수정이 허용 범위였는데 입력 파일·기대값·장치 설정도 바뀌었다면 결과가 좋아진 원인을 바로 승인할 수 없다. Git status 공식 문서의 수정/미추적 상태도 함께 확인해 diff에 보이지 않은 새 입력이나 설정을 놓치지 않는다.
변경 뒤에는 수정과 관련된 판정을 다시 확인한다. 새 r1 출력만 보고 끝내지 말고 r2 경계와 r3/r4 거부 동작이 유지되는지 확인한다. 이렇게 변경 때문에 깨질 수 있는 기존 동작을 다시 확인하는 것이 회귀 확인이다. 이미 수행한 관련 검증이 통과했고 추가 변경·실패가 없다면 의미 없이 같은 검사를 반복하기보다 판정과 미확인 범위를 기록한다.
변경을 작게 나누는 것은 무조건 한 줄만 바꾸라는 뜻이 아니다. 한 계약을 일관되게 고치기 위해 여러 파일이 필요할 수 있다. 그때는 함께 바뀌어야 하는 이유·검증 범위를 설명한다. 반대로 변환 수정에 모델 교체·GUI 개편·장치 보정까지 섞으면 어떤 변화가 결과를 만들었는지 검토하기 어려워진다. 이번 명세의 범위를 넘는 요구는 다음 작업으로 분리한다.
빌드 성공·선택된 검사·완료는 서로 다르다
컴파일이나 빌드가 성공했다는 기록은 실행 산출물을 만들었다는 근거다. 입력의 단위와 거부 규칙까지 맞았다는 근거는 아니다. CMake 3.28 CTest 문서는 프로젝트에 등록한 테스트를 실행하고 결과를 보고하는 도구를 설명한다. 선택 조건으로 실제 실행한 테스트가 무엇인지와 개수, 실패/건너뜀을 읽어야 한다. “테스트 성공”이라는 요약만으로 요구한 네 사례를 모두 수행했다고 추론하지 않는다.
이 단원에서는 다음 기록을 읽는다. 모든 값과 실행 기록은 교육용이며 실제 CTest나 로봇 실행 결과가 아니다.
| 제출안 | 변경·입력 | 제출된 검증 | 판정 |
|---|---|---|---|
| A | 허용 함수만 수정, DataA/ConfigA 유지 | 새 소스 산출물로 r1~r4 실행; 0.250/0/범위 거부/형식 거부, 원본 불변 | 이번 자료 계약의 통과 근거가 됨 |
| B | 함수 외에 입력을 DataB로 바꾸고 기대값 파일도 수정 | 변경된 입력·기준에서 4건 성공 | 원래 DataA/기준 통과를 입증하지 못함 |
| C | 허용 함수만 수정, DataA 유지 | 빌드 성공, 테스트 선택 결과 0건 | 네 사례 미실행이므로 미확인; 완료 아님 |
A도 실물 장치에서 지연이 짧거나 안전하다는 근거는 아니다. 제출한 소스/입력/설정·검증 범위 안에서만 통과를 말한다. 같은 파일 이름의 오래된 산출물을 실행했다면 새 변경을 검증한 것인지 추가 확인해야 한다. 테스트의 입력 식별자와 실제 실행 경로, 기록한 산출물 식별자를 이어 보는 이유다.
마지막 기록은 “A의 네 사례와 원본 불변을 확인해 이번 변환 계약을 통과했다. 장치/GPU 성능은 미확인이다. 다음 작업은 새 자료 형식 지원 여부의 명세다”처럼 쓴다. 사람이나 도구가 제안한 변경, 실행 관찰, 해석, 완료 판단을 각각 구분하면 다음 작업자가 근거를 이어 받을 수 있다. 다음 M31.02에서는 이 명세를 AI 코딩 도구에 줄 때 사람 검토와 실행 권한의 경계를 다룬다. 기존 M01.05 재현 환경은 시작 조건, 기존 응용 교재의 5.12 재현성 체크리스트와 6.8 포트폴리오 패키징은 나중에 학습/배포로 확장하는 예다. 지금 전체 응용 장을 먼저 이수할 필요는 없다.