변경 영향과 누락 파일 찾기
그래프 후보, 변경 파일과 실제 테스트를 함께 읽어 영향 범위를 결정합니다.
가이드 검토 기준: Holmes-Kit 0.40.0 · 2026-11-05 · 설치 대상: 실행 시점의 latest
CLI·OS·설치 방식을 선택하면 해당 명령만 표시합니다. 이 페이지는 컴퓨터를 검사하거나 명령을 실행하지 않습니다.
AGY CLI 일반 연동은 지원 대상입니다. 0.40.0의 AGY run start는 거절되므로 이 오케스트레이션 편에는 실행할 AGY 시작 절차가 없습니다. 다른 CLI를 직접 선택하거나 기본편을 확인하세요.
준비 사항·검증 범위·설치 방식 비교
시작하기 전에
- 기초 과정을 마친 내 작업 폴더와 연결된 MCP 세션. 이 터미널에서 설치 단계의 HOLMES_CLI 또는 PowerShell HolmesCli 경로를 정의하고 파일·버전을 확인합니다.
- 변경 요청과 실제 changedFiles 또는 비교할 Git 기준
분석의 한계와 함께 수정·검증할 파일을 설명할 수 있습니다.
0.40.0 문서 기준 · 2026-11-04 릴리스 계약 검토. 네이티브 실행 근거는 2026-11-01의 0.39.0 기록입니다. macOS 독립 작업 폴더에서 Codex·Claude의 읽기 전용 binding 일치를 관찰했습니다. Claude 훅 이벤트는 있으나 routing 미검증, Codex 훅은 미관찰입니다. 0.40.0 네이티브 재검증과 승인된 작은 변경의 RED/GREEN 검증은 미완료입니다. Windows/Linux는 문서 안내이며 네이티브 검증이 없습니다.
- 1. 별도 사용자 폴더
- 프로젝트 의존성과 전역 npm 설치를 유지하며 버전별로 관리합니다. 설치 경로·업데이트를 별도로 관리합니다. 연결한 프로젝트가 있으면 폴더를 보존해야 합니다.
- 2. 프로젝트 로컬
- 팀·프로젝트별 버전을 잠금 파일로 관리합니다. 공통 실습에 권장합니다. package.json과 잠금 파일을 변경합니다. 비 Node 프로젝트에는 npm 구성이 추가될 수 있습니다.
- 3. 전역 npm
- 여러 프로젝트에서 공통 설치를 사용하기 편리합니다. 쓰기 권한과 업데이트 영향을 확인합니다. 같은 설치를 공유한 프로젝트들에 영향을 줍니다.
패키지 설치 위치와 AI 도구 설정은 별개입니다. 프로젝트 로컬 설치도 Codex 연결 시 사용자 수준 설정을 변경할 수 있습니다.
단계 1 / 4
비교 기준을 고정한다
작업 트리 변경인지 특정 커밋 비교인지 정합니다.
내 작업 폴더의 터미널
git diff --name-only
git diff --cached --name-only
git ls-files --others --exclude-standard
git diff --stat
git diff --cached --stat에이전트에게 요청
unstaged·staged·untracked 세 파일 목록의 합집합을 중복 제거하여 changedFiles로 사용하고 새 파일 내용도 확인해. 커밋 비교라면 정확한 base와 head를 명시하고 해당 비교에서 파일 목록을 구해. 이 요청의 maintenance_analyze를 persist:true로 실행하고 비교 기준과 evidenceDigest를 남겨.예상 결과 — 실제 출력을 직접 확인하세요
- 분석이 현재 파일 목록과 revision을 가리킵니다.
예상과 다르거나 막혔다면
분석이 오래되었거나 architecture axis가 not assessed입니다.
현재 changedFiles를 포함해 다시 분석하고 not assessed를 영향 없음으로 해석하지 않습니다.
에이전트가 할 일 · 용어 설명
실제 변경 파일을 읽고 요청·파일 목록·기준 revision을 분석에 연결합니다.
- MCP
- AI가 Holmes 도구를 호출하는 연결입니다.
- REQ → H-SPEC → A-SPEC → T-SPEC
- 요구 → 상위 설계 → 구현 설계 → 테스트 명세입니다. 실제 반환된 ID를 사용합니다.
- 훅 / binding
- 실행 전후 검사 / 현재 세션이 의도한 프로젝트·서버와 연결됐는지 확인하는 것입니다.
단계 2 / 4
순위를 가설로 읽는다
직접 수정 후보와 추가 조사 후보를 구분합니다.
에이전트에게 요청
maintenance_analyze 후보마다 직접 근거를 확인해. confidence를 정답 확률로 쓰지 말고 관련 테스트·미해결 호출·제약을 함께 정리해.예상 결과 — 실제 출력을 직접 확인하세요
- 수정이 필요한 파일은 실제 코드 연결로 설명됩니다.
예상과 다르거나 막혔다면
상위 후보가 이름만 비슷하고 호출 관계가 없습니다.
직접 코드를 확인해 후보를 제외하거나 낮추고 누락 가능성은 별도로 기록합니다.
에이전트가 할 일 · 용어 설명
rankedImpact, relevantTests, constraints와 unknowns를 읽고 호출·계약·공동 변경 근거를 확인합니다.
- MCP
- AI가 Holmes 도구를 호출하는 연결입니다.
- REQ → H-SPEC → A-SPEC → T-SPEC
- 요구 → 상위 설계 → 구현 설계 → 테스트 명세입니다. 실제 반환된 ID를 사용합니다.
- 훅 / binding
- 실행 전후 검사 / 현재 세션이 의도한 프로젝트·서버와 연결됐는지 확인하는 것입니다.
단계 3 / 4
불완전한 변경을 찾는다
분석에 나온 경로가 실제로 필요한지 검토합니다.
에이전트에게 요청
changedFiles 기반 missingNewFiles와 removedNameUsers를 확인해. import가 실제로 해결되는지와 제거된 이름 사용처를 검증하고, 별칭·동적 호출처럼 분석 밖인 경로를 표시해.예상 결과 — 실제 출력을 직접 확인하세요
- 누락 파일과 남은 사용처를 재현할 수 있고 추정은 분리됩니다.
예상과 다르거나 막혔다면
결과가 비어 있지만 런타임 import가 실패합니다.
빈 결과는 완전성 보증이 아닙니다. 별칭과 동적 경로를 프로젝트 해석기와 실제 테스트로 확인합니다.
에이전트가 할 일 · 용어 설명
missingNewFiles와 removedNameUsers를 확인합니다. 상대 import·언어·작업 트리 제한을 함께 보고합니다.
- MCP
- AI가 Holmes 도구를 호출하는 연결입니다.
- REQ → H-SPEC → A-SPEC → T-SPEC
- 요구 → 상위 설계 → 구현 설계 → 테스트 명세입니다. 실제 반환된 ID를 사용합니다.
- 훅 / binding
- 실행 전후 검사 / 현재 세션이 의도한 프로젝트·서버와 연결됐는지 확인하는 것입니다.
단계 4 / 4
명세와 테스트 범위를 조정한다
새 영향이 목표에 필요한지 결정합니다.
에이전트에게 요청
추가 영향이 승인 범위를 벗어나는지 확인해. 필요하면 명세를 먼저 재검토하고, 관련 회귀 테스트와 실제 diff를 비교해 누락을 보고해.예상 결과 — 실제 출력을 직접 확인하세요
- 최종 diff·명세·테스트 범위가 서로 설명됩니다.
예상과 다르거나 막혔다면
관련 테스트가 새로운 실패를 드러냅니다.
실패의 실제 의존 경로를 기록하고 범위 재검토 후 고칩니다. 실패 테스트를 제외해 범위를 맞추지 않습니다.
에이전트가 할 일 · 용어 설명
필요한 명세 재검토를 마친 뒤 관련 테스트를 실행하고 분석의 예상과 실제 결과를 비교합니다.
- MCP
- AI가 Holmes 도구를 호출하는 연결입니다.
- REQ → H-SPEC → A-SPEC → T-SPEC
- 요구 → 상위 설계 → 구현 설계 → 테스트 명세입니다. 실제 반환된 ID를 사용합니다.
- 훅 / binding
- 실행 전후 검사 / 현재 세션이 의도한 프로젝트·서버와 연결됐는지 확인하는 것입니다.
Holmes Lab의 실제 변경 기록
A-SPEC-101.21은 홈에서 숨겨져 있던 기술 여정·작업·실천의 세 주요 메뉴를 복원하고, 그래프 fallback의 JSON 링크를 제거하며 실천 내용을 확장한 변경입니다. docs/evidence/engineering-perspective의 RED·회귀·빌드 기록이 과거 근거입니다. 아래 명령을 내 프로젝트에서 실행하는 것은 재현이며 그 과거 실행 기록이 아닙니다.
연결된 사례 ↗내 프로젝트에 적용하기
명세 없는 기존 코드는 도입 편으로, 명세가 있는 프로젝트의 새 변경은 요구 관리 편으로 이어가세요. 다른 심화편은 각 선행 조건을 확인합니다.