Diagnose

---
name: diagnose
description: 오류·잘못된 출력·성능 저하를 재현하고 구분 가능한 실험으로 원인을 좁힌다. 버그 진단과 수정 요청에 사용하며 일반 코드 품질 탐색은 범위로 확대하지 않는다.
---

# Diagnose

코드와 실행 결과의 불일치, 환경별 차이, 제한 기능이 작동하지 않거나 자원이 누적되는 신호에는 [실행 환경 계약](references/workflows/runtime-contract.md)을 적용한다. 코드의 가정과 실제 버전·capability·실효 설정 차이도 가설에 포함한다.

용어·허용 상태·소유권 충돌 때문에 기대값이 불명확하면 실험을 정하기 전에 [domain](references/workflows/domain.md)을 읽고 계약을 구분한다. 원인이 공유 책임·모듈 경계에 있어 변경이 필요하면 수정 전에 [architecture](references/workflows/architecture.md)로 기존 경로와 소비자 영향을 확인한다. 확인된 단일 조건문 오류에는 전체 도메인·구조 설계를 추가하지 않는다.

원인 조사에 외부 API·호환 사실이 부족하면 [research](references/workflows/research.md), 성능 저하를 측정할 때는 [optimize](references/workflows/optimize.md)의 측정 절차만 사용한다. 원인 확인 전 최적화 수정을 시작하지 않는다. 수정이 허용되면 [test](references/workflows/test.md)로 원인 회귀를 고정하고 [clean](references/workflows/clean.md)으로 diff를 점검한 뒤 [verify](references/workflows/verify.md)로 같은 실패·복구 경계를 확인한다. 이미 수행한 실험·검증은 재사용한다.

먼저 [공통 실행 계약](references/execution-contract.md)을 읽는다. 코드 수정을 시작하거나 작업 branch/worktree를 통합·정리할 때는 [작업 공간 수명주기](references/workspace-lifecycle.md)를 읽고 생성부터 안전한 정리 영수증까지 적용한다. 분석만 요청됐다면 원인과 수정 제안까지, 수정이 허용됐다면 회귀 검증까지 진행한다.

1. **관찰 경계 확보.** cwd, branch/worktree, 지침, 기존 변경과 실행 도구를 확인한다. 사용자 증상의 기대값·실제값·입력·발생 환경·최초 발생 시점과 영향 범위를 기록한다. 실제 entrypoint에서 관련 모듈과 외부 의존성까지 호출/데이터 흐름을 좁혀 읽는다. 넓은 저장소는 조사한 하위 시스템과 미탐색 범위를 구분한다.
2. **실패 신호 만들기.** 기존 테스트, 실제 CLI/API/UI 또는 안전한 trace replay 중 증상을 관찰하는 가장 작은 공개 경계를 택한다. 명령/행동, 입력, 버전·설정, exit/status와 관련 출력·로그를 보존한다. 입력이나 환경 조건을 하나씩 줄이면서 같은 실패인지 확인한다. 재현 실패는 원인 확정이 아니다. 시도한 조건, 부족한 자료·권한과 재개 조건을 남기고 가능한 읽기 조사를 계속하되 추측으로 수정하지 않는다. 비결정적 문제는 횟수·seed·실패율을 기록하고 재시도 시간/횟수를 제한한다.
3. **가설을 구분한다.** 수정 전에 관찰을 설명하는 경쟁 가설과 각각의 반증 가능한 예측을 적는다. 작은 명백한 결함에 개수를 채우려고 가설을 발명하지 않는다. 각 실험에는 입력/통제 조건, 가설별 예상 결과, 실제 결과와 지지·기각·미결 판정을 남긴다. 한 번에 한 변수를 바꾸고 실패 지점 전후의 값, stack/trace, 정상 대조군을 비교한다. 외부 timeout/인증 실패와 내부 결함을 분리한다. 도구 선택과 성능 분기는 [실험 방법](references/experiments.md)을 읽는다.
4. **원인에 최소 수정.** 증상 → 실행 경로 → 계약 위반 → 원인이라는 연결이 실험 결과로 설명되고 수정 권한이 있을 때 진행한다. 재현을 공개 경계 회귀 테스트로 고정하고 수정 전 실패를 확인한 뒤 해당 원인만 고친다. 진단 계측은 필요한 증거를 보존한 후 작업 소유 부분만 정리한다. 수정이 실패하면 가설로 돌아가며 무관한 리팩터링을 누적하지 않는다. 고위험 인증·결제·데이터 변경은 독립 검토가 완료 조건이다.
5. **같은 조건으로 확인.** 원래 재현과 회귀 테스트를 다시 실행하고 인접 정상·경계·실패/복구 사례 중 관련 위험을 확인한다. 성능은 같은 workload·환경·반복 조건의 전후 수치로 판단한다. 기존 사용자 변경의 보존과 최종 diff를 확인한다. 테스트 통과만으로 실행하지 않은 UI/API/운영 환경을 성공으로 표시하지 않는다.

결과는 원인과 최소 수정, 재현 전후 및 회귀 결과, 남은 한계를 공통 계약의 사용자 언어로 짧게 보고한다. 상세 증거에는 환경/입력, 가설·실험 표, 실제 명령과 출력의 원본 참조, 변경 파일, PASS/FAIL/NOTRUN과 재개 조건을 남긴다. 원인 미확정·외부 장애·검증 불가를 해결 완료와 구분하고, 로그의 비밀정보는 제거한다.