스크립트로 복잡한 CLI 도구를 실행하고, JSON 보고서로 성공을 확인한다

## CLI의 성공 여부를 진행 문구가 아닌 구조화된 데이터로 판단한다 스크립트, 처리 파이프라인 또는 코딩 에이전트가 복잡한 명령줄 도구를 제어할 때는 CLI를 대화형 셸이 아니라 버전이 관리되는 기계용 인터페이스로 취급한다. 계획, 실행, 검증을 분리하여 각 단계가 구조화된 데이터를 사용하고 다음 단계에서 검증할 수 있는 증거를 생성하도록 한다. - 사람이 읽는 진행 텍스트를 분석하여 실행 성공 여부를 판단해서는 안 된다. - 지원되는 작업, 출력 클래스 또는 라이선스 요건을 기억에 의존해 추론해서는 안 된다. - 도구 버전, 해석된 실행 환경 설정, 요청 범위 및 생성된 산출물을 기록한다. - 필수 구조화 증거가 없거나 서로 일치하지 않으면 안전하게 실패한 것으로 처리한다. ## 실행 전에 도구의 작업과 클래스 목록을 확인한다 비용이 큰 작업을 구성하기 전에 도구의 경량 정보 명령이나 레지스트리 명령을 사용한다. 기본 CLI를 검증하는 것과 동일한 레지스트리에서 생성된 JSON 보기를 우선한다. 소스에서 복사한 목록이나 하드코딩한 이름은 설치된 버전과 달라질 수 있기 때문이다. 기능 확인 결과에는 다음이 포함되어야 한다. - 사용 가능한 작업과 각 작업의 입력 형식 - 각 작업에 라이선스 또는 사용 권한이 필요한지 여부 - 클래스 필터가 허용하는 정확한 인덱스와 클래스 이름의 대응 관계 - 설치된 도구 버전과 작업별 제약 무거운 추론 의존성을 불러오지 않고, 가속기를 초기화하지 않으며, 모델 가중치를 내려받지 않고, 로컬 상태도 변경하지 않는 확인 경로를 우선한다. 전체 레지스트리가 필요하지 않다면 조회 범위를 하나의 작업 또는 클래스 보기로 제한한다. ## 입력·출력·설정을 모두 적어 같은 실행을 반복할 수 있게 한다 각 실행은 입력, 출력, 작업, 장치 정책, 선택적 클래스 부분집합, 출력 표현 방식 및 보고서 경로를 명시하여 구성한다. 볼륨 파일, 순서가 있는 슬라이스 디렉터리 또는 슬라이스 압축 파일처럼 문서화된 입력 형식만 허용하고, 선택한 출력 방식에 맞는 대상 위치인지 검증한다. 실행 전에 다음을 확인한다. 1. 요청한 작업과 클래스가 현재 기능 레지스트리에 존재한다. 2. 입력 형식이 지원되며 출력 경로의 의미가 명확하다. 3. 사용이 제한된 작업을 시작하기 전에 라이선스 문제를 해결한다. 4. 장치와 성능 모드를 의도적으로 선택한다. 5. 기계 판독 가능한 실행 보고서를 위한 고유 경로를 확보한다. 오래된 산출물을 현재 결과로 오인할 수 있다면 기존 출력 디렉터리를 재사용해서는 안 된다. 해석된 명령 매개변수를 실행 증거와 함께 보관한다. ## 장치와 고속 모드를 고르고, 라이선스가 필요한 작업은 먼저 확인한다 장치 선택과 속도 옵션을 재현성 계약의 일부로 취급한다. 요청한 장치뿐 아니라 실제로 선택된 장치를 기록한다. 가속 기능을 사용할 수 없으면 CPU로 대체되어 실행 시간이 크게 달라질 수 있기 때문이다. 자원이 제한된 경우에는 문서화된 제어 옵션으로 비용을 낮춘다. - 정확도 저하를 허용할 수 있을 때만 저해상도 고속 모드를 사용한다. - 후속 작업에 필요한 클래스만 요청한다. - 장치가 여러 개라면 특정 가속기 인덱스를 사용한다. - 필요한 경우 지원되는 플랫폼 백엔드를 명시적으로 선택한다. 출력 품질이나 범위를 바꾸는 더 빠르거나 더 좁은 모드로 절대 몰래 대체해서는 안 된다. 라이선스가 필요한 작업은 유효한 권한이 이미 설정되어 있지 않다면 추론을 시작하기 전에 중단한다. ## JSON 보고서와 거기 적힌 모든 파일을 확인한다 정상적으로 완료된 뒤 CLI가 구조화된 보고서를 작성하도록 요구한다. 이 보고서는 자동화에 전달하는 공식 산출물이며 다음을 포함해야 한다. - 도구, 실행 환경, 프레임워크 및 의존성 버전 - 작업, 입력 형식 및 라이선스 요건 - 실제로 선택된 장치와 성능 플래그 - 정규화된 입력 및 출력 위치 - 요청한 클래스 부분집합과 최종 인덱스 및 클래스 이름의 대응 관계 - 실제 경과 시간과 생성된 출력 파일의 정확한 목록 보고서가 존재하고 JSON으로 해석되며, 예상한 작업을 식별하고 다음 단계에 필요한 모든 산출물을 나열하는지 확인한다. 그다음 나열된 각 파일이 실제로 존재하는지 확인한다. 클래스별 부피, 강도, 복셀 수, 분산, 극값, 중심점 또는 경계 상자에는 전용 통계 출력을 사용하며 파일 이름이나 진행 텍스트에서 값을 추론해서는 안 된다. ## 종료 코드로 실패를 나누고, 새 저장 위치에서 다시 시도한다 선택적 산출물을 읽기 전에 프로세스 종료 상태를 해석한다. 정상 완료, 실행 중 실패, 인수 또는 사용법 오류를 구분하여 재시도 시 잘못된 명령을 반복하지 않도록 한다. - 성공한 경우 보고서와 보고서에 선언된 출력 파일을 검증한다. - 실행 중 실패한 경우 진단용 표준 오류를 보관하고 권한 누락, 사용 불가능한 자원, 손상된 입력 또는 처리되지 않은 도구 오류 등으로 원인을 분류한다. - 인수 오류인 경우 재시도하기 전에 작업, 입력, 출력 또는 옵션 구성을 바로잡는다. - 일반적인 잡음을 줄일 때는 조용한 모드를 사용하고, 추가 진단 정보가 필요할 때만 디버그 모드를 사용한다. 일부 파일, 진행 메시지 또는 빈 출력 디렉터리를 성공으로 간주해서는 안 된다. 재시도는 새 대상 또는 정리된 대상을 사용하여 실패한 시도의 산출물이 이번 검증을 통과하지 못하도록 해야 한다. ## 공개 API로 호출하고, 보고서의 파일 목록으로 다음 처리를 잇는다 프로세스 내부 실행이 필요하면 지원되는 상위 수준 프로그래밍 API를 사용하되, CLI 작업 흐름과 동일하게 작업, 입력, 출력 및 검증 계약을 명시한다. 계획과 검증에는 전체 추론 실행 환경을 가져오지 않고도 작업과 클래스를 나열할 수 있는 경량 레지스트리 모듈을 우선한다. 오케스트레이션을 구현 세부 사항과 분리한다. 공식 레지스트리에서 기능을 확인하고, 문서화된 CLI 또는 API로 실행하며, 구조화된 보고서의 출력 목록을 기준으로 후속 처리를 연결한다. 이렇게 하면 취약한 표준 출력 분석과 기능표 중복을 피하면서 버전이 바뀐 뒤에도 자동화를 유지할 수 있다.