이 페이지는 영어 문서의 번역입니다. 명령, 식별자, 예제는 그대로입니다. 런타임 7.24.4 · SDK 2.6.7. 영어 원문

목표 보증

상태: 현재

범위: 목표 수용 검사와 소스 신선도

최종 검토: 2026-09-14

담당: AX Code 런타임 유지관리자

목표 계획자가 만드는 코드 변경 계획은 실행 가능한 수용 검사를 선언합니다. 각 검사는 다루는 결과, 정확한 명령, 목적, 의도한 환경을 이름 짓습니다. 에이전트가 verify_project를 실행하고 그 검사의 goalCheck id를 쓰면 AX Code는 실행 증거를 기록합니다.

{ "goalCheck": "invoice-parity" }

명령은 고정된 목표 계획에서 옵니다. 에이전트는 이 호출로 다른 명령으로 바꿀 수 없습니다. 기존의 bash 권한은 계속 적용됩니다. 목표를 완료하려면 선언된 모든 검사의 최근 시도가, 일치하는 목표, 세션, 작업 공간, 계약, 소스 내용과 함께 통과해야 합니다. 수용 산문은 결과를 설명합니다. 실행된 검사를 대체하지는 않습니다. 보통의 셸 실행과 통째로 건너뛴 검사는 이 증거를 제공할 수 없습니다.

보증이 없는 옛 목표 계획은 이전의 완료 규칙을 유지합니다. 새 계약이 필요하면 옛 목표를 지우고 다시 만듭니다. 고정된 요구 사항을 그 자리에서 고치면 계약 불일치가 납니다. 포크는 계약을 보존하지만 새 세션에서 새로운 검사 실행이 필요합니다.

마이그레이션 프로젝트 준비

리비전 식별자가 있는 권위 있는 레거시 소스나 내보내기, 범위가 제한된 커버리지 목록, 단언을 검증할 수 없을 때 실패하는 검사 스크립트를 제공합니다. 주석과 이전 마이그레이션 구현은 조사할 단서로 다룹니다. 승인된 동작 변경은 레거시 동등 요구와 따로 기록합니다.

요청된 변경이 실제로 영향을 주는 계층의 검사를 고릅니다.

스크립트는 검사를 수행하기 전에 대상 신원을 단언해야 합니다. 자격 증명은 프로젝트의 기존 자격 증명 방식에 두고, 계획 텍스트, 명령, 대상 설명에는 두지 않습니다. 검사는 실패한 단언, 없는 환경, 건너뛴 필수 단언에 대해 0이 아닌 종료 코드를 반환해야 합니다. 실패를 가리는 래퍼는 피합니다. AX Code는 성공한 프로세스 종료만으로 단언을 추론할 수 없습니다.

큰 마이그레이션에서는 작업을 범위가 제한된 업무 흐름 묶음으로 나누고, 양식, 의존성, 레거시 참조, 수용 검사를 잇는 목록을 유지합니다. 수용된 묶음과 남은 커버리지를 모두 보고합니다. 묶음 하나가 통과해도 마이그레이션 전체가 완료되지는 않습니다.

계획이 기록하는 것

계획자는 assurance 객체를 제공합니다. 이 예시 조각은 프로젝트가 참조된 소스 내보내기와 검사 스크립트를 가지고 있다고 가정합니다.

{
  "version": 1,
  "sourcePaths": ["src", "checks", "package.json"],
  "sources": [
    { "role": "legacy", "reference": "legacy/invoice-schema.sql at export-v1" },
    { "role": "requirement", "reference": "Invoice acceptance criteria supplied by the user" }
  ],
  "checks": [
    {
      "id": "invoice-parity",
      "acceptanceIds": ["AC1"],
      "command": "node checks/invoice-parity.cjs",
      "purpose": "Assert invoice behavior, database mappings and target identity",
      "environment": "Staging migration target, schema ERP"
    }
  ]
}

모든 수용 id가 다뤄져야 합니다. 명령은 작업 공간 루트에서 실행됩니다. 보증 객체는 수용 계약과 함께 고정됩니다. 에이전트는 이어지는 목표 맥락에서 검증된 범위, 소스 참조, 검사 id, 선언된 대상을 받습니다. 없거나 바뀐 계약은 복원 알림을 만듭니다. 생성된 대화 요약은 여전히 틀릴 수 있습니다. 선언된 참조와 대상 레이블은 요구 사항이며, 독립적으로 관찰된 사실이 아닙니다.

이 목표가 바꾼 것을 재는 Git 범위는 이전 상태로 {BASELINE}를 써야 합니다. 계획자는 계획이 제출될 때 포착한 HEAD SHA로 그 자리 표시자를 다시 쓰므로, origin/main보다 앞에 있는 기존의 커밋이나 더러운 작업 트리가 목표를 완료 불가로 만들 수 없습니다. 원격 추적 참조(origin/main, @{u}, refs/remotes/…)는 목표 목적이 원격을 이름 짓지 않으면 그 이전 상태로 거부됩니다. 이미 갈라졌거나 더러운 경로는 위험 아래에 기록합니다. 목적이 그 실패를 고치는 것이 아니라면, 이미 실패 중인 관문 검사를 고정하지 않습니다.

신선도와 한계

Git 소스 지문은 선언된 sourcePaths 안에서 추적되는 파일과 무시되지 않은 미추적 파일의 실제 바이트를 포함합니다. 명시적 파일 경로는 무시된 구성 파일도 포함합니다. 디렉터리 경로는 Git 무시 규칙을 유지합니다. 변하는 목표 계획 점검 목록은 제외됩니다. 그 고정된 요구는 계약 다이제스트를 통해 검사됩니다. Git이 아닌 프로젝트는 없는 경로를 포함해 선언된 sourcePaths를 재귀적으로 지문합니다. 관련된 모든 소스, 구성 파일, 검사 스크립트를 그 범위에 넣습니다.

지문은 항목 20,000개와 파일 내용 128 MiB로 제한됩니다. 연결된 소스, 중첩된 Git 저장소, 특수 파일, 벗어나는 경로, 바뀌는 파일, 읽을 수 없는 읽기는 신선한 증거를 만들 수 없습니다. 그런 실패는 보증된 완료를 막습니다. 검사 출력 산출물은 무시되는 위치로 가야 보고서를 만들어도 검증 중인 소스가 바뀌지 않습니다.

명시적으로 이름 짓지 않은 무시 파일, 소스 범위 밖의 의존성, 데이터베이스, 배포는 프로젝트 명령 안의 단언이 필요합니다. 영수증은 실행 시각의 관찰을 기록합니다. 외부 상태가 바뀌지 않고 남았다는 증명은 아닙니다. 구성, 데이터베이스, 배포를 바꾼 뒤에는 영향받은 검사를 다시 실행합니다. AX Code는 모든 레거시 동작을 자동으로 발견하거나 마이그레이션 동등을 인증하지 않습니다.

계획이 실행되는 때

계획은 두 표면 모두에서 선택입니다. /goal <objective>와 create_goal는 assure가 없으면 목표를 즉시 시작합니다. 고정된 수용 기준이 없고, 완료는 작업 계획(남은 할 일)과 마지막 변경 뒤의 통과하는 검증으로 판단됩니다. /goal --assure <objective>와 create_goal는 assure: true가 있으면 계획 작성자를 먼저 실행하며, 이것이 아래의 실행된 검사 영수증을 완료 요구로 만듭니다.

계약이 없는 목표는 보이는 곳마다 그렇다고 말합니다(/goal view, 목표 대화 상자, 제어 메시지). 따라서 완료 관문을 추론할 필요가 없습니다. 바뀌는 목표에 유효한 계약이 있으면 /goal replace가 보증을 유지합니다.

계획 맥락과 모델 선택

목표 계획은 /goal와 create_goal 도구 모두를 통해 선택된 세션 모델을 상속합니다. 호환되는 호출자 변형은 보존됩니다. 읽기 전용 작성자는 최근의 원래 사용자 요구와 첨부 참조를 받으며, 기록 예산은 16 KiB입니다. 너무 큰 기록은 알림과 함께 더 오래된 기록의 포함을 멈추므로, 더 오래된 요구가 생략된 수정을 조용히 대체할 수 없습니다. 인라인 미디어 내용은 검사된 증거로 다루지 않습니다. 미디어에만 있는 요구에는 검사할 수 있는 소스 파일을 제공합니다.

진행과 차단

get_goal는 현재 검사 상태(통과, 실패, 오래됨, 실행 중, 없음)와 최근 도구 증거 ID를 포함합니다. 완료 관문은 여전히 현재의 성공한 영수증을 요구합니다. 차단 갱신에는 차단 종류, 이유, 필요한 외부 변경, 원래 증거 ID, 독립된 작업이 남지 않았다는 확인이 필요합니다. 차단 이유는 검사할 수 있는 기록이 뒷받침하는 모델 선언이며, 외부 서비스가 계속 쓸 수 없다는 인증이 아닙니다.

새로운 성공 도구 증거를 반복해서 만들지 않는 끝난 턴은 복구 안내를 받은 뒤, 끝나지 않은 작업을 밝히며 목표를 일시 중지합니다. 새 연구 결과는 소스 편집 없이도 셀 수 있습니다. 할 일 다시 쓰기와 반복된 동일 결과는 세지 않습니다. 이것은 제한된 휴리스틱이며, 의미적 진행의 증명이 아닙니다. /goal resume는 다른 시도를 시작합니다. 이전 목표를 위해 생성된 도구 호출은 그 대체 목표를 끝낼 수 없습니다. 도구가 만든 목표는 모델이 다음 단계에서 생성 결과를 받은 뒤에 상태 갱신에 사용할 수 있습니다.

기존 계획 개정

활성, 일시 중지, 차단된 고정 목표를 명시적으로 개정하려면 /goal revise <correction>를 사용합니다. 완료된 작업과 소진된 예산에는 새 목표가 필요합니다. 이전 계획과 다이제스트는 그대로 남습니다. 개정된 계획은 새 신원을 받고, 두 다이제스트와 수정을 잇는 로컬 준비 개정 기록을 받습니다. 현재 목표 신원이 실제로 설치된 후보를 결정합니다. 실패한 동시 후보는 검사를 위해 디스크에 남을 수 있습니다. 옛 영수증은 기록에 남으며 새 개정을 만족할 수 없습니다. 토큰 예산과 누적 사용량은 이어집니다. 개정은 새 지출 예산을 주지 않습니다.

개정은 현재 실행을 취소하고 새 계획을 준비하는 동안 목표를 일시 중지합니다. 계획이 실패하면 이전 계약은 재개할 수 있습니다. 이전에 차단된 목표는 그 상태를 유지합니다. 계획 중의 사용자 일시 중지나 취소는 활성화를 막습니다. 동시 대체는 후보가 인수하는 것을 막습니다. 모델 도구는 고정된 요구를 조용히 개정할 수 없습니다. 결과 계획과 수용 기준을 검토합니다. 실행 가능한 명령만으로는 그 단언이 수정된 요청을 다룬다고 확정되지 않습니다.

검토 결과와 이후의 소스 변경

비어 있지 않은 검토 로그가 성공한 검토를 확정하지는 않습니다. 필수 외부 검토자에게는 실제 종료 코드, 터미널 완료, 소스 또는 diff 신원, 최종 발견 또는 명시적인 발견 없음 판정을 검증하는 프로젝트 소유의 검사를 사용합니다. 경고만 있는 로그, 부분 추론, 시간 초과는 실패해야 합니다. 실패한 시도는 진단을 위해 따로 유지합니다.

새 코드 변경 제출은 인식된 단순한 파일 존재와 검사 확인을 거부합니다. 이것은 좁은 입장 가드이며, 임의의 셸 명령에 대한 의미적 증명이 아닙니다. 기존의 고정 계약은 스키마와 다이제스트를 유지합니다. 체크포인트는 더 오래된 검사에 이 약점이 있으면 경고합니다.

목표 검사 신선도는 현재 목표 동안 성공한 파일 편집 도구가 보고한 해석된 파일 경로도 지문합니다. 모든 multiedit 결과와 원래 소스 목록에서 빠진 경로를 포함합니다. 그 파일을 나중에 편집하면 이전 영수증이 무효가 됩니다. 고정 계약과 다이제스트는 바뀌지 않습니다. 이 추적은 파일 도구 결과 메타데이터를 사용합니다. 임의의 셸 부작용이나 테스트 커버리지를 추론하지는 않습니다. 기존의 파일 시스템 격리, 링크, 크기, 파일 수 한계는 계속 적용됩니다.

검사 출력과 목표 체크포인트는 추가 경로를 밝힙니다. 고정된 테스트 명령이 필요한 회귀를 빠뜨리면 /goal revise <correction>를 요청하고 개정된 검사를 실행합니다. 지문에 파일을 넣는 것은 신선도를 증명하며, 테스트가 그 파일을 실행했다는 뜻은 아닙니다. 열린 버그 조사를 계획할 때는 제한된 소스 디렉터리와 새 회귀를 포함하는 테스트 명령을 선호합니다.

작업 공간 별칭은 관찰된 파일 경로에 대해 정규화됩니다. 외부 임시 파일은 작업 공간 소스 입력이 되지 않습니다. 체크포인트는 외부 내용이 지문되지 않는다고 밝힙니다. 필요한 외부 상태는 여전히 프로젝트 소유의 검증이 필요합니다.

커밋 범위 증거

비어 있지 않은 git log <baseline>..HEAD -- <paths>는 커밋이 필터와 일치한다는 것만 증명합니다. 그 커밋 안의 관계없는 파일이나 다른 커밋을 제외하지는 않습니다. 새 코드 변경 계획은 인식된, 단독으로 쓰인, 비어 있지 않은 경로 필터 Git 로그 단언을 거부합니다. 더 오래된 고정 검사는 다이제스트나 읽기 시점 검증을 바꾸지 않고 개정 안내를 받습니다.

기준 조상을 확인하고, 비어 있지 않은 범위를 요구하고, 경로 필터 없이 모든 커밋의 모든 변경 경로를 검사하는 프로젝트 소유의 검증기를 사용합니다. 삭제된 파일과 이름 변경의 양쪽을 포함하고, 병합 커밋을 명시적으로 다루며, 필요한 브랜치나 메시지 속성은 따로 검증합니다. 기존 계약을 강화하려면 /goal revise를 사용합니다. 고정된 요구를 편집하지 않습니다.

계획 크기와 완전한 재제출

Markdown과 보증 JSON을 포함한 렌더된 계획은 8,192 UTF-8 바이트 안에 들어가야 합니다. 7,168 바이트 아래를 목표로 합니다. 제출이 상한을 넘으면 반복된 산문을 줄이고, kind와 모든 필수 필드를 포함한 완전한 객체를 다시 제출합니다. 수용 id와 검사는 보존합니다. 런타임은 요구를 자르거나, 너무 큰 계획을 받기 위해 읽는 쪽 한계를 올리지 않습니다.

로컬 CLI 애니메이션 검토 영수증

저장소가 소유한 packages/ax-code/script/verify-cli-review-receipts.ts는 round-* 산출물을 검사하며, 영수증 루트는 --root로 고릅니다. 각 라운드에는 revision.txt가 필요하고, grok, claude, codex 각각에는 exit.txt가 필요하며 그와 함께 0와 stdout.jsonl(Grok 텍스트 이벤트) 또는 stdout.txt(Claude/Codex)의 최종 판정 하나가 필요합니다. 실패한 시도는 완료된 라운드 디렉터리 밖에 보존합니다. 실패를 종료 코드 0인 영수증으로 바꾸지 않습니다.

dispositions.json는 findings 배열을 담습니다. 모든 항목은 round, cli, id, status(fixed 또는 rejected), 그리고 비어 있지 않은 evidence를 이름 짓습니다. 고정된 항목은 추가로 regression 객체가 필요하며, 그 객체에는 리터럴 저장소 경로 file가 있고 그 경로는 packages/ax-code/test/cli/tui/ 아래이며, 정확한 Vitest fullName도 있습니다. 중복된 처분이나 모호한 복수 판정은 실패합니다.

검증기는 설치된 Vitest로 그 파일을 실행하며 전역 재시도 기본값은 0입니다(개별 테스트 옵션이 그 기본값을 덮어쓸 수 있습니다). 그다음 참조된 각 단언이 정확히 한 번 통과했는지 확인합니다. 없거나, 건너뛰거나, 실패하거나, 모호한 단언은 검증을 실패시킵니다. 이것은 참조된 테스트가 통과했음을 증명하며, 그 단언이 발견을 의미적으로 다룬다는 뜻은 아닙니다. 거부된 처분은 기록된 판단으로 남습니다. 최종 라운드는 현재 HEAD와 일치해야 합니다. 고쳐졌다고 표시된 발견은 더 새로운 리비전과 검토 라운드가 필요합니다. 커밋되지 않은 코어 패키지 소스, 테스트, 구성 변경은 검증을 막습니다. 관계없는 로컬 ax-code.json 구성은 커밋에 넣지 않습니다.

이 저장소에서 vitest run --dir test/cli/tui는 TUI 디렉터리를 살펴보는 동안 보통 레인의 제외를 보존합니다. 그룹 실행기는 여전히 AX_TEST_FILES로 정확한 파일을 고를 수 있습니다. 디렉터리를 선택해도 제외가 꺼지지는 않습니다.