실제 명령과 플래그로 AI 에이전트용 명령 스키마 생성하기

## 생성된 파일이 아니라 레지스트리와 생성기를 고치기 저장소 지침을 적용 범위에 속한 파일의 계약으로 취급한다. 관련 없는 작업을 보존하고, 수정한 모든 소스 파일에 해당 언어의 포맷터를 적용하며, 요청된 동작에 필요한 최소한의 소유 입력만 변경한다. 편집하기 전에 권위 있는 입력을 식별한다. 검토된 명령 레지스트리는 안정적인 명령 식별 정보, 기본 경로, 별칭, 탐색을 소유해야 한다. 실행 가능한 명령 트리는 경로의 존재 여부, 실행 가능 여부, 허용하는 플래그를 소유해야 한다. 생성된 카탈로그와 에이전트 메타데이터는 출력이며 편집 표면이 아니다. 해당 소스 입력과 생성기를 변경한 다음 다시 생성한다. 변경 사항을 다루는 저장소 지정 빌드, 전체 테스트, 생성, 드리프트 검사, 정책 검사, 범위를 좁힌 명령 테스트를 실행한다. 생성된 차이를 검토하고 관련 없는 재작성을 거부한다. ## 스키마를 한 방향으로 만들고 각 명령을 한 번만 바인딩하기 스키마 해결 방향을 한쪽으로 유지한다. 1. 실제로 실행 가능한 명령 트리와 플래그를 구축한다. 2. 바인딩 전에 검토된 식별 정보 레지스트리와 검토된 메타데이터 오버레이를 결합한다. 3. 매개변수 타입, 매핑, 필수 상태, 기본값, 매개변수 간 제약을 해결한다. 4. 선언된 소스 우선순위에 따라 에이전트 선택, 안전, 인터페이스, 런타임 게이트의 의미를 해결한다. 5. 각 명령을 정확히 한 번만 하나의 타입 기반 도구 사양과 인덱스에 바인딩한다. 6. 해당 타입 기반 정본에서만 카탈로그, 전체 내보내기, 요약, 생성 메타데이터를 게시한다. 바인딩 후 식별 정보를 복구하거나 다시 해결하려고 주석, 소스 레코드, 이전 카탈로그, 생성된 JSON을 다시 열어서는 안 된다. 내장 스냅샷을 디코딩하는 프로덕션 로더는 전달 경계이며 두 번째 소스 해결 단계가 아니다. 이 로더는 명령, 플래그, 레지스트리 항목, 이후의 생성 입력을 만들거나 복구해서는 절대 안 된다. 버전이 지정된 변경이 명시적으로 승인되지 않는 한 게시된 전송 계약을 유지한다. 다른 시스템과 아키텍처를 맞추는 것은 버전 없는 형식 변경을 정당화하지 않는다. ## 모든 명령과 스키마가 양방향으로 맞는지 확인하기 바인더는 없거나 실행할 수 없는 명령 경로, 별칭 충돌, 유효 레지스트리와 일치하지 않는 네이티브 식별 정보 표명을 거부해야 한다. 주석이 대체 식별 정보 소스가 아니라 일관성 검사인 경우에는 네이티브 식별 정보 표명이 없어도 허용할 수 있다. 양방향으로 범위를 강제한다. 1. 카탈로그 투영을 포함해 전달되는 모든 스키마 도구는 실행 가능한 명령으로 해결되어야 한다. 2. 공개된 모든 실행 가능 명령 리프는 스키마로 해결되거나, 비어 있지 않은 이유가 있는 정확한 검토 대상 제외 항목에 포함되어야 한다. 향후 명령을 숨길 수 있으므로 접두사나 와일드카드 제외를 절대 사용하지 않는다. 오래되었거나 유효하지 않거나 중복된 제외 항목이 있으면 생성에 실패해야 하며, 해당 명령이 스키마에 들어오면 제외 항목의 사용을 중단해야 한다. 검토된 레지스트리를 안정적인 식별 정보와 탐색의 유일한 정본으로 취급하고, 실행 가능한 트리를 경로, 실행 가능성, 플래그 사실의 정본으로 취급한다. 명령 트리가 변경될 때마다 역방향 완전성 테스트를 실행한다. ## 안전 메타데이터와 에이전트 선택 설명을 따로 작성하기 사람이 작성하는 입력을 소유 책임에 따라 분리한다. 메타데이터는 영향, 위험, 확인, 멱등성, 인터페이스, 런타임 게이트, 선택적 매개변수 오버레이를 소유한다. 선택 정보는 에이전트 요약, 긍정 및 부정 라우팅 지침, 예제, 제품 라우팅을 소유한다. 인덱스는 제품 식별자를 해당 파일에 매핑하는 역할만 해야 한다. 이 블록들 사이에 필드를 섞지 않는다. 사람이 작성한 모든 항목은 명시적으로 검토되어야 하고, 구체적인 검토 이유와 증거 참조를 포함해야 하며, 사용자에게 보이는 동작을 표현하는 최소 항목이어야 한다. 선택 문구는 명령 요약을 반복하지 말고, 발동 의도, 관련 명령 간 라우팅, 예상 결과를 설명해야 한다. 선언된 우선순위에 따라 증거를 해결한다. 먼저 실행 가능한 런타임 사실, 그다음 가동 중인 인터페이스 스키마, 고정된 인터페이스 메타데이터, 마지막으로 증거로만 사용하는 스킬 문서를 적용한다. 가동 중인 탐색에서 개인용 자격 증명을 사용하는 경우 접근 자격 증명을 표시하거나 커밋해서는 절대 안 된다. 가동 중인 탐색이 실패하면 실패를 기록하고, 승인된 대체 증거를 사용하며, 인터페이스나 원격 프로시저를 꾸며내지 않는다. 매개변수 오버레이는 공개된 정확한 실행 가능 리프와 실제 플래그를 대상으로 해야 한다. 설명, 인터페이스 매핑, 필수 상태, 조건부 요구 사항을 조정할 수 있지만, 명령이나 플래그를 만들거나, 인터페이스를 정의하거나, 알 수 없는 원격 프로시저를 알리면 안 된다. ## 모든 출력을 처음부터 다시 만들고 서로 같은지 확인하기 생성을 이전 카탈로그에 대한 증분 패치가 아니라 완전하고 결정론적인 스냅샷 재구축으로 취급한다. 검토된 모든 입력을 다시 읽고, 오래된 생성 제품 메타데이터의 사용을 중단하며, 정확한 출력 투영을 다시 작성한다. 생성 파일을 병합 입력으로 사용해서는 절대 안 되며, 생성 과정이 사람이 작성한 입력이나 검토된 레지스트리를 변경하면 바이트 가드가 실패해야 한다. 모든 투영에 해결된 동일한 타입 기반 도구 사양을 사용한다. 리프 페이로드는 전체 내보내기와 카탈로그의 해당 항목과 같아야 하고, 개요와 그룹 요약은 같은 도구의 요약 투영과 같아야 한다. 별칭 조회는 별칭별 보기 필드만 변경할 수 있으며, 명령 계약을 다시 해결하거나 변경해서는 안 된다. 전달되는 모든 도구와 매개변수 필드에서 선택된 출처 값은 전달된 값과 정확히 같아야 한다. 소스 이름, 후보 수, 필드 존재 여부, 해시만 확인해서는 충분하지 않다. 생성, 런타임 확인 정보의 사실성 검사, 역방향 완전성 테스트, 범위를 좁힌 명령 테스트, 최종 내장 로더 검사를 실행한다. 스냅샷을 받아들이기 전에 그 결과로 생긴 모든 차이를 검토한다. ## 건너뛰기나 --yes 없이 예제와 시험 실행 검증하기 검토된 예제는 도구당 최대 2개만 저장한다. 예제는 실제 기본 경로나 별칭, 허용되는 플래그, 필수 위치 인수, 유효한 모든 `require-one-of`, `require-together`, `mutual-exclusion` 제약을 사용해야 한다. 셸 주석이나 `--yes` 같은 확인 우회 플래그를 포함하지 않는다. 모든 예제는 바인딩된 명령에 대한 계약 검증을 통과해야 한다. 필수 값 누락, 제약 실패, 런타임 오류, 인터페이스 해결 오류는 계약 결함이며 예제를 건너뛸 이유가 아니다. 런타임 예제 실행은 명시적 선택 참여 방식이며, 최종 타입 기반 도구가 명시적인 검토 완료 시험 실행 기능을 게시한 경우에만 허용된다. 위험 및 확인 메타데이터로 미리보기 지원을 만들어내서는 안 된다. 검토된 수동 판정은 기존 시험 실행 기능을 0부터 시작하는 정확한 예제 인덱스 1개로 좁힐 수 있지만, 승인된 이유 코드와 구체적인 이유를 사용해야 하며 일반 계약 검증을 건너뛰기로 바꾸면 절대 안 된다. 시험 실행 실패를 포착한 뒤 계약 검증만 수행하도록 동적으로 낮추면 안 된다. 기본적으로 포괄적인 계약 게이트를 실행한다. 실제 명령에서는 사용자 상태를 격리하고 프록시를 차단한 상태로 적합한 시험 실행 하위 집합만 실행한다. 안정적인 실행 개수의 변경은 검토가 필요한 계약 변경으로 취급한다. ## 정답을 보내지 않고 AI가 고르는 명령 테스트하기 모든 긍정 선택 시나리오는 검토된 명령이 선택되어야 한다는 표명으로 취급하고, 모든 부정 시나리오는 해당 명령이 선택되어서는 안 된다는 표명으로 취급한다. 사람이 작성한 선택 필드에서 결정론적 타입 기반 테스트 픽스처를 도출하고, 정확한 도구 범위와 실행 가능한 기본 명령을 요구하며, 누락되거나 중복되거나 모순된 기대값을 거부한다. 문자열 일치만으로는 의미 이해를 증명할 수 없다. 가동 중인 모델을 사용하는 선택 검사는 명시적 선택 참여 방식으로 유지한다. 소규모 스모크 세트, 검토된 전체 세트, 정확한 사례 목록을 지원한다. 평가기에는 사례 식별자, 시나리오 본문, 동일 제품의 후보 표만 보내고, 기대 표명과 금지 표명은 로컬에 유지한다. 내장 HTTPS 평가 엔드포인트를 허용 목록에 넣는다. 다른 HTTPS 제공자를 사용하려면 정확한 기본 URL을 승인된 허용 목록에 넣어야 하며, 평문 HTTP는 루프백 테스트 서버에서만 허용된다. 임의의 평문 엔드포인트로 API 자격 증명을 절대 보내지 않는다. 일반적인 지속적 통합은 결정론적으로 유지하며 모델을 호출해서는 안 된다. 재현 가능한 테스트 픽스처, 명령 바인딩, 예제 유효성, 출처 정보, 최종 전달의 동일성을 차단 게이트로 삼는다. ## 안전과 확인 설정을 출처 우선순위로 정하기 안전 및 매개변수 메타데이터는 더 엄격해 보이는 값을 고르는 대신 소스 우선순위에 따라 해결한다. 우선순위가 더 높은 검토된 소스는 영향, 위험, 확인, 멱등성, 설명, 매핑을 의도적으로 높이거나 낮출 수 있다. 모든 후보와 선택된 소스를 보존하고, 같은 우선순위의 충돌은 조용히 병합하지 말고 실패하게 한다. 필수 명령 플래그는 낮출 수 없는 하한선이다. 오버레이는 선택적 플래그를 필수로 만들 수 있지만, 실행 가능 명령이 선언한 요구 사항을 절대 약화해서는 안 된다. 명령 문구에서는 검토된 명령별 힌트, 명령 도움말, 인터페이스 메타데이터 순으로 우선한다. 일반적인 원격 프로시저 문구가 특화된 명령 설명을 덮어써서는 안 된다. 한 안전 필드에서 다른 안전 필드를 추론하지 않는다. 파괴적 영향이나 높은 위험이 확인을 기계적으로 다시 쓰는 것은 아니다. 확인은 명시적 런타임 게이트와 일치해야 하며, 사용자 확인이 필요한 경우 `--yes` 같은 우회 플래그를 추가하기 전에 확인을 받아야 한다. 배포된 명령 도움말과 리프 스키마가 일치하지 않으면 실행 가능 명령이 허용하는 플래그만 전달한다. 안전 소스가 충돌하면 더 안전한 해석을 사용하거나 중단하고 계약 드리프트를 보고한다. 확인의 의미는 생성기의 단위 테스트뿐 아니라 최종 내장 로더와 쿼리 경로를 통해 검증한다. ## 명령을 단계적으로 찾고 데이터는 실제 명령으로 가져오기 일반 탐색은 개요, 제품 또는 그룹, 리프 순으로 단계적으로 진행한다. 전체 내보내기는 안정적인 호환성 계약을 위해 남겨 두고, 플래그가 없는 명령의 빈 매개변수 객체를 포함하여 모든 최종 도구의 완전한 매개변수, 제약, 안전 의미를 담는다. 간소화된 전체 내보내기는 완전한 호환성 기준이 아니다. 명령 도움말은 경로 존재 여부와 실행 프로그램이 허용하는 플래그를 결정한다. 리프 스키마는 에이전트 선택, 매개변수 매핑과 제약, 안전 및 확인의 의미를 결정한다. 불일치는 계약 드리프트이며 추측해도 된다는 뜻이 아니다. 스키마와 도움말은 명령을 설명할 뿐 업무 데이터를 반환하지 않는다. 탐색 후 확인된 권한 안에서 적절한 실제 읽기, 검색, 목록 명령을 실행하여 데이터를 얻는다. 전달 전에 명령 식별 정보가 검토되었는지, 실행 가능 범위가 양방향인지, 제외 항목이 정확한지, 사람이 작성한 블록이 분리된 소유 책임을 유지하는지, 소스 우선순위가 보존되는지, 생성 출력이 출력 전용으로 남아 있는지, 예제가 실제 계약을 통과하는지, 확인이 런타임 게이트와 일치하는지, 모든 투영이 같은 타입 기반 정본과 같은지 확인한다.