Holmes LabAgentic Software Engineering Architect

기존 코드베이스에 도입

이미 동작하는 코드에서 명세를 복원하되 관찰된 동작과 의도한 정책을 구분합니다.

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

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

시작하기 전에

  • 기초 과정을 마친 내 작업 폴더와 연결된 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

기준 동작을 남긴다

한 모듈과 유지해야 할 공개 동작을 고릅니다.

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

에이전트에게 요청

이 모듈을 읽기 전용으로 조사해. 공개 입력·출력, 기존 테스트, 현재 실패를 나눠 정리하고 추측은 표시해.

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

  • 현재 동작과 테스트 기준이 있으며 아직 소스 변경은 없습니다.
수동 학습 기록이며 실제 환경의 자동 검증 결과가 아닙니다.
예상과 다르거나 막혔다면

테스트가 없거나 외부 서비스에 의존합니다.

재현 가능한 순수 동작부터 범위를 줄이고 서비스 실행은 별도 허가와 환경을 준비합니다.

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

reverse_scan으로 선택한 범위를 읽고 기존 테스트 명령을 실행해 실패와 미지원 영역을 기록합니다.

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

단계 2 / 4

도입 요구를 먼저 확정한다

동작 유지와 복원 대상 범위를 정의합니다.

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

에이전트에게 요청

이 모듈의 기존 동작을 바꾸지 않고 명세 연결을 복원하려 해. 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

코드에서 초안을 복원한다

추출된 동작이 유지할 계약인지 직접 검토합니다.

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

에이전트에게 요청

reverse_draft의 현재 입력 스키마를 확인하고 승인된 도입 요구의 실제 parentReqId와 이 모듈 범위로 초안을 복원해. 관찰된 코드와 추정한 정책을 분리해.

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

  • 초안의 각 동작을 실제 파일이나 테스트로 추적할 수 있습니다.
수동 학습 기록이며 실제 환경의 자동 검증 결과가 아닙니다.
예상과 다르거나 막혔다면

초안이 예외 처리나 동적 호출을 누락합니다.

사람이 코드를 확인하여 누락과 불확실성을 문서에 추가합니다. 추출되지 않은 부분을 지원된 것으로 표시하지 않습니다.

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

reverse_draft의 현재 도구 스키마를 확인하여 선택한 범위와 parentReqId로 실행합니다. 기본 dry-run 초안을 검토한 뒤 실제 생성 여부를 결정합니다.

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

내 프로젝트에 적용

Holmes Lab의 주요 메뉴 복원은 이미 명세가 있는 변경입니다. 이 시나리오는 명세가 없는 내 모듈에 적용하는 개념 예시이며 Lab 도입 실행 로그를 주장하지 않습니다.

연결된 사례 ↗

내 프로젝트에 적용하기

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