런타임 디버그 툴킷

디버그 모드

현재 사용자가 $debug-mode를 호출하거나, 'debug mode'라고 말하거나, 계측된 디버깅을 요청할 때만 세션을 시작합니다. 활성 디버그 세션이 있는 경우, 사용자의 응답이나 컨텍스트 압축 이후에도 항상 재개합니다. 세션은 3단계가 서버를 준비할 때 활성화됩니다. 세션은 8단계 정리 또는 명시적 중단 후에만 종료됩니다. 어느 조건도 해당하지 않으면 분석, 수집 또는 계측을 시작하기 전에 중지합니다.

이 워크플로우는 형제 trace-mode 워크플로우를 기반으로 합니다. 수정, 검증 및 정리를 통해 위치 증거를 확장합니다. 형제 스크립트에는 Node.js 24 이상이 필요합니다.

다음 증거 루프를 실행합니다:

코드 분석 -> 가설 수립 -> trace-mode로 추적 -> 증명 -> 수정 -> 검증 -> 정리

계측을 통해 자율적으로 작업합니다. 첫 번째 계획된 사용자 상호 작용은 재현 체크포인트입니다. 재현 및 검증은 게이트(gate)입니다.

체크포인트 불변성: 모든 수동 재현 또는 검증 시도는 새로운 체크포인트가 필요합니다. 도구 가용성만이 경로를 선택합니다: 네이티브 Codex request_user_input이 나열된 경우 반드시 호출해야 합니다. 그렇지 않으면 Pi chooser가 나열된 경우 이를 호출하고, 두 대화형 경로 모두 실행할 수 없는 경우에만 정확한 일반 텍스트 템플릿을 사용합니다. 네이티브 도구 호출이 체크포인트입니다; 설명이나 최종 답변으로 대체할 수 없습니다. 네이티브 취소는 게이트를 보류 상태로 두며, 이전 결과는 현재 시도만 승인합니다.

1. 코드 경로 분석

보고된 증상에서 저장소 작업을 시작합니다. 관련 진입점, 핸들러, 상태 전환, 기존 로그 및 최근 변경 사항을 읽습니다. 사용자의 트리거에서 관찰된 결과까지의 후보 경로를 매핑합니다. 버그 카드를 작성합니다:

• 증상 및 예상 동작
• 알려진 트리거, 경로, 명령, 입력 또는 픽스처
• 후보 런타임 경로 및 논쟁되는 경계
• 관련 환경, 빈도, 변경 사항 및 증거
• 관찰 가능한 승인 기준

알 수 없는 사실은 unknown으로 기록합니다. 중요한 미지수는 코드 읽기 또는 식별 런타임 프로브를 통해 해결합니다.

완료 조건: 하나의 후보 경로가 트리거를 증상에 연결하고, 각 논쟁되는 분기에 명명된 프로브 경계가 있습니다.

2. 가설 매트릭스 구축

프로브를 추가하기 전에 2~5개의 순위가 매겨진 가설을 작성합니다. 코드 분석 및 사용 가능한 증거에 매트릭스를 고정합니다. 다음 형식을 사용합니다:

H1 <간단한 원인>
예측: <런타임 상태, 경로 또는 타이밍>
프로브: <이벤트 이름 및 코드 위치>
확인됨: <특정 기록 조건>
기각됨: <특정 기록 조건>

구체적인 예측이 없는 가설은 더 많은 코드 읽기가 필요합니다. 여러 가설을 구분하는 프로브를 선호합니다.

완료 조건: 모든 가설이 반증 가능한 조건과 구별되는 계획된 프로브를 가지고 있습니다.

3. Trace Mode를 통해 추적

형제 trace-mode 스킬을 읽습니다. 버그 카드와 함께 이벤트 계획, 서버 시작 및 계측 단계를 사용합니다. 디버그 이벤트 확장에 대한 references/probes.md를 읽습니다. 독립형 trace 체크포인트 전에 여기로 돌아옵니다.

이 워크플로우는 호출자입니다. trace-mode 워크플로우는 활성 프로브와 5개의 서버 값을 반환해야 합니다.

완료 조건: 모든 가설에 활성 프로브가 있고 5개의 서버 값을 모두 알고 있습니다.

4. 재현 게이트 통과

수정 전 체크포인트를 제시하기 전에 references/checkpoints.md를 읽습니다. 위에서 선택한 체크포인트 경로를 통해 수정 전 프로토콜을 실행합니다. 그런 다음 결과를 기다리고 상태 테이블을 통해 라우팅합니다. 모든 재시도는 새로운 대화형 호출과 함께 이 게이트를 통해 돌아옵니다.

완료 조건: 유효한 A, B 또는 C 결과가 단계별로 라우팅되었습니다.

5. 원인 증명

수정 전 A 이후, 제품 코드를 편집하기 전에 LOG_FILE의 현재 세션 기록을 읽습니다. 모든 예상 프로브가 있는지 확인한 다음 파일 순서대로 기록을 검사하고 관련 값을 각 가설 예측과 비교합니다. 각 가설을 CONFIRMED, REJECTED 또는 INCONCLUSIVE로 분류합니다. 증거 보고서를 작성합니다:

H1 <간단한 원인>
상태: CONFIRMED
증거: <특정 이벤트 및 값>

H2 <간단한 원인>
상태: REJECTED
증거: <특정 이벤트 및 값>

승인: <하나의 관찰 가능한 문장>
다음 작업: <확인된 원인에 대한 가장 작은 수정>

예상 프로브가 누락되면 확인이 차단됩니다. 모든 결과가 기각되거나 결정적이지 않은 경우 2단계로 돌아갑니다.

완료 조건: 현재 실행 기록이 하나의 설명 가능한 원인을 확인하고, 하나의 관찰 가능한 승인 기준이 있습니다.

6. 증거 기반 수정

확인된 원인을 해결하는 가장 작은 변경을 수행합니다. 모든 프로브를 활성 상태로 유지합니다. 이벤트를 runId: "post-fix"로 변경합니다. 동작을 자동화할 수 있는 경우 집중된 회귀 테스트를 추가합니다.

완료 조건: 각 제품 편집이 원인으로 추적되고, 수정 후 증거가 준비되었습니다.

7. 검증 게이트 통과

선택한 경로를 통해 references/checkpoints.md의 수정 후 체크포인트를 제시합니다. 그런 다음 결과를 기다리고 상태 테이블을 통해 라우팅합니다. 모든 이후의 검증 시도는 다른 대화형 호출이 필요합니다.

완료 조건: 사용자가 명시된 승인 기준에 대해 수정 후 B를 반환합니다.

8. 기계적 정리

LOG_SERVER_PROBE <session_id>로 표시된 모든 쌍 영역을 제거합니다. 세션 ID, LOG_SERVER_PROBE 및 두 영역 형식을 검색합니다. 복사된 헬퍼와 모든 임시 계측을 제거합니다. 사용자가 보존된 증거를 요청하지 않는 한 LOG_FILE을 삭제합니다. 사용자가 종료를 요청하지 않는 한 공유 서버를 계속 실행합니다. 관련 검사를 실행하고 최종 diff를 검사합니다.

완료 조건: 마커 및 세션 검색이 저장소에서 0개의 일치를 반환하고, 검사가 통과하고, 제품 변경 사항만 남아 있습니다.

예외 분기

수집, 재현 또는 전달에 실패한 경우에만 references/troubleshooting.md를 읽습니다.