Squashed '.vendor/myagent-kit/' content from commit 96defc9

git-subtree-dir: .vendor/myagent-kit git-subtree-split: 96defc92f92d617a80f7b0f54e998ce4c25f631b
2026-04-13 23:25:23 +09:00
commit acd1bab8f2
19 changed files with 1058 additions and 0 deletions
@@ -0,0 +1,152 @@
+# myagent-kit
+
+Reusable Copilot Development workflow assets.
+
+## Contents
+- `base/.github/prompts`: reusable prompts
+- `base/.github/instructions`: reusable file instructions
+- `base/.github/ISSUE_TEMPLATE`: reusable issue templates
+- `base/.github/copilot-instructions.md`: managed Copilot baseline gate template (opt-in merge)
+- `base/.github/pull_request_template.md`: PR traceability gate template
+- `templates/docs/SRS/REQ-template.md`: REQ starter template
+- `templates/docs/SRS/TRACEABILITY-template.md`: traceability matrix starter template
+- `bootstrap/install.sh`: copy base assets into a target project
+
+### Pre-flight Scope Decision (Step 0)
+새 기능이나 변경 요청이 들어오면, requirement drafting을 시작하기 **전에** 먼저 아래 명령으로 SRS 대상 여부를 판정한다.
+
+| Asset | 용도 |
+|---|---|
+| `base/.github/prompts/decide-requirement-scope.prompt.md` | 변경 요청을 입력받아 4종 판정 결과 반환 |
+| `base/.github/instructions/requirement-scope-decision.instructions.md` | 판정 기준 및 출력 형식 가이드 |
+| `base/.github/prompts/reopen-requirement-status.prompt.md` | `Approved/Implemented/Deprecated` requirement를 `Proposed`(또는 `Re-review`)로 되돌리기 위한 결정/충돌 검토 |
+| `base/.github/instructions/reopen-requirement-discovery.instructions.md` | REQ 미지정 입력 시 후보 탐색(키워드/점수/동점 처리) 커스터마이징 가이드 |
+
+**판정 결과 4종**
+1. `New SRS requirement needed` — 새 REQ 문서 작성
+2. `Update existing SRS requirement` — 기존 REQ 문서 수정
+3. `Technical spec only` — SRS 변경 없이 technical spec만 업데이트
+4. `Needs owner decision` — 운영 리스크/책임이 불명확하여 소유자 결정 필요
+
+## Install into a project
+
+```bash
+bash .vendor/myagent-kit/bootstrap/install.sh /path/to/project
+```
+
+변경 적용 없이 계획만 확인하려면 dry-run을 사용한다.
+
+```bash
+bash .vendor/myagent-kit/bootstrap/install.sh /path/to/project --dry-run
+```
+
+옵션: 기존 `.github/copilot-instructions.md`를 덮어쓰지 않고 병합하려면 opt-in 플래그를 사용한다.
+
+```bash
+bash .vendor/myagent-kit/bootstrap/install.sh /path/to/project --merge-copilot-instructions
+```
+
+병합 정책 요약:
+- marker 이름은 `myagent-kit`로 고정된다.
+- 기존 파일이 있으면 `.github/copilot-instructions.md.bak`으로 최근 1개 백업 후 병합한다.
+- 병합은 `myagent-kit` 관리 섹션만 갱신하고 `project-specific` 섹션은 유지한다.
+- marker 쌍이 손상된 경우 병합을 중단하고 백업본으로 롤백한다.
+
+In subtree-based usage:
+
+```bash
+git subtree add --prefix=.vendor/myagent-kit https://github.com/<owner>/myagent-kit.git main --squash
+bash .vendor/myagent-kit/bootstrap/install.sh .
+bash .vendor/myagent-kit/bootstrap/install.sh . --dry-run
+bash .vendor/myagent-kit/bootstrap/install.sh . --merge-copilot-instructions
+bash .vendor/myagent-kit/bootstrap/install.sh . --merge-copilot-instructions --dry-run
+```
+
+## 운영 규칙
+
+- SRS는 계약 문서, 구현 문서는 실행 기록으로 분리합니다.
+- 모든 요구사항에 고유 ID를 부여합니다. 예: REQ-001
+- 구현/테스트/릴리즈까지 같은 ID를 계속 사용합니다.
+- 상태 기반으로 관리합니다: Draft → Approved → Implemented → Verified → Released
+
+## 추적/운영 표준
+
+### 1) 식별자 규칙
+- Requirement ID는 `REQ-XXX` 형식을 사용합니다. 예: `REQ-001`
+- Acceptance Criteria는 requirement 내부에서 `AC1`, `AC2`처럼 번호를 고정합니다.
+- 이슈/PR 제목에는 requirement ID를 포함합니다. 예: `[REQ-001] ...`
+
+### 2) 증거(Evidence) 연결 규칙
+- 구현 이슈에는 `Acceptance Criteria Mapping`을 작성합니다. (`ACx -> Task`)
+- PR에는 어떤 AC가 어떤 변경으로 충족되었는지 명시합니다.
+- 테스트 이름 또는 테스트 설명에도 requirement ID를 포함합니다.
+- 릴리즈 노트에는 포함된 requirement ID 목록을 남깁니다.
+
+### 3) 추적 문서 운영
+- 추적 매트릭스는 `docs/SRS/traceability-matrix.md`로 운영합니다.
+- 초기 작성은 `templates/docs/SRS/TRACEABILITY-template.md`를 복사해 사용합니다.
+- 매트릭스의 각 행은 최소한 `REQ ID`, `AC`, `Issue/PR`, `Test`, `Status`를 채웁니다.
+
+### 4) 최소 운영 절차
+1. Requirement 작성 및 ID 확정
+2. Requirement를 `Approved`로 전환
+3. Implementation Issue 생성 (AC 매핑 포함)
+4. PR 생성 (REQ/AC 충족 근거 기입)
+5. 테스트 증거 업데이트
+6. Requirement 상태를 `Implemented`/`Verified`로 전환
+7. 릴리즈 시 매트릭스와 릴리즈 노트에 REQ ID 반영
+
+## myagent-kit Development Life Cycle
+
+### Phase 0. Workspace Bootstrap
+- 프로젝트에 myagent-kit 자산을 설치한다.
+- `bootstrap/install.sh`를 실행해 `.github` 워크플로 자산을 동기화한다.
+
+### Phase 0.5. Pre-flight Scope Decision *(새 기능/변경 요청 진입 시 필수)*
+- `decide-requirement-scope.prompt.md`로 변경 요청이 SRS 대상인지 먼저 판정한다.
+- 판정 결과에 따라 다음 단계를 결정한다.
+  - `New SRS requirement needed` → Phase 1로 진행
+  - `Update existing SRS requirement` → 해당 REQ 파일을 수정하고 Phase 2로 진행
+  - `Technical spec only` → SRS 변경 없이 technical spec / implementation note만 업데이트
+  - `Needs owner decision` → 소유자와 협의 후 위 3가지 중 하나로 재판정
+
+### Phase 1. Requirement Drafting
+- `templates/docs/SRS/REQ-template.md`로 REQ 문서를 작성한다.
+- REQ ID(`REQ-XXX`)를 확정하고, `Acceptance Criteria`를 test 가능한 문장으로 작성한다.
+
+### Phase 2. Requirement Quality Gate
+- `validate-requirement.prompt.md`로 requirement 품질 검토를 수행한다.
+- 모호성, 누락 필드, impacted area, change log 누락을 수정한다.
+
+### Phase 3. Requirement Approval Gate
+- `approve-requirement.prompt.md`로 `Proposed -> Approved` 전환 가능 여부를 확인한다.
+- 승인 이력(Change Log)을 남기고 상태를 `Approved`로 변경한다.
+
+### Phase 3.5. Requirement Reopen / Re-review
+- 구현 전/후에 계약 변경, acceptance criteria 재정의, 리스크 재평가가 필요하면 `reopen-requirement-status.prompt.md`를 사용한다.
+- 입력 예시: `REQ-003, REQ-011; API 응답 필드 계약을 다시 정리해야 해서 재검토 필요`.
+- 결과에서 사용자 결정 항목(목표 상태: `Proposed` vs `Re-review`)과 충돌 후보 REQ를 먼저 확인한 뒤 REQ 문서/인덱스를 수정한다.
+
+### Phase 4. Pre-Implementation Design Review
+- Implementation Issue를 생성하고 설계검토 체크리스트를 작성한다.
+- 아키텍처, 인터페이스, 데이터, 오류 처리, 보안/성능, 테스트 전략을 합의한다.
+- 미해결 항목은 `Open Items / Assumptions`에 기록한다.
+
+### Phase 5. Implementation Planning
+- `create-implementation-issue.prompt.md`로 구현 이슈를 생성한다.
+- `Acceptance Criteria Mapping`으로 AC와 작업 항목을 연결한다.
+- AI Agent 작업과 Human 작업을 분리한다.
+
+### Phase 6. Implementation & PR
+- 구현을 진행하고 PR을 생성한다.
+- `.github/pull_request_template.md`로 REQ ID, AC 커버리지, 테스트 증거를 기록한다.
+
+### Phase 7. Verification & Status Transition
+- 자동/수동 검증 결과를 반영한다.
+- `mark-requirement-implemented.prompt.md`로 `Approved -> Implemented` 전환 가능 여부를 점검한다.
+- 충족 여부가 확인되면 requirement 상태를 전환한다.
+
+### Phase 8. Traceability & Release
+- `docs/SRS/traceability-matrix.md`를 갱신한다.
+- 릴리즈 노트에 반영된 REQ ID를 기록한다.
+- 필요 시 운영 문서/회고 문서에 residual risk를 남긴다.