요구를 중복 없이 구체화
요청 분류부터 계보 선택, 성공 조건과 승인까지 이어지는 요구 관리 흐름입니다.
가이드 검토 기준: 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
관찰할 성공을 쓴다
사용자, 시작 상태, 행동, 관찰 결과와 유지할 동작을 적습니다.
에이전트에게 요청
내 요청을 원문 그대로 보존하고 사용자 행동으로 확인할 수 있는 성공 조건을 제안해. 가정과 확인이 필요한 내용을 분리해.예상 결과 — 실제 출력을 직접 확인하세요
- 각 기준에 실제 확인 방법이 있습니다.
예상과 다르거나 막혔다면
품질 목표가 수치나 관찰 조건 없이 남습니다.
측정 환경 또는 사용자 시나리오를 정하고 확정되지 않은 수치를 만들지 않습니다.
에이전트가 할 일 · 용어 설명
요청 원문을 보존하고 모호한 부분과 수용 기준 후보를 나눕니다.
- MCP
- AI가 Holmes 도구를 호출하는 연결입니다.
- REQ → H-SPEC → A-SPEC → T-SPEC
- 요구 → 상위 설계 → 구현 설계 → 테스트 명세입니다. 실제 반환된 ID를 사용합니다.
- 훅 / binding
- 실행 전후 검사 / 현재 세션이 의도한 프로젝트·서버와 연결됐는지 확인하는 것입니다.
단계 2 / 4
최신 근거로 분류한다
분류가 요청 의도와 맞는지 확인합니다.
에이전트에게 요청
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
문서 본문을 직접 작성한다
범위 밖 항목과 호환성 경계를 함께 검토합니다.
에이전트에게 요청
분류된 계보에 맞춰 공식 도구로 명세를 생성해. 모든 TODO와 REQ Success Criteria를 구체적으로 작성하고 입력·출력·실패·호환성·바꿀 파일을 연결해.예상 결과 — 실제 출력을 직접 확인하세요
- 실패 사례와 제외 범위까지 문서에 적혀 있습니다.
예상과 다르거나 막혔다면
코드 목록만 있고 왜 바꾸는지 설명이 없습니다.
구현 계획보다 먼저 사용자 동작과 성공 기준을 보완합니다.
에이전트가 할 일 · 용어 설명
공식 도구로 scaffold하고 markdown 본문을 편집합니다. 새 REQ 생성에는 최신 triage_evidence를 전달합니다.
- MCP
- AI가 Holmes 도구를 호출하는 연결입니다.
- REQ → H-SPEC → A-SPEC → T-SPEC
- 요구 → 상위 설계 → 구현 설계 → 테스트 명세입니다. 실제 반환된 ID를 사용합니다.
- 훅 / binding
- 실행 전후 검사 / 현재 세션이 의도한 프로젝트·서버와 연결됐는지 확인하는 것입니다.
단계 4 / 4
현재 내용을 승인하고 연결한다
현재 diff를 읽고 공식 승인 요청을 결정합니다.
에이전트에게 요청
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·회귀·빌드 기록이 과거 근거입니다. 아래 명령을 내 프로젝트에서 실행하는 것은 재현이며 그 과거 실행 기록이 아닙니다.
연결된 사례 ↗내 프로젝트에 적용하기
명세 없는 기존 코드는 도입 편으로, 명세가 있는 프로젝트의 새 변경은 요구 관리 편으로 이어가세요. 다른 심화편은 각 선행 조건을 확인합니다.