|
|
|
@@ -0,0 +1,202 @@
|
|
|
|
|
# 0. 문서 상태
|
|
|
|
|
이 문서의 현재 상태와 식별 정보를 기록한다. 문서 추적과 승인 흐름에 필요한 최소 메타데이터를 적는다.
|
|
|
|
|
|
|
|
|
|
- 상태: draft
|
|
|
|
|
- 문서 ID: sdlc-001_20260417_stage-pilot
|
|
|
|
|
- 이슈명: stage-pilot 프로젝트의 사용 설명서 작성
|
|
|
|
|
- 작성 시각(KST): 2026-04-17 13:45:58 KST
|
|
|
|
|
- 마지막 갱신 시각(KST): 2026-04-17 14:12:00 KST
|
|
|
|
|
|
|
|
|
|
# 1. 계획 상태 요약
|
|
|
|
|
현재 Discovery가 어떤 배경에서 작성되고 있는지, 연계 문서가 있는지, 지금 시점의 해석이 무엇인지 짧게 요약한다.
|
|
|
|
|
|
|
|
|
|
- 연계 문서 현황:
|
|
|
|
|
- Planning 점수 파일: 미생성
|
|
|
|
|
- 관련 TODO/메모: 없음
|
|
|
|
|
- 해석:
|
|
|
|
|
- stage-pilot 저장소를 처음 도입하거나 업데이트하려는 사용자가 설치, 업데이트, SDLC 프롬프트 사용법을 빠르게 이해할 수 있도록 공식 사용 설명서가 필요하다.
|
|
|
|
|
- 이번 Discovery에서는 README 중심의 사용 설명서를 어떤 범위와 수준으로 작성할지 정의하고, 설치 절차와 운영성 정보를 문서 구조에 반영할 기준을 정해야 한다.
|
|
|
|
|
|
|
|
|
|
# 2. 요구사항 판정 결과
|
|
|
|
|
이번 요청이 기존 요구사항과 비교해 신규인지, 유사한지, 중복인지 판단하고 그 근거를 남긴다.
|
|
|
|
|
|
|
|
|
|
- 판정: 신규
|
|
|
|
|
- 근거
|
|
|
|
|
- 현재 저장소에는 기본 사용방법과 SDLC 프롬프트 요약은 있으나, 프로젝트 전체 사용 설명서를 별도 산출물로 정의한 SDLC 주기나 관련 문서 세트가 존재하지 않는다.
|
|
|
|
|
- 요청은 기존 README 보완 수준을 넘어 설치, 업데이트, 프롬프트 사용 흐름을 체계화하는 신규 문서 작업으로 해석하는 것이 합리적이다.
|
|
|
|
|
|
|
|
|
|
# 3. 문제점의 요약
|
|
|
|
|
문제의 현재 상태, 기대 상태, 관련 이해관계자, 제약사항을 정리한다. Discovery의 핵심 맥락을 가장 먼저 이해할 수 있어야 한다.
|
|
|
|
|
|
|
|
|
|
- 현재 상태
|
|
|
|
|
- README에 최초 등록, 업데이트, SDLC 프롬프트 사용법이 간단히 정리되어 있지만, 사용자의 목표별 진입 경로와 단계별 설명이 충분히 구조화되어 있지 않다.
|
|
|
|
|
- 설치 스크립트와 운영 흐름은 존재하지만 어떤 순서로 실행해야 하는지, 어떤 상황에서 어떤 명령을 선택해야 하는지에 대한 사용 설명서가 부족하다.
|
|
|
|
|
- 기대 상태
|
|
|
|
|
- 신규 사용자가 저장소 도입부터 업데이트, SDLC 프롬프트 실행까지를 하나의 사용 설명서만 읽고 재현 가능하게 따라갈 수 있어야 한다.
|
|
|
|
|
- 사용 설명서의 위치(README 확장 또는 별도 문서)가 확정된 후, 사용자가 해당 위치에서 설치/업데이트 절차와 참고 문서를 빠르게 찾을 수 있어야 한다.
|
|
|
|
|
- 이해관계자
|
|
|
|
|
- 문서 작성자(AI agent 또는 프로젝트 유지보수자)
|
|
|
|
|
- 저장소를 도입하는 개발자 또는 팀
|
|
|
|
|
- stage-pilot 운영/관리 담당자
|
|
|
|
|
- 제약사항
|
|
|
|
|
- 현재 확인 가능한 근거 문서는 README와 bootstrap 스크립트, 프롬프트/템플릿 구조로 제한되므로 세부 운영 정책은 추후 확인이 필요할 수 있다.
|
|
|
|
|
- 사용 설명서는 실제 저장소 구조와 스크립트 동작을 기준으로 작성해야 하며, 존재하지 않는 자동화나 미확인 절차를 단정적으로 문서화하면 안 된다.
|
|
|
|
|
|
|
|
|
|
## 주요 사용자 시나리오
|
|
|
|
|
사용자 또는 운영자가 실제로 어떤 상황에서 이 변경을 필요로 하는지 대표 시나리오를 적는다.
|
|
|
|
|
|
|
|
|
|
- 신규 팀원이 stage-pilot을 기존 저장소에 연결하고 bootstrap 설치를 적용하기 위해 공식 사용 설명서를 따라 최초 설정을 수행한다.
|
|
|
|
|
- 기존 사용자가 stage-pilot subtree를 최신 상태로 갱신하면서 `--no-overwrite`, `--skip-install` 같은 옵션 차이를 확인한다.
|
|
|
|
|
- Copilot Chat 사용자가 어떤 프롬프트를 어떤 순서로 실행해야 하는지 이해하기 위해 SDLC 실행 흐름과 예시 명령을 참조한다.
|
|
|
|
|
|
|
|
|
|
# 4. 이번에 정의할 변경
|
|
|
|
|
이번 Discovery에서 다루는 핵심 변경 항목을 목록으로 적는다. 기능, 구조, 규칙 변경을 함께 포함해도 된다.
|
|
|
|
|
|
|
|
|
|
- stage-pilot의 설치, 업데이트, SDLC 프롬프트 사용 흐름을 설명하는 공식 사용 설명서의 초안 범위를 정의한다.
|
|
|
|
|
- 기존 README와 bootstrap 스크립트 기준으로 사용자 관점의 작업 절차와 주요 명령 예시를 문서 구조에 반영한다.
|
|
|
|
|
- 향후 Planning에서 문서 위치, 섹션 구성, 검증 방법을 세분화할 수 있도록 문서 산출물과 성공 기준의 기준선을 세운다.
|
|
|
|
|
|
|
|
|
|
## 영향 범위
|
|
|
|
|
변경이 미칠 코드/문서/운영 범위를 명시해 Planning에서 추정 누락을 줄인다.
|
|
|
|
|
|
|
|
|
|
- 코드 영향:
|
|
|
|
|
- 코드 변경 자체는 제한적이거나 없을 가능성이 높지만, 문서 경로를 README에서 연결하거나 프롬프트 안내 문구를 조정하는 변경이 필요할 수 있다.
|
|
|
|
|
- bootstrap 스크립트 사용 예시와 실제 옵션 동작의 일치 여부를 확인하기 위한 점검이 필요하다.
|
|
|
|
|
- 문서 영향:
|
|
|
|
|
- README 또는 별도 사용 설명서 문서가 새로 작성되거나 대폭 보강될 수 있다.
|
|
|
|
|
- SDLC 관련 안내 문서와 시작 가이드에서 사용 설명서 링크를 추가해야 할 수 있다.
|
|
|
|
|
- 운영 영향:
|
|
|
|
|
- 배포/운영 절차 변경은 없으나, 문서가 최신 상태로 유지되도록 이후 업데이트 시 문서 동기화 책임이 필요하다.
|
|
|
|
|
- 사용자 문의 대응 시 참조 기준 문서가 새로 생기므로 운영 커뮤니케이션 비용이 줄어들 수 있다.
|
|
|
|
|
|
|
|
|
|
# 5. 요구사항 목록
|
|
|
|
|
실제로 구현과 검증으로 이어질 요구사항을 기능/비기능으로 나누어 정리하고, 범위 경계를 명확히 적는다.
|
|
|
|
|
|
|
|
|
|
## 기능 요구사항
|
|
|
|
|
- FR-1: 사용 설명서는 stage-pilot의 최초 등록 절차를 리모트 등록, subtree 추가, bootstrap 설치 순서대로 설명해야 한다.
|
|
|
|
|
- FR-2: 사용 설명서는 업데이트 절차를 기본 업데이트, 덮어쓰기 방지, 원격 URL 직접 사용, 설치 생략 옵션으로 구분해 설명해야 한다.
|
|
|
|
|
- FR-3: 사용 설명서는 Copilot Chat 기반 SDLC 프롬프트의 기본 실행 순서와 대표 명령 예시를 포함해야 한다.
|
|
|
|
|
- FR-4: 사용 설명서는 사용자가 추가 참고 문서를 찾을 수 있도록 관련 파일 또는 디렉터리 위치를 명시해야 한다.
|
|
|
|
|
|
|
|
|
|
## 비기능 요구사항
|
|
|
|
|
성능, 운영성, 일관성, 자동화 안정성 등 기능 외 요구사항을 적는다.
|
|
|
|
|
|
|
|
|
|
- NFR-1: 문서 내용은 현재 저장소에 실제 존재하는 파일, 스크립트, 명령만 기준으로 작성되어야 한다.
|
|
|
|
|
- NFR-2: 문서는 신규 사용자가 한 번에 읽을 수 있도록 작업 흐름 중심으로 구조화되어야 하며, 명령 예시는 복사 가능한 형태로 제공되어야 한다.
|
|
|
|
|
- NFR-3: README 및 관련 가이드와 용어가 일관되어야 하며, 단계 명칭과 문서 ID 규칙이 서로 충돌하지 않아야 한다.
|
|
|
|
|
|
|
|
|
|
## 범위 경계
|
|
|
|
|
이번 반복에서 반드시 포함할 범위와 명시적으로 제외할 범위를 구분한다.
|
|
|
|
|
|
|
|
|
|
- In Scope
|
|
|
|
|
- stage-pilot 저장소 사용 설명서의 목적, 주요 섹션, 포함할 명령/예시 범위 정의
|
|
|
|
|
- 설치, 업데이트, SDLC 프롬프트 사용 흐름에 대한 초안 수준의 문서 요구사항 정리
|
|
|
|
|
- Out of Scope
|
|
|
|
|
- bootstrap 스크립트의 기능 변경 또는 신규 자동화 추가
|
|
|
|
|
- README 외 별도 웹 문서 사이트 구축이나 다국어 번역 지원 (후속 반복에서 검토)
|
|
|
|
|
|
|
|
|
|
# 6. 리스크/가정 목록
|
|
|
|
|
불확실성과 전제 조건을 분리해서 적는다. 리스크는 영향과 완화 방안을, 가정은 현재 판단의 전제를 기록한다.
|
|
|
|
|
|
|
|
|
|
## 리스크
|
|
|
|
|
- R-1 (Medium): 사용 설명서가 README의 현재 내용만 재서술하고 실제 사용자 질문에 필요한 맥락을 충분히 추가하지 못할 수 있다.
|
|
|
|
|
- 완화 방안: Planning 단계에서 사용자 작업 시나리오 기준의 섹션 구조와 예시 수준을 명확히 정의한다.
|
|
|
|
|
- R-2 (Medium): 스크립트 옵션이나 프롬프트 예시가 실제 최신 동작과 어긋나면 문서 신뢰도가 떨어질 수 있다.
|
|
|
|
|
- 완화 방안: 문서 작성 전에 bootstrap 스크립트와 프롬프트 정의 파일을 대조해 명령과 옵션을 검증한다.
|
|
|
|
|
- R-3 (Low): 문서 위치가 README 확장인지 별도 가이드 문서인지 결정되지 않으면 이후 링크 구조가 바뀔 수 있다.
|
|
|
|
|
- 완화 방안: 사용자 결정 필요 항목으로 위치 정책을 확인하고, 확정 전까지는 문서 산출물 형태를 초안 수준으로 유지한다.
|
|
|
|
|
|
|
|
|
|
## 가정
|
|
|
|
|
아직 확정되지 않았지만 현재 문서 작성의 기반이 되는 전제를 적는다.
|
|
|
|
|
|
|
|
|
|
- A-1: 이번 작업의 1차 산출물은 개발자 중심의 사용 설명서이며, 운영자/리뷰어 안내까지 포함하는 범위는 Planning 이후 반복에서 검토한다.
|
|
|
|
|
- A-2: 설치 및 업데이트 절차의 정본은 현재 README와 bootstrap 스크립트이며, 사용 설명서는 이를 재구성해 설명하는 형태가 된다.
|
|
|
|
|
- A-3: 문서 초안은 우선 한국어 기준으로 작성해도 무방하며, 영문 병행 여부는 후속 결정 사항이다.
|
|
|
|
|
|
|
|
|
|
## 오픈 질문
|
|
|
|
|
답을 아직 모르는 항목을 적는다. 추정으로 덮지 말고 Planning 이전에 확인할 질문으로 남긴다.
|
|
|
|
|
|
|
|
|
|
- OQ-1: 사용 설명서를 README 확장으로 작성할지, 별도 문서 파일로 분리할지 최종 산출물 위치를 어디로 할 것인가?
|
|
|
|
|
- 상태: Open
|
|
|
|
|
- 처리 방안: 사용자 또는 승인자가 문서 배치 정책을 결정한다.
|
|
|
|
|
- 종료 조건: Planning 시작 전 최종 산출물 경로가 확정된다.
|
|
|
|
|
- OQ-2: 사용 설명서에 포함할 대상 독자 범위를 개발자 전용으로 제한할지, 운영자/리뷰어 안내까지 포함할지 확정할 필요가 있는가?
|
|
|
|
|
- 상태: Open
|
|
|
|
|
- 처리 방안: 사용자와 범위 경계를 확인해 In Scope를 확정한다.
|
|
|
|
|
- 종료 조건: 대상 독자와 제외 범위가 승인된다.
|
|
|
|
|
|
|
|
|
|
### 오픈 질문 처리 기준
|
|
|
|
|
- `Open`: 아직 답이 없고 다음 단계 진행에 영향이 있는 상태다. 문서에 유지한다.
|
|
|
|
|
- `Answered`: 답이 확정된 상태다. 관련 본문/요구사항에 반영한 뒤 오픈 질문 목록에서는 제거하거나 resolved 기록으로 이동한다.
|
|
|
|
|
- `Deferred`: 지금 단계에서 결정하지 않고 다음 단계 또는 후속 이슈로 넘기는 상태다. 넘길 대상과 이유를 반드시 적는다.
|
|
|
|
|
- `Dropped`: 더 이상 유효하지 않은 질문이다. 삭제 사유를 짧게 남기고 목록에서 제거한다.
|
|
|
|
|
- 처리 원칙 1: 질문만 남기지 말고 반드시 `상태`, `처리 방안`, `종료 조건`을 함께 적는다.
|
|
|
|
|
- 처리 원칙 2: 답이 나온 질문은 본문 반영 없이 단순 삭제하지 않는다. 반영 위치를 먼저 갱신한다.
|
|
|
|
|
- 처리 원칙 3: High 영향 질문은 `Deferred` 처리 후 처리 방안에 Planning 인계 추적 방식을 명시한다.
|
|
|
|
|
|
|
|
|
|
# 7. 초기 성공 기준
|
|
|
|
|
이 변경이 성공했다고 판단할 기준을 측정 가능하게 정의한다. 가능하면 데이터 출처까지 연결한다.
|
|
|
|
|
|
|
|
|
|
- S-1: 사용 설명서 초안에 최초 등록, 업데이트, SDLC 프롬프트 사용 흐름이 모두 포함되어 있다.
|
|
|
|
|
- S-2: 사용 설명서 초안의 각 주요 절차에 대해 사용자가 실행 가능한 명령 예시 또는 참조 경로를 확인할 수 있다.
|
|
|
|
|
- S-3: 문서 검토 시 실제 저장소 구조와 맞지 않는 경로 또는 존재하지 않는 명령이 발견되지 않는다.
|
|
|
|
|
|
|
|
|
|
## 측정 방식 및 데이터 출처
|
|
|
|
|
각 성공 기준을 어떻게 측정할지와 어떤 데이터나 문서를 근거로 쓸지 적는다.
|
|
|
|
|
|
|
|
|
|
- S-1 측정 방식: 문서 섹션 체크리스트로 포함 여부 검토 / 데이터 출처: README, bootstrap 스크립트, 프롬프트 정의 파일
|
|
|
|
|
- S-2 측정 방식: 절차별 예시 명령과 링크 존재 여부 수동 검토 / 데이터 출처: 사용 설명서 초안, README
|
|
|
|
|
- S-3 측정 방식: 경로/명령 대조 검토 또는 샘플 실행 검토 / 데이터 출처: 저장소 파일 구조, bootstrap/*.sh, .github/prompts/
|
|
|
|
|
|
|
|
|
|
# 8. Planning으로 넘기기 전 확인 체크
|
|
|
|
|
Planning 단계로 넘기기 전에 무엇이 확정되어야 하는지 확인한다. 미완료 항목은 후속 결정이 필요함을 뜻한다.
|
|
|
|
|
|
|
|
|
|
- [ ] 범위(In Scope/Out of Scope) 확정
|
|
|
|
|
- 기준: 최종 독자와 포함 대상 문서 범위가 승인되어야 한다.
|
|
|
|
|
- [ ] 성공 지표의 측정 방식/데이터 출처 확정
|
|
|
|
|
- 기준: 샘플 실행 여부와 문서 검토 체크리스트의 적용 방법이 정리되어야 한다.
|
|
|
|
|
- [ ] High 영향 리스크 우선순위 및 해소 책임자 지정
|
|
|
|
|
- 기준: 문서 정확성 검증 책임자 또는 검토 방식이 지정되어야 한다.
|
|
|
|
|
- [ ] 모든 오픈 질문(OQ) `Open` 상태 없음 확인
|
|
|
|
|
- 기준: OQ 목록에 `Open` 상태 항목이 0개이거나, 잔여 항목 전부 `Deferred` 처리 완료
|
|
|
|
|
- [ ] Freeze 확정 담당자(CONFIRMED_BY) 지정
|
|
|
|
|
- 기준: 문서 승인 또는 인계 결정을 내릴 담당자가 명시되어야 한다.
|
|
|
|
|
|
|
|
|
|
# 9. 파일 처리 결과
|
|
|
|
|
이 Discovery 문서 생성/갱신 결과와 참조 문서를 기록한다. 이후 추적과 리뷰 시 근거로 사용한다.
|
|
|
|
|
|
|
|
|
|
- 처리 결과: 생성
|
|
|
|
|
- 생성 경로: docs/sdlc/sdlc-001_20260417_stage-pilot/1_discovery.md
|
|
|
|
|
- 참조 문서:
|
|
|
|
|
- README.md
|
|
|
|
|
- 없음
|
|
|
|
|
|
|
|
|
|
# 10. 사용자 결정 필요 항목 요약
|
|
|
|
|
사용자나 승인자가 결정해야 하는 항목만 모아 정리한다. 결정, 확인, 데이터 요청을 구분해서 적는다.
|
|
|
|
|
|
|
|
|
|
## DECIDE
|
|
|
|
|
- 사용 설명서 최종 산출물을 README 확장으로 할지, 별도 문서 파일로 분리할지 결정
|
|
|
|
|
|
|
|
|
|
## CONFIRM
|
|
|
|
|
- 대상 독자 범위를 개발자 전용으로 한정할지, 운영자/리뷰어 역할까지 포함할지 확인
|
|
|
|
|
- 승인 및 Freeze 확정 책임자 지정 (섹션 11의 CONFIRMED_BY에 입력)
|
|
|
|
|
|
|
|
|
|
## DATA
|
|
|
|
|
- 성공 기준 #S-3 검증 시 샘플 실행 환경 및 검증 기록 방식 확인
|
|
|
|
|
|
|
|
|
|
# 11. Discovery Freeze
|
|
|
|
|
Planning 인계 시점의 확정 플래그와 섹션 참조만 기록한다. 내용 재작성 없이 원본 섹션을 링크로 대신한다.
|
|
|
|
|
|
|
|
|
|
## 섹션 참조
|
|
|
|
|
- 범위: [# 5. 요구사항 목록 > 범위 경계](#5-요구사항-목록)
|
|
|
|
|
- 리스크/오픈 질문: [# 6. 리스크/가정 목록](#6-리스크가정-목록)
|
|
|
|
|
- 성공 기준: [# 7. 초기 성공 기준](#7-초기-성공-기준)
|
|
|
|
|
- 인계 전 확인: [# 8. Planning으로 넘기기 전 확인 체크](#8-planning으로-넘기기-전-확인-체크)
|
|
|
|
|
- 사용자 결정 필요: [# 10. 사용자 결정 필요 항목 요약](#10-사용자-결정-필요-항목-요약)
|
|
|
|
|
|
|
|
|
|
## Freeze 플래그
|
|
|
|
|
- Handoff Decision: 보류
|
|
|
|
|
- Handoff Rationale: 초기 Discovery 초안 생성 완료, Planning 인계 전 사용자 확인 필요
|
|
|
|
|
- Ready for Planning: false
|
|
|
|
|
- Confirmed By: TBD
|
|
|
|
|
- Confirmed At (KST): TBD
|
