8.3 KiB
8.3 KiB
name, description, argument-hint, agent
| name | description | argument-hint | agent |
|---|---|---|---|
| review-design | Review and validate SDLC Design document for consistency, completeness, and readiness for approval | 예: sdlc-001 또는 docs/sdlc/sdlc-001_20260417_stage-pilot/3_design.md | agent |
SDLC Design 문서를 체계적으로 검토하고, 승인 가능한 상태인지 판단한다.
목표:
3_design.md파일의 일관성 확인 (태스크/아키텍처/인터페이스/보안 간 중복 및 충돌)- 기술적 오류, 잘못된 표현, 명확하지 않은 문구 식별
- AI agent에게 할당된 플레이스홀더(
{{...}}) 중 판단/결정 가능한 항목 처리 - 플레이스홀더 중 사용자 결정이 정말 필요한 항목만 남겼는지 확인
- 최종 승인 가능 상태 판단
검토 절차
1. 입력 해석
- 사용자가 제공한 문서 경로 또는 CYCLE_ID에서
3_design.md파일 위치를 확정한다. - 파일이 없으면 입력값을 다시 확인하도록 사용자에게 피드백하고 중단한다.
2_planning.md도 함께 읽어 인계 내용의 정합성 확인에 사용한다.
2. Planning 인계 정합성 검토
# 1. Planning 인계 요약이 2_planning.md의 확정 내용과 일치하는지 확인한다.
- 태스크 목록(T-N 제목, 참조 요구사항)이 Planning
# 2와 내용/수량이 일치하는가 - 이월된 오픈 질문이 Planning
# 7의Deferred항목과 대응하는가 # 3상세 설계의 T-N 항목이# 1태스크 목록과 누락 없이 1:1 대응하는가
3. 저장소 현황 대조
3_design.md에 기술된 "현재 상태(개선 전)"가 실제 저장소와 일치하는지 확인한다.
3-1. 변경 대상 파일 존재 여부
# 3 상세 설계의 각 T-N 섹션에서 "변경 대상" 파일/함수 경로를 추출하고 실제 저장소에서 확인한다.
| 확인 항목 | 기준 |
|---|---|
| 수정 대상으로 명시된 파일 | 실제 저장소에 존재해야 한다. 없으면 경고 — 경로 오류 또는 신규 생성 여부를 명시하도록 요구 |
| 삭제 대상으로 명시된 파일 | 실제 저장소에 존재해야 한다. 없으면 경고 |
| 신규 생성 대상으로 명시된 파일 | 실제 저장소에 없어야 한다. 이미 존재하면 경고 — 수정 대상으로 재분류 필요 |
3-2. "현재 상태" 기술 정확성
# 3 상세 설계 및 # 4 인터페이스 정의에서 "현재 X 방식으로 동작한다", "현재 Y 함수가 Z를 반환한다" 등 현황을 기술한 문장을 찾아 실제 코드와 대조한다.
- 일치: 별도 표시 없이 통과
- 불일치: 해당 문장과 실제 코드를 나란히 제시하고 설계 문서 수정을 요구한다. 불일치 항목이 하나라도 있으면 최종 판단을 "보류(Hold)"로 설정한다.
- 확인 불가(파일이 너무 크거나 탐색 범위 초과): "확인 불가 — 수동 검토 권장" 으로 표시한다.
3-3. 인터페이스 시그니처 대조
# 4 인터페이스 정의에 "현재 시그니처"가 명시된 항목에 대해 실제 코드의 함수/메서드 시그니처와 대조한다.
- 파라미터 이름·타입·반환 타입이 일치하는지 확인한다.
- 불일치 시 실제 시그니처를 제시하고 설계 문서 수정을 요구한다.
5. 일관성 검토 (모든 섹션 대상)
- 태스크 번호 연속성:
# 1,# 2컴포넌트 영향 범위,# 3상세 설계의 T-N 번호가 누락 없이 연속이고 일치하는가 - 인터페이스 정합성:
# 3상세 설계에서 언급된 API/함수가# 4인터페이스 정의에 실제로 명시되었는가 - 보안 연결성:
# 3에서 입출력이 정의된 경우# 5보안 점검의 "입력값 검증(Injection)" 항목이 적절히 점검되었는가 - 숫자 연속성: R-N, DA-N, OQ-N 번호가 누락 없이 연속인지 확인
4. 표현 검토 (모든 텍스트)
- 문법: 문장 구조, 주술 호응, 시제 일관성
- 명확성: "적절히", "대략", "가능하면" 같은 모호한 표현 식별
- 작성 수준: 기술 문서 기준의 형식적 톤 유지. 비공식 표현 제거
- 오타: 한글 띄어쓰기, 숫자 오류, 테이블 형식 검증
6. 플레이스홀더 처리
모든 {{...}} 플레이스홀더를 나열하고 각 항목의 의도를 파악한다.
AI agent가 채울 수 있는 항목:
{{..._DECISION:...}}형태 — 문서 내 다른 섹션이나 Planning/저장소 정보로 추론 가능한지 확인- 컴포넌트 역할(
COMPONENT_N_ROLE), 데이터 흐름(DATA_FLOW_N), 엣지 케이스(DESIGN_EDGE_N) 등 구조적으로 추론 가능한 항목
사용자 결정이 필요한 항목 (플레이스홀더 유지):
- 태스크 담당자(
DESIGN_TASK_OWNER_N) - 외부 시스템 계약이 미확정인 인터페이스(
INTERFACE_N,SCHEMA_N) - Freeze 확정 담당자(
CONFIRMED_BY)
각 항목에 대해 아래 중 하나를 판단한다:
- 채울 수 있음: 문서 내 맥락, Planning 내용, 저장소 구조로 합리적 추론 가능 → 실제 내용으로 치환
- 판단 불가능: 사용자/승인자 결정, 외부 시스템 계약, 책임자 지정 필요 → 플레이스홀더 유지하되 명확성 강화
처리 결과를 별도 목록으로 보고한다.
7. 섹션별 최소 검수 기준
| 섹션 | 최소 기준 |
|---|---|
# 0 문서 상태 |
메타데이터 완성도 확인 (CREATED_AT_KST, PLANNING_PATH 채워졌는가) |
# 1 Planning 인계 요약 |
태스크 최소 1개 이상, Planning 태스크와 1:1 대응 여부 |
# 2 아키텍처/구조 설계 |
전체 구조 개요 1문단 이상, 주요 컴포넌트 1개 이상 |
# 3 상세 설계 |
모든 T-N 태스크에 설계 방향과 변경 대상이 있는가 |
# 4 인터페이스 정의 |
해당 없으면 "해당 없음" 명시, 있으면 함수/API 시그니처가 구체적인가 |
# 5 보안 고려사항 |
4개 항목(Injection/Auth/Data/Dep) 모두 해당/비해당 판정이 있는가, 해당 항목에 대응 방안이 있는가 |
# 6 리스크/가정/오픈 질문 |
리스크 1개 이상, 가정 1개 이상, OQ Open 상태가 있으면 종료 조건이 명시되었는가 |
# 7 확인 체크 |
체크 항목이 구체적이고 측정 가능한가 |
# 9 사용자 결정 필요 |
플레이스홀더가 실제 {{...}} 형식인가 (단순 문장 아닌가) |
# 10 Freeze |
Handoff Decision과 Rationale이 채워졌는가 |
8. 최종 승인 판단
- 승인 가능 (Ready for Implementation):
- 모든 T-N 태스크에 설계 방향과 변경 대상이 채워졌는가
- 인터페이스 계약이 구체적으로 명시되었는가
- 보안 점검 항목 중 "해당"은 모두 대응 방안이 있는가
# 6오픈 질문에Open상태 항목이 없거나 모두Deferred처리 완료인가- 남은 플레이스홀더는 모두 정당한가 (사용자/승인자 결정이 정말 필요)
- Freeze 플래그가 준비되었는가 (
READY_FOR_IMPLEMENTATION: true로 변경 가능한가) - 저장소 현황 대조에서 불일치 항목이 없는가 (3-2, 3-3)
- 조건부 (Pending Minor Changes):
- 일부 표현/인터페이스 초안만 수정하면 가능
- 보안 항목 중 근거가 빈약한 항목 보완 권장
- 저장소 현황 대조 결과 중 "확인 불가" 항목이 있어 수동 검토 권장
- 보류 (Hold):
- T-N 태스크 설계 방향 누락, 인터페이스 미정의, 보안 "해당" 항목에 대응 방안 없음, OQ
Open잔여 등 근본적 재검토 필요 - 저장소 현황 대조(3-2, 3-3)에서 불일치 항목이 하나라도 있는 경우
- T-N 태스크 설계 방향 누락, 인터페이스 미정의, 보안 "해당" 항목에 대응 방안 없음, OQ
응답 형식
-
검토 결과 요약
- Planning 인계 정합성 오류 (있으면 나열)
- 저장소 현황 대조 결과 (불일치/확인 불가 항목 나열, 없으면 "이상 없음")
- 발견된 일관성 오류 (있으면 나열)
- 표현/문법 오류 (있으면 나열)
- 섹션별 완성도 (예:
# 3상세 설계 — T-2 변경 대상 누락)
-
플레이스홀더 처리 결과
- 채워진 항목 (예:
{{COMPONENT_2_ROLE}}→ "Copilot 프롬프트 파일 등록·관리" 로 치환) - 유지된 항목 (예:
{{DESIGN_TASK_OWNER_1:TBD}}→ 담당자 지정 필요로 유지)
- 채워진 항목 (예:
-
수정 사항 목록 (적용된 변경)
-
최종 판단
- 승인 가능 / 조건부 / 보류
- 근거 및 남은 작업 사항