portfolio-hub/.github/instructions/placeholder-guide.md

플레이스홀더 가이드

이 파일은 .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)