sg-reverse-engineer-servicelisted

# Reverse Engineer Service 전체 파일을 차례로 읽지 말고, 결정적 분석 결과로 읽을 범위를 좁힌 뒤 코드와 런타임 증거를 대조한다. 현재 상태의 이해에 집중하고 목표 아키텍처나 개선안은 사용자가 별도로 요청할 때만 다룬다. ## 시작 1. 사용자의 학습 목적, 알고 싶은 기능이나 시나리오, 사용할 수 있는 코드·문서·IaC·테스트·서비스·로그·트레이스를 확인한다. 2. 질문이 탐색적이어도 서비스 가치, 주요 actor, 도메인 용어에서 해당 기능으로 내려가는 흐름을 제시한다. 3. 분석 대상 root와 revision, dirty 상태, 환경, 접근 제한을 기록한다. 비밀값이나 실제 업무 데이터는 출력하지 않는다. 4. 세부 탐색 방법이 필요하면 [탐색 플레이북](references/exploration-playbook.md)을 읽는다. 문서를 만들거나 갱신하기 전에는 [문서 계약](references/document-contract.md)을 읽는다. ## 증거 모델 주장마다 진실 계층과 상태를 함께 기록한다. - `intended`: README, ADR, 카탈로그, 인터뷰가 말하는 의도 - `implemented`: 코드, 설정, IaC, 테스트, CI가 구현한 상태 - `observed`: 로그, 메트릭, 트레이스, 실행 중 서비스에서 관찰한 상태 - `확인`: 직접 증거가 주장을 지지함 - `추론`: 여러 증거를 연결한 해석이며 반증 가능함 - `미확인`: 필요한 증거가 없거나 상충함 정적 호출 후보를 런타임 사실로 승격하지 않는다. 문서와 구현, 구현과 관찰이 다르면 드리프트로 명시한다. ## 코드 탐색 1. 임시 디렉터리를 만들고 Windows에서는 `scripts/analyze-code.ps1 discover --root <repo> --output <temp>/facts.json`, macOS·Linux에서는 `scripts/analyze-code.sh discover --root <repo> --output <temp>/facts.json`을 실행한다. 2. 후보가 여러 개면 질문, manifest 근거, 대표 가치 흐름을 기준으로 사용자와 엔트리포인트를 정한다. 임의로 고르지 않는다. 3. `trace --entry <file[#symbol]|file:line>`을 실행한다. 큰 그래프는 `--max-depth`와 `--max-nodes`로 제한한다. 4. `read_set`의 파일과 줄 범위, 미해결 frontier만 우선 읽는다. `candidate`, `syntactic`, `dynamic` edge는 코드에서 확인하고도 불명확하면 그대로 남긴다. 5. TypeScript Compiler API가 없고 대상 저장소에 dependency-cruiser가 있으면 module-only trace를 사용한다. symbol/call 관계가 없음을 명시하고 필요한 파일은 Agent가 확인한다. 분석기가 capability 부족을 종료 코드 `3`으로 보고하면 도구를 자동 설치하지 않는다.