Holmes LabAgentic Software Engineering Architect

테스트·검토·완료 근거

통과라는 한 단어 대신 실패 재현, 회귀 범위, 실제 관찰을 연결합니다.

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

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

시작하기 전에

  • 기초 과정을 마친 내 작업 폴더와 연결된 MCP 세션. 이 터미널에서 설치 단계의 HOLMES_CLI 또는 PowerShell HolmesCli 경로를 정의하고 파일·버전을 확인합니다.
  • 승인된 A-SPEC과 실제 테스트 실행 환경

무엇이 구현·테스트·실행 관찰되었는지 분리한 검토 묶음을 만듭니다.

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에 전달할 프롬프트공통

에이전트에게 요청

현재 승인된 A-SPEC을 확인하고 maintenance_analyze를 persist:true로 저장해. 실제 ID의 첫 줄 @implements 앵커로 테스트를 작성한 뒤 test_run으로 assertion RED를 기록해.

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

  • 실패가 요구의 누락된 동작을 직접 가리킵니다.
수동 학습 기록이며 실제 환경의 자동 검증 결과가 아닙니다.
예상과 다르거나 막혔다면

패키지를 못 불러오거나 fixture가 잘못되었습니다.

테스트 환경을 고치고 같은 행동 검증을 다시 실행합니다. 환경 오류를 RED 증거로 사용하지 않습니다.

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

승인된 변경 범위와 영향 분석 후 공식 test_run의 assertion RED를 기록합니다.

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

단계 2 / 4

같은 테스트로 개선을 확인한다

T-SPEC과 구현 범위를 검토합니다.

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

에이전트에게 요청

승인된 T-SPEC에 따라 최소 구현하고 동일 테스트를 다시 실행해. assertion을 바꿨다면 이유와 원래 요구를 여전히 검증하는 근거를 설명해.

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

  • 동일 행동 테스트가 GREEN이고 변경 파일이 승인 범위 안입니다.
수동 학습 기록이며 실제 환경의 자동 검증 결과가 아닙니다.
예상과 다르거나 막혔다면

테스트는 통과하지만 다른 입력에서 실패합니다.

경계·실패 입력을 추가하여 구현을 수정하고 새 검증 결과를 기록합니다.

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

대응 T-SPEC 승인 후 최소 구현을 하고 RED에 사용한 테스트를 다시 실행합니다.

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

단계 3 / 4

관련 회귀와 사용 경로를 본다

사용자가 실제로 지나는 경로와 유지할 기존 동작을 고릅니다.

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

에이전트에게 요청

프로젝트 package scripts 또는 테스트 설정에서 실제 검증 명령을 찾아 실행해. UI가 바뀌면 실제 화면과 직접 URL을 확인하고 각 검증이 증명하지 못하는 부분도 적어.

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

  • 명령별 결과와 실제 화면 관찰이 구분되어 있습니다.
수동 학습 기록이며 실제 환경의 자동 검증 결과가 아닙니다.
예상과 다르거나 막혔다면

환경 제한으로 브라우저나 서비스 실행이 불가합니다.

미검증으로 표시하고 재현 조건을 기록합니다. 빌드 성공을 운영 성공으로 바꾸지 않습니다.

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

관련 회귀·타입 검사·빌드를 실행하고 UI 변경은 브라우저로 확인합니다.

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

단계 4 / 4

독립 검토와 잔여 사항을 닫는다

중요한 미해결 사항과 배포 결정을 검토합니다.

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

에이전트에게 요청

최종 diff, RED/GREEN, 회귀·빌드·실행 관찰과 미검증 항목을 검토 묶음으로 정리해. 독립 검토 결과와 미해결 critical/important를 구분하고 배포는 별도로 남겨.

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

  • 각 완료 주장에 실제 근거가 있고 미해결 사항이 숨겨지지 않습니다.
수동 학습 기록이며 실제 환경의 자동 검증 결과가 아닙니다.
예상과 다르거나 막혔다면

검토 후 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·회귀·빌드 기록이 과거 근거입니다. 아래 명령을 내 프로젝트에서 실행하는 것은 재현이며 그 과거 실행 기록이 아닙니다.

연결된 사례 ↗

내 프로젝트에 적용하기

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