13 KiB
13 KiB
플레이스홀더 가이드
이 파일은 .github/templates/ 및 .github/prompts/에서 사용하는 {{...}} 플레이스홀더의 문법, 처리 주체, 전체 목록을 정의한다.
템플릿을 수정하거나 새 프롬프트를 작성할 때 이 파일을 기준으로 한다.
1. 문법 규칙
| 형식 | 의미 | 예시 |
|---|---|---|
{{KEY}} |
단순 치환 대상. 힌트 없음. | {{CYCLE_ID}} |
{{KEY:hint}} |
힌트 포함. 치환 시 힌트 텍스트도 함께 제거. | {{CREATED_AT_KST:TBD}} |
{{KEY:opt1|opt2|opt3}} |
열거형. 나열된 값 중 하나를 선택. | {{DOC_STATUS:draft|review|confirmed}} |
{{KEY_N_DECISION:hint}} |
AI agent가 섹션 본문에 임시로 삽입하는 판단 대기 마커. review-discovery 등 검토 단계에서 실제 문장으로 치환하거나 #10으로 이동. |
{{TARGET_STATE_2_DECISION:...}} |
규칙: 플레이스홀더를 채울 때는
{{...}}전체를 값으로 교체한다. 힌트나 파이프(|) 열거는 최종 문서에 남기지 않는다.
2. 처리 주체 분류
플레이스홀더는 누가 채워야 하는가에 따라 세 가지로 나뉜다.
A. 자동 치환 (Auto — 프롬프트 실행 시 agent가 즉시 채움)
| 키 | 치환 값 | 사용 위치 |
|---|---|---|
{{DOC_STATUS}} / {{DOC_STATUS:draft|review|confirmed}} |
draft |
모든 SDLC 문서 #0 |
{{CYCLE_ID}} / {{CYCLE_ID:sdlc-<3자리>_<YYYYMMDD>_<topic-slug>}} |
계산된 주기 ID | 모든 SDLC 문서 #0, index, summary |
{{ISSUE_NAME}} / {{ISSUE_NAME:...}} |
사용자 입력 원문 | 모든 SDLC 문서 #0, summary |
{{CREATED_AT_KST}} / {{CREATED_AT_KST:TBD}} |
현재 시각 (KST) | 모든 SDLC 문서 #0, summary |
{{UPDATED_AT_KST}} / {{UPDATED_AT_KST:TBD}} |
현재 시각 (KST) | 모든 SDLC 문서 #0, summary |
{{OUTPUT_PATH}} |
생성 파일 경로 | 1_discovery.md #9 |
{{FILE_RESULT}} / {{FILE_RESULT:생성|갱신|미생성}} |
생성 (신규) 또는 갱신 |
1_discovery.md #9 |
{{SUMMARY_STATUS}} / {{SUMMARY_STATUS:draft|review|confirmed}} |
draft |
summary.md |
B. AI 추론 치환 (Infer — agent가 입력 요청과 저장소 맥락을 바탕으로 초안을 채움)
입력만으로 합리적 추론이 가능한 항목은 플레이스홀더로 남기지 않고 자연어 문장으로 채운다. 추론이 불확실한 경우에는
_DECISION접미사 형태로 남기고review-discovery단계에서 처리한다.
| 키 | 설명 | 위치 |
|---|---|---|
{{PLANNING_SCORE_FILE}} |
Planning 점수 파일 경로 또는 미생성 |
#1 |
{{TODO_FILE}} |
관련 TODO/메모 경로 또는 없음 |
#1 |
{{SUMMARY_LINE_1}}, {{SUMMARY_LINE_2}} |
현재 검토 배경 및 이번 Discovery 핵심 요약 | #1 |
{{REQUIREMENT_CLASSIFICATION}} |
신규 / 유사 / 완전 중복 |
#2 |
{{CLASSIFICATION_REASON_1}}, {{CLASSIFICATION_REASON_2}} |
판정 근거 2줄 | #2 |
{{CURRENT_STATE_1}}, {{CURRENT_STATE_2}} |
현재 문제 상태 | #3 |
{{TARGET_STATE_1}}, {{TARGET_STATE_2}} |
기대 상태 | #3 |
{{STAKEHOLDER_1~3}} |
이해관계자 | #3 |
{{CONSTRAINT_1}}, {{CONSTRAINT_2}} |
제약사항 | #3 |
{{USER_SCENARIO_1~3}} |
주요 사용자 시나리오 | #3 |
{{CHANGE_ITEM_1~3}} |
핵심 변경 항목 | #4 |
{{CODE_IMPACT_1~2}}, {{DOC_IMPACT_1~2}}, {{OPS_IMPACT_1~2}} |
영향 범위 | #4 |
{{FR_1~4}} |
기능 요구사항 (최소 2개) | #5 |
{{NFR_1~3}} |
비기능 요구사항 (최소 1개) | #5 |
{{IN_SCOPE_1~2}}, {{OUT_OF_SCOPE_1~2}} |
범위 경계 | #5 |
{{RISK_LEVEL_1~3}}, {{RISK_1~3}}, {{MITIGATION_1~3}} |
리스크 항목 (최소 2개) | #6 |
{{ASSUMPTION_1~3}} |
가정 (최소 2개) | #6 |
{{OPEN_QUESTION_1~3}}, {{OPEN_QUESTION_STATUS_1~3}} |
오픈 질문 | #6 |
{{OPEN_QUESTION_ACTION_1~3}}, {{OPEN_QUESTION_EXIT_1~3}} |
오픈 질문 처리 방안/종료 조건 | #6 |
{{SUCCESS_METRIC_1~3}} |
성공 기준 (최소 2개) | #7 |
{{MEASURE_METHOD_1~3}}, {{MEASURE_SOURCE_1~3}} |
측정 방식 및 데이터 출처 | #7 |
{{CHECK_SCOPE_CRITERIA}} |
범위 확정 기준 | #8 |
{{CHECK_METRICS_CRITERIA}} |
성공 지표 확정 기준 | #8 |
{{CHECK_RISK_OWNER_CRITERIA}} |
리스크 책임자 지정 기준 | #8 |
{{CHECK_CONFIRMEDBY_CRITERIA}} |
Freeze 담당자 지정 기준 | #8 |
{{REFERENCE_1~3}} |
참조 문서 목록 | #9 |
{{SUMMARY_POINT_1~2}} |
summary.md 핵심 요약 | summary.md |
C. 사용자 결정 필요 (Decide — 자동 추론 불가, 사용자/승인자가 직접 채워야 함)
이 항목들은
#10 사용자 결정 필요 항목 요약에 모아서 관리한다. 섹션 본문에는 최소 플레이스홀더만 남기거나 맥락 설명 문장으로 대체한다.
| 키 | 설명 | 위치 |
|---|---|---|
{{DECIDE_ITEM_1~2}} |
정책/구조 결정이 필요한 항목 | #10 > DECIDE |
{{CONFIRM_ITEM_1~2}} |
범위나 책임자 확인이 필요한 항목 | #10 > CONFIRM |
{{DATA_ITEM_1~2}} |
외부 데이터나 환경 정보가 필요한 항목 | #10 > DATA |
{{FREEZE_HANDOFF_DECISION}} |
Planning 진행 가능 여부 (Planning 진행 가능 / 보류) |
#11 |
{{FREEZE_HANDOFF_RATIONALE}} |
Handoff Decision 판단 근거 | #11 |
{{READY_FOR_PLANNING}} |
true / false |
#11 |
{{CONFIRMED_BY}} |
Freeze 확정 담당자 이름 | #11 |
{{CONFIRMED_AT_KST}} |
Freeze 확정 시각 (KST) | #11 |
3. _DECISION 접미사 패턴
섹션 본문에 판단이 필요한 항목이 생겼을 때 AI agent가 임시로 삽입하는 마커이다.
- 형식:
{{원래키_N_DECISION:판단 내용 또는 질문}} - 예시:
{{TARGET_STATE_2_DECISION:README 확장으로 할지, 별도 파일로 분리할지 결정 필요}} - 처리 규칙:
review-discovery프롬프트 실행 시 각 항목을 검토하여 아래 중 하나로 처리한다.- 추론 가능 → 자연어 문장으로 치환
- 사용자 결정 필요 →
#10으로 이동하고 본문은 맥락 설명 문장으로 대체
Planning 전용 플레이스홀더 (2_planning.md)
A. 자동 치환 (Auto)
| 키 | 치환 값 | 사용 위치 |
|---|---|---|
{{DISCOVERY_PATH}} |
docs/sdlc/<CYCLE_ID>/1_discovery.md |
#0, #9 |
B. AI 추론 치환 (Infer)
| 키 | 설명 | 위치 |
|---|---|---|
{{PLANNING_ISSUE_PURPOSE}} |
Discovery 이슈명과 핵심 목적 요약 | #1 |
{{PLANNING_IN_SCOPE_1~2}} |
Discovery #5에서 이식한 In Scope |
#1 |
{{PLANNING_OUT_OF_SCOPE_1~2}} |
Discovery #5에서 이식한 Out of Scope |
#1 |
{{PLANNING_FR_1~4}} |
Discovery #5 FR 요약 |
#1 |
{{PLANNING_NFR_1~2}} |
Discovery #5 NFR 요약 |
#1 |
{{DEFERRED_ITEM_1~2}} |
Discovery #6에서 Deferred 처리된 오픈 질문 |
#1 |
{{TASK_TITLE_N}} |
FR/NFR 기반 태스크 제목 | #2 |
{{TASK_TYPE_N}} |
태스크 유형 (개발|문서|검토|설계|운영) |
#2 |
{{TASK_REF_N}} |
참조 요구사항 ID (예: FR-1) |
#2 |
{{TASK_DEP_N}} |
의존 태스크 ID 또는 - |
#2 |
{{TASK_DOD_N}} |
태스크 완료 조건 | #2 |
{{EFFORT_N}} |
추정 공수 (숫자 또는 범위) | #3 |
{{EFFORT_UNIT}} |
공수 단위 (SP|시간|일) |
#3 |
{{EFFORT_NOTE_N}} |
공수 추정 비고 | #3 |
{{TOTAL_EFFORT}} |
총 추정 공수 | #3 |
{{EFFORT_CONFIDENCE}} |
추정 신뢰도 (High|Medium|Low) |
#3 |
{{EFFORT_BASIS}} |
추정 근거 | #3 |
{{MILESTONE_N_NAME}} |
마일스톤 이름 | #4 |
{{MILESTONE_N_TASKS}} |
마일스톤 포함 태스크 목록 | #4 |
{{MILESTONE_N_DONE}} |
마일스톤 완료 조건 | #4 |
{{ITERATION_UNIT}} |
이터레이션 단위 | #4 |
{{ITERATION_N_TASKS}} |
이터레이션 N 포함 태스크 | #4 |
{{TASK_DEPENDENCY_N}} |
태스크 간 의존 관계 설명 | #5 |
{{EXTERNAL_DEP_N}} |
외부 의존성 항목 | #5 |
{{TECH_CONSTRAINT_N}} |
기술/환경 제약 | #5 |
{{VERIFY_CRITERIA_N}} |
검증 대상 성공 기준 (Discovery S-N 요약) | #6 |
{{VERIFY_METHOD_N}} |
검증 방법 초안 | #6 |
{{PLAN_RISK_LEVEL_N}} |
Planning 리스크 등급 | #7 |
{{PLAN_RISK_N}} |
Planning 리스크 내용 | #7 |
{{PLAN_MITIGATION_N}} |
리스크 완화 방안 | #7 |
{{PLAN_ASSUMPTION_N}} |
Planning 단계 가정 | #7 |
{{PLAN_OPEN_QUESTION_N}} |
Planning 오픈 질문 | #7 |
{{PLAN_OQ_STATUS_N}} |
오픈 질문 상태 | #7 |
{{PLAN_OQ_ACTION_N}} |
오픈 질문 처리 방안 | #7 |
{{PLAN_OQ_EXIT_N}} |
오픈 질문 종료 조건 | #7 |
{{CHECK_TASKS_CRITERIA}} |
태스크 확정 기준 | #8 |
{{CHECK_EFFORT_CRITERIA}} |
공수 추정 확정 기준 | #8 |
{{CHECK_SCHEDULE_CRITERIA}} |
일정 확정 기준 | #8 |
{{CHECK_DEP_CRITERIA}} |
외부 의존성 해소 기준 | #8 |
C. 사용자 결정 필요 (Decide)
| 키 | 설명 | 위치 |
|---|---|---|
{{TASK_OWNER_N}} |
태스크 담당자 | #2 |
{{MILESTONE_N_DATE}} |
마일스톤 목표 날짜 | #4 |
{{ITERATION_N_PERIOD}} |
이터레이션 날짜 범위 | #4 |
{{VERIFY_OWNER_N}} |
검증 담당자 | #6 |
{{FREEZE_HANDOFF_DECISION}} |
Design 진행 가능 여부 | #11 |
{{FREEZE_HANDOFF_RATIONALE}} |
Handoff Decision 판단 근거 | #11 |
{{READY_FOR_DESIGN}} |
true / false |
#11 |
{{CONFIRMED_BY}} |
Freeze 확정 담당자 이름 | #11 |
{{CONFIRMED_AT_KST}} |
Freeze 확정 시각 (KST) | #11 |
Design 전용 플레이스홀더 (3_design.md)
A. 자동 치환 (Auto)
| 키 | 치환 값 | 사용 위치 |
|---|---|---|
{{PLANNING_PATH}} |
docs/sdlc/<CYCLE_ID>/2_planning.md |
#0, #8 |
B. AI 추론 치환 (Infer)
| 키 | 설명 | 위치 |
|---|---|---|
{{DESIGN_ISSUE_PURPOSE}} |
Planning 이슈명과 핵심 목적 요약 | #1 |
{{DESIGN_TASK_TITLE_N}} |
Planning #2에서 이식한 태스크 제목 |
#1 |
{{DESIGN_TASK_REF_N}} |
Planning #2에서 이식한 참조 요구사항 |
#1 |
{{DESIGN_DEFERRED_ITEM_N}} |
Planning #7에서 Deferred 처리된 오픈 질문 |
#1 |
{{ARCH_OVERVIEW}} |
전체 아키텍처/구조 개요 | #2 |
{{COMPONENT_N_NAME}} |
주요 컴포넌트 이름 | #2 |
{{COMPONENT_N_ROLE}} |
컴포넌트 역할 | #2 |
{{COMPONENT_N_SCOPE}} |
컴포넌트 영향 범위 | #2 |
{{DATA_FLOW_N}} |
데이터 흐름 단계 | #2 |
{{DESIGN_DETAIL_N}} |
태스크별 설계 방향 | #3 |
{{DESIGN_TARGET_N}} |
변경 대상 파일/함수/설정 | #3 |
{{DESIGN_IO_N}} |
입력/출력 또는 사이드이펙트 | #3 |
{{DESIGN_EDGE_N}} |
예외/엣지 케이스 | #3 |
{{INTERFACE_N}} |
API/함수 시그니처 | #4 |
{{SCHEMA_N}} |
데이터 스키마/포맷 | #4 |
{{EVENT_N}} |
이벤트/메시지 | #4 |
{{SEC_INJECTION}} ~ {{SEC_OTHER}} |
보안 항목 해당 여부 | #5 |
{{SEC_INJECTION_ACTION}} ~ {{SEC_OTHER_ACTION}} |
보안 대응 방안 | #5 |
{{DESIGN_RISK_LEVEL_N}} |
Design 리스크 등급 | #6 |
{{DESIGN_RISK_N}} |
Design 리스크 내용 | #6 |
{{DESIGN_MITIGATION_N}} |
리스크 완화 방안 | #6 |
{{DESIGN_ASSUMPTION_N}} |
Design 단계 가정 | #6 |
{{DESIGN_OPEN_QUESTION_N}} |
Design 오픈 질문 | #6 |
{{DESIGN_OQ_STATUS_N}} |
오픈 질문 상태 | #6 |
{{DESIGN_OQ_ACTION_N}} |
오픈 질문 처리 방안 | #6 |
{{DESIGN_OQ_EXIT_N}} |
오픈 질문 종료 조건 | #6 |
{{CHECK_DESIGN_COMPLETE}} |
설계 완성 기준 | #7 |
{{CHECK_INTERFACE}} |
인터페이스 확정 기준 | #7 |
{{CHECK_SECURITY}} |
보안 점검 완료 기준 | #7 |
C. 사용자 결정 필요 (Decide)
| 키 | 설명 | 위치 |
|---|---|---|
{{DESIGN_TASK_OWNER_N}} |
태스크 담당자 | #1 |
{{FREEZE_HANDOFF_DECISION}} |
Implementation 진행 가능 여부 | #10 |
{{FREEZE_HANDOFF_RATIONALE}} |
Handoff Decision 판단 근거 | #10 |
{{READY_FOR_IMPLEMENTATION}} |
true / false |
#10 |
{{CONFIRMED_BY}} |
Freeze 확정 담당자 이름 | #10 |
{{CONFIRMED_AT_KST}} |
Freeze 확정 시각 (KST) | #10 |
4. 참조 위치 요약
| 파일 | 역할 | 관련 플레이스홀더 |
|---|---|---|
.github/prompts/new-sdlc.prompt.md |
주기 생성, 자동/추론 치환 실행 | A, B 전체 |
.github/prompts/review-discovery.prompt.md |
검토, _DECISION 처리, 사용자 결정 항목 정리 |
B (_DECISION), C |
.github/prompts/draft-planning.prompt.md |
Planning 초안 생성, Discovery 내용 이식 | A, B 전체 (Planning) |
.github/prompts/draft-design.prompt.md |
Design 초안 생성, Planning 내용 이식 | A, B 전체 (Design) |
.github/templates/sdlc/1_discovery.md |
Discovery 원본 템플릿 | A, B, C 전체 |
.github/templates/sdlc/2_planning.md |
Planning 원본 템플릿 | A, B, C 전체 (Planning) |
.github/templates/sdlc/3_design.md |
Design 원본 템플릿 | A, B, C 전체 (Design) |