Holmes LabAgentic Software Engineering Architect

변경 영향과 누락 파일 찾기

그래프 후보, 변경 파일과 실제 테스트를 함께 읽어 영향 범위를 결정합니다.

가이드 검토 기준: Holmes-Kit 0.40.0 · 2026-11-05 · 설치 대상: 실행 시점의 latest

준비 사항·검증 범위·설치 방식 비교

시작하기 전에

  • 기초 과정을 마친 내 작업 폴더와 연결된 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
AI CLI에 전달할 프롬프트공통

에이전트에게 요청

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

순위를 가설로 읽는다

직접 수정 후보와 추가 조사 후보를 구분합니다.

AI CLI에 전달할 프롬프트공통

에이전트에게 요청

maintenance_analyze 후보마다 직접 근거를 확인해. confidence를 정답 확률로 쓰지 말고 관련 테스트·미해결 호출·제약을 함께 정리해.

예상 결과 — 실제 출력을 직접 확인하세요

  • 수정이 필요한 파일은 실제 코드 연결로 설명됩니다.
수동 학습 기록이며 실제 환경의 자동 검증 결과가 아닙니다.
예상과 다르거나 막혔다면

상위 후보가 이름만 비슷하고 호출 관계가 없습니다.

직접 코드를 확인해 후보를 제외하거나 낮추고 누락 가능성은 별도로 기록합니다.

에이전트가 할 일 · 용어 설명

rankedImpact, relevantTests, constraints와 unknowns를 읽고 호출·계약·공동 변경 근거를 확인합니다.

MCP
AI가 Holmes 도구를 호출하는 연결입니다.
REQ → H-SPEC → A-SPEC → T-SPEC
요구 → 상위 설계 → 구현 설계 → 테스트 명세입니다. 실제 반환된 ID를 사용합니다.
훅 / binding
실행 전후 검사 / 현재 세션이 의도한 프로젝트·서버와 연결됐는지 확인하는 것입니다.

단계 3 / 4

불완전한 변경을 찾는다

분석에 나온 경로가 실제로 필요한지 검토합니다.

AI CLI에 전달할 프롬프트공통

에이전트에게 요청

changedFiles 기반 missingNewFiles와 removedNameUsers를 확인해. import가 실제로 해결되는지와 제거된 이름 사용처를 검증하고, 별칭·동적 호출처럼 분석 밖인 경로를 표시해.

예상 결과 — 실제 출력을 직접 확인하세요

  • 누락 파일과 남은 사용처를 재현할 수 있고 추정은 분리됩니다.
수동 학습 기록이며 실제 환경의 자동 검증 결과가 아닙니다.
예상과 다르거나 막혔다면

결과가 비어 있지만 런타임 import가 실패합니다.

빈 결과는 완전성 보증이 아닙니다. 별칭과 동적 경로를 프로젝트 해석기와 실제 테스트로 확인합니다.

에이전트가 할 일 · 용어 설명

missingNewFiles와 removedNameUsers를 확인합니다. 상대 import·언어·작업 트리 제한을 함께 보고합니다.

MCP
AI가 Holmes 도구를 호출하는 연결입니다.
REQ → H-SPEC → A-SPEC → T-SPEC
요구 → 상위 설계 → 구현 설계 → 테스트 명세입니다. 실제 반환된 ID를 사용합니다.
훅 / binding
실행 전후 검사 / 현재 세션이 의도한 프로젝트·서버와 연결됐는지 확인하는 것입니다.

단계 4 / 4

명세와 테스트 범위를 조정한다

새 영향이 목표에 필요한지 결정합니다.

AI CLI에 전달할 프롬프트공통

에이전트에게 요청

추가 영향이 승인 범위를 벗어나는지 확인해. 필요하면 명세를 먼저 재검토하고, 관련 회귀 테스트와 실제 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·회귀·빌드 기록이 과거 근거입니다. 아래 명령을 내 프로젝트에서 실행하는 것은 재현이며 그 과거 실행 기록이 아닙니다.

연결된 사례 ↗

내 프로젝트에 적용하기

명세 없는 기존 코드는 도입 편으로, 명세가 있는 프로젝트의 새 변경은 요구 관리 편으로 이어가세요. 다른 심화편은 각 선행 조건을 확인합니다.