기존 코드베이스에 도입
이미 동작하는 코드에서 명세를 복원하되 관찰된 동작과 의도한 정책을 구분합니다.
가이드 검토 기준: 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 경로를 정의하고 파일·버전을 확인합니다.
- 기존 테스트 명령과 검토할 작은 모듈 하나
선택한 모듈의 요구·명세·코드 연결을 검토 가능한 단위로 확보합니다.
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
기준 동작을 남긴다
한 모듈과 유지해야 할 공개 동작을 고릅니다.
에이전트에게 요청
이 모듈을 읽기 전용으로 조사해. 공개 입력·출력, 기존 테스트, 현재 실패를 나눠 정리하고 추측은 표시해.예상 결과 — 실제 출력을 직접 확인하세요
- 현재 동작과 테스트 기준이 있으며 아직 소스 변경은 없습니다.
예상과 다르거나 막혔다면
테스트가 없거나 외부 서비스에 의존합니다.
재현 가능한 순수 동작부터 범위를 줄이고 서비스 실행은 별도 허가와 환경을 준비합니다.
에이전트가 할 일 · 용어 설명
reverse_scan으로 선택한 범위를 읽고 기존 테스트 명령을 실행해 실패와 미지원 영역을 기록합니다.
- MCP
- AI가 Holmes 도구를 호출하는 연결입니다.
- REQ → H-SPEC → A-SPEC → T-SPEC
- 요구 → 상위 설계 → 구현 설계 → 테스트 명세입니다. 실제 반환된 ID를 사용합니다.
- 훅 / binding
- 실행 전후 검사 / 현재 세션이 의도한 프로젝트·서버와 연결됐는지 확인하는 것입니다.
단계 2 / 4
도입 요구를 먼저 확정한다
동작 유지와 복원 대상 범위를 정의합니다.
에이전트에게 요청
이 모듈의 기존 동작을 바꾸지 않고 명세 연결을 복원하려 해. requirement_triage를 persist:true로 실행하고 해당 계보의 도입 REQ와 성공 조건을 준비해.예상 결과 — 실제 출력을 직접 확인하세요
- 도입 목표, 제외 범위, 실제 부모 REQ ID를 확인할 수 있습니다.
예상과 다르거나 막혔다면
parentReqId is required 또는 부모가 없다는 응답입니다.
번호를 만들어 넣지 말고 spec_next로 계보를 확인하여 실제 REQ를 준비합니다.
에이전트가 할 일 · 용어 설명
requirement_triage를 저장하고 계보에 맞는 REQ를 작성합니다. 반환된 실제 부모 ID를 유지합니다.
- MCP
- AI가 Holmes 도구를 호출하는 연결입니다.
- REQ → H-SPEC → A-SPEC → T-SPEC
- 요구 → 상위 설계 → 구현 설계 → 테스트 명세입니다. 실제 반환된 ID를 사용합니다.
- 훅 / binding
- 실행 전후 검사 / 현재 세션이 의도한 프로젝트·서버와 연결됐는지 확인하는 것입니다.
단계 3 / 4
코드에서 초안을 복원한다
추출된 동작이 유지할 계약인지 직접 검토합니다.
에이전트에게 요청
reverse_draft의 현재 입력 스키마를 확인하고 승인된 도입 요구의 실제 parentReqId와 이 모듈 범위로 초안을 복원해. 관찰된 코드와 추정한 정책을 분리해.예상 결과 — 실제 출력을 직접 확인하세요
- 초안의 각 동작을 실제 파일이나 테스트로 추적할 수 있습니다.
예상과 다르거나 막혔다면
초안이 예외 처리나 동적 호출을 누락합니다.
사람이 코드를 확인하여 누락과 불확실성을 문서에 추가합니다. 추출되지 않은 부분을 지원된 것으로 표시하지 않습니다.
에이전트가 할 일 · 용어 설명
reverse_draft의 현재 도구 스키마를 확인하여 선택한 범위와 parentReqId로 실행합니다. 기본 dry-run 초안을 검토한 뒤 실제 생성 여부를 결정합니다.
- MCP
- AI가 Holmes 도구를 호출하는 연결입니다.
- REQ → H-SPEC → A-SPEC → T-SPEC
- 요구 → 상위 설계 → 구현 설계 → 테스트 명세입니다. 실제 반환된 ID를 사용합니다.
- 훅 / binding
- 실행 전후 검사 / 현재 세션이 의도한 프로젝트·서버와 연결됐는지 확인하는 것입니다.
단계 4 / 4
승인하고 작은 범위부터 연결한다
초안과 실제 동작의 차이를 해결한 뒤 승인합니다.
에이전트에게 요청
복원 명세의 미해결 사항을 먼저 보여줘. 승인된 후 maintenance_analyze를 저장하고 범위 내 앵커와 추적성을 연결해. 동작 변경이 필요하면 별도 변경 요구로 분리해.예상 결과 — 실제 출력을 직접 확인하세요
- 코드 연결과 회귀 결과가 있으며 동작 변경은 별도 계보에 남습니다.
예상과 다르거나 막혔다면
연결 작업 중 기존 결함을 발견합니다.
도입 범위를 넓히지 말고 결함을 기록하고 새 변경 분류로 처리합니다.
에이전트가 할 일 · 용어 설명
공식 승인 후 maintenance_analyze를 저장합니다. reverse_anchor의 기본 dry-run으로 앵커 계획을 검토하고 승인 범위에 적용한 뒤 기존 테스트를 다시 실행합니다.
- MCP
- AI가 Holmes 도구를 호출하는 연결입니다.
- REQ → H-SPEC → A-SPEC → T-SPEC
- 요구 → 상위 설계 → 구현 설계 → 테스트 명세입니다. 실제 반환된 ID를 사용합니다.
- 훅 / binding
- 실행 전후 검사 / 현재 세션이 의도한 프로젝트·서버와 연결됐는지 확인하는 것입니다.
내 프로젝트에 적용
Holmes Lab의 주요 메뉴 복원은 이미 명세가 있는 변경입니다. 이 시나리오는 명세가 없는 내 모듈에 적용하는 개념 예시이며 Lab 도입 실행 로그를 주장하지 않습니다.
연결된 사례 ↗내 프로젝트에 적용하기
명세 없는 기존 코드는 도입 편으로, 명세가 있는 프로젝트의 새 변경은 요구 관리 편으로 이어가세요. 다른 심화편은 각 선행 조건을 확인합니다.