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

에이전트에게 요청

내 요청을 원문 그대로 보존하고 사용자 행동으로 확인할 수 있는 성공 조건을 제안해. 가정과 확인이 필요한 내용을 분리해.

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

  • 각 기준에 실제 확인 방법이 있습니다.
수동 학습 기록이며 실제 환경의 자동 검증 결과가 아닙니다.
예상과 다르거나 막혔다면

품질 목표가 수치나 관찰 조건 없이 남습니다.

측정 환경 또는 사용자 시나리오를 정하고 확정되지 않은 수치를 만들지 않습니다.

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

요청 원문을 보존하고 모호한 부분과 수용 기준 후보를 나눕니다.

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

단계 2 / 4

최신 근거로 분류한다

분류가 요청 의도와 맞는지 확인합니다.

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

에이전트에게 요청

requirement_triage를 내 요청 원문과 persist:true로 실행해. fulfilled, existing-change, new 또는 ambiguous 판정과 후보 계보, digest를 설명해.

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

  • fulfilled는 기존 계보를 재사용하고 existing-change는 선행 ID를 명시합니다.
수동 학습 기록이며 실제 환경의 자동 검증 결과가 아닙니다.
예상과 다르거나 막혔다면

새로고침 실패로 ambiguous가 남습니다.

캐시 결과를 새 근거로 포장하지 말고 새로고침 원인을 해결한 뒤 다시 분류합니다.

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

requirement_triage에 정확한 원문과 persist:true를 주고 fresh evidence를 확인합니다.

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

단계 3 / 4

문서 본문을 직접 작성한다

범위 밖 항목과 호환성 경계를 함께 검토합니다.

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

에이전트에게 요청

분류된 계보에 맞춰 공식 도구로 명세를 생성해. 모든 TODO와 REQ Success Criteria를 구체적으로 작성하고 입력·출력·실패·호환성·바꿀 파일을 연결해.

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

  • 실패 사례와 제외 범위까지 문서에 적혀 있습니다.
수동 학습 기록이며 실제 환경의 자동 검증 결과가 아닙니다.
예상과 다르거나 막혔다면

코드 목록만 있고 왜 바꾸는지 설명이 없습니다.

구현 계획보다 먼저 사용자 동작과 성공 기준을 보완합니다.

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

공식 도구로 scaffold하고 markdown 본문을 편집합니다. 새 REQ 생성에는 최신 triage_evidence를 전달합니다.

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

단계 4 / 4

현재 내용을 승인하고 연결한다

현재 diff를 읽고 공식 승인 요청을 결정합니다.

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

에이전트에게 요청

spec_next로 필요한 승인 순서를 확인하고 현재 문서와 digest를 보여줘. 승인되면 계보와 다음 테스트 단계를 정리해. 승인 이후 내용이 바뀌면 이전 승인을 재사용하지 마.

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

  • 승인 상태와 현재 내용이 일치하며 다음 단계가 명확합니다.
수동 학습 기록이며 실제 환경의 자동 검증 결과가 아닙니다.
예상과 다르거나 막혔다면

부모 digest 불일치나 승인 대기가 있습니다.

변경된 부모와 자식의 영향을 확인하여 공식 재승인 순서를 따릅니다.

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

spec_next로 순서를 확인하고 spec_slice_approve 또는 spec_approve를 사용합니다. 수정이 생기면 재검토합니다.

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

연결된 사례 ↗

내 프로젝트에 적용하기

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