From 705ee72b5da55940a394c8336059c0c0d39e200d Mon Sep 17 00:00:00 2001 From: klaus Date: Mon, 19 Oct 2026 13:45:43 +0900 Subject: [PATCH] =?UTF-8?q?docs(agents):=20=EC=8A=A4=ED=82=AC=20=EC=84=A4?= =?UTF-8?q?=EC=A0=95=20=EC=9A=94=EA=B5=AC=EC=82=AC=ED=95=AD=EA=B3=BC=20?= =?UTF-8?q?=EA=B2=80=EC=A6=9D=20=EA=B2=B0=EA=B3=BC=EB=A5=BC=20=EA=B8=B0?= =?UTF-8?q?=EB=A1=9D=ED=95=9C=EB=8B=A4?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- .../plan-task.md | 137 ++++++++++++++++++ .../20261019_엔지니어링_스킬_로컬_설정/prd.md | 57 ++++++++ 2 files changed, 194 insertions(+) create mode 100644 docs/20261019_엔지니어링_스킬_로컬_설정/plan-task.md create mode 100644 docs/20261019_엔지니어링_스킬_로컬_설정/prd.md diff --git a/docs/20261019_엔지니어링_스킬_로컬_설정/plan-task.md b/docs/20261019_엔지니어링_스킬_로컬_설정/plan-task.md new file mode 100644 index 00000000..63268ef1 --- /dev/null +++ b/docs/20261019_엔지니어링_스킬_로컬_설정/plan-task.md @@ -0,0 +1,137 @@ +# 엔지니어링 스킬 로컬 설정 구현 계획 + +| 문서 항목 | 내용 | +|---|---| +| 상태 | 구현 완료 | +| 작성일 | 2026-10-19 | +| 요구사항 기준 | [prd.md](prd.md) | +| API 기준 | 해당 없음 | +| 현재 Phase | 1: 저장소 문서 설정 | +| 현재 활성 작업 | 없음 | + +## 목표 + +엔지니어링 스킬이 로컬 이슈 위치와 도메인 문서 규칙을 찾고 기존 작업 절차를 유지할 수 있다. + +## 현재 상태 + +| Phase | 상태 | 완료 Task | 활성/다음 작업 | 차단 조건 | +|---|---|---|---|---| +| 1 | 완료 | 1/1 | 없음 | 없음 | + +## 범위와 기술적 제약 + +- 포함: 승인된 설정 문서, 작업 문서 두 개, 관련 가이드 교차 참조. +- 제외: 앱·빌드 설정 변경, 원격 작업, 라벨 설정, 빈 도메인 문서·이슈 생성, 커밋. +- 기존 문서의 내용·경로·완료 기록을 보존한다. +- 기술 스택: Markdown, 검증용 `rg`·비파괴 Git 명령·Gradle task 목록 조회. +- 문서 외 실행 로직을 추가하지 않으며 기기·UI 검증은 하지 않는다. + +## Phase 1 + +**Phase 결과:** 승인된 로컬 이슈·single-context 설정을 저장소 지침에서 읽을 수 있다. + +**선행조건:** 사용자의 로컬 Markdown 선택과 초안 승인. + +### 구현 항목 + +#### Task 1.1 로컬 설정 문서 반영 + +**작업 ID `P1-T1`:** 기존 작업 절차를 유지하면서 승인된 설정 문서를 연결한다. + +- **시작 조건:** 이 PRD와 계획 준비 완료. +- **완료 증거:** 아래 체크리스트 및 요구사항별 문서 검색 결과. +- **범위 밖:** 앱 코드·설정과 실제 이슈 생성. +- **TDD 예외 사유:** 실행 로직을 변경하지 않는 문서 전용 Task다. +- **대체 검증 방법:** 파일 재읽기, `rg` 경로·문구 검사, `git diff --check`와 변경 파일 확인. + +**Files:** + +- Create: `docs/20261019_엔지니어링_스킬_로컬_설정/prd.md`, `plan-task.md`. +- Create: `docs/agents/issue-tracker.md`, `docs/agents/domain.md`. +- Modify: `AGENTS.md`, `docs/agent-guides/work-plan-docs.md`. + +**Interfaces:** 승인된 초안과 기존 PRD 규칙을 입력으로 받아, `AGENTS.md`에서 두 설정 문서를 참조하는 Markdown 계약을 제공한다. + +- [x] 샘플과 기존 지침을 확인하고 PRD·계획을 먼저 작성한다. +- [x] 이슈·도메인 설정 문서를 승인된 초안대로 작성한다. +- [x] `AGENTS.md`에 중복 없는 `Agent skills` 블록을 추가한다. +- [x] 작업 가이드에 기존 PRD·계획 규칙을 보존하는 교차 참조를 추가한다. +- [x] 설정 문서의 요구사항별 문구·경로를 검색하여 확인한다. + +**검증 기록:** + +- 2026-10-19: `AGENTS.md`, 문서 샘플 두 개, 작업 가이드, `.gitignore`를 읽었다. 앞선 탐색에서 기존 설정 문서와 triage 스킬이 없는 것을 확인했고 사용자가 초안을 승인했다. +- 2026-10-19: 설정 네 문서를 재읽고 `rg -n 'Agent skills|docs/agents/(issue-tracker|domain)\.md|docs/agents/' AGENTS.md docs/agent-guides/work-plan-docs.md`로 안내와 참조를 확인했다. `rg -n '\.scratch/|issues/|Status:|Comments|spec\.md|prd\.md|plan-task\.md|single-context|GLOSSARY\.md|docs/adr/|ADR|domain-modeling' docs/agents`로 요구사항 문구를 확인했다. 두 명령 모두 종료 코드 0이며 기존 지침 수정 없이 안내만 추가했다. + +### Phase 1 Gate + +**작업 ID `P1-GATE`:** 문서 정합성과 변경 범위를 판정하고 실제 검증 결과를 남긴다. + +- **시작 조건:** P1-T1의 설정 문서 반영 완료. +- **완료 증거:** 아래 검사 실행 결과와 최하단 Verification Log. +- **범위 밖:** 앱 전체 회귀·빌드·UI 검증, 관련 없는 환경 수정. + +- [x] `rg -n 'Agent skills|docs/agents/(issue-tracker|domain)\.md' AGENTS.md docs/agent-guides/work-plan-docs.md`로 참조를 확인한다. +- [x] 설정 두 문서의 실제 내용을 재읽고 경로·상태·도메인 규칙을 확인한다. +- [x] `git diff --check`, `git status --short`로 공백 오류와 여섯 파일 범위를 확인한다. +- [x] `./gradlew tasks --all`을 실행하고 결과를 기록한다. 환경 실패는 문서 검증과 구분한다. +- [x] Markdown 진단 도구 제공 여부와 생략한 검증을 기록한다. + +## 실행 순서 + +PRD·계획 준비 → P1-T1 → P1-GATE. 단일 작업 흐름으로 진행한다. + +## Progress + +### P1-T1 1차 실행: 2026-10-19 + +- 상태: 진행 중. +- 무엇을: 승인된 요구사항과 여섯 파일 범위를 PRD·계획에 기록했다. +- 왜: 설정 변경 전에 작업 문서를 준비하는 저장소 규칙을 준수한다. +- 어떻게: 사용자 승인 초안과 기존 지침·문서 샘플을 대조했다. +- 남은 항목: 설정 네 문서 반영과 검증. +- 다음 행동: 승인된 설정 문서를 작성한다. + +### P1-T1 2차 실행: 2026-10-19 + +- 상태: 완료. +- 무엇을: 승인된 설정 네 문서를 반영하고 PRD 중복 방지와 도메인 지연 생성 규칙을 확인했다. +- 왜: SETUP-001~004 및 관련 가이드 동기화를 충족한다. +- 어떻게: 설정 문서 재읽기, 요구사항별 `rg` 검색, 기존 두 파일의 Git diff 대조. +- 남은 항목: 없음. +- 다음 행동: P1-GATE 통합 검증 기록. + +### P1-GATE 1차 실행: 2026-10-19 + +- 상태: 완료. +- 무엇을: 설정·경로·공백·변경 범위와 Gradle 명령을 검증했다. +- 왜: SETUP-005의 실제 완료 증거를 남긴다. +- 어떻게: 아래 Verification Log의 명령과 결과를 기록했다. +- 남은 항목: 없음. Markdown LSP 검증 제한은 아래에 명시한다. +- 다음 행동: 결과 보고. 커밋하지 않는다. + +## Decision Log + +| 날짜 | ID | 상태 | 결정 | 근거 | +|---|---|---|---|---| +| 2026-10-19 | DEC-001 | 확정 | 사용자 승인 초안을 변경 없이 반영하고 관련 가이드만 동기화 | PRD SETUP-001~005 | +| 2026-10-19 | DEC-002 | 확정 | 자동 테스트 추가 대신 문서 검색·차이·Gradle task 조회 | 문서 전용 TDD 예외 | + +## Verification Log + +아직 최종 검증을 실행하지 않았다. + +### 최종 검증: 2026-10-19 + +- 위 문장은 초기 상태 기록이다. 아래 검증을 실행하여 문서 설정 작업을 완료했다. +- `rg` 참조·요구사항 검색: 종료 코드 0. Agent skills 블록 한 개와 설정 문서 두 개, 관련 가이드 교차 참조를 확인했다. +- 셸 `test` 검사: 설정·작업 문서 존재, Agent skills 블록 한 개, 불필요한 라벨 문서·빈 이슈·도메인 파일 부재를 확인했다. 초기 검색은 PRD의 라벨 참조 금지 문구까지 포함해 일치했으므로 설정 문서만 대상으로 좁혀 재실행했고 종료 코드 0이다. +- `rg` 부정 검색: 설정 문서의 존재하지 않는 라벨 문서 참조가 없고, 여섯 Markdown 파일에 줄 끝 공백과 도구 내부 표식이 없는 것을 확인했다. 부정 검색을 포함한 셸 검증 종료 코드 0. +- `git diff --check`: 종료 코드 0, 공백 오류 없음. 미추적 파일은 별도 파일 재읽기와 `rg` 공백 검사로 확인했다. +- `git -c core.quotePath=false status --short --untracked-files=all`: 기존 문서 수정 2개, 신규 문서 4개, 계획한 여섯 Markdown 파일만 변경했다. +- `git diff -- AGENTS.md docs/agent-guides/work-plan-docs.md`: 기존 지침 제거·변경 없이 Agent skills 블록과 가이드 안내만 추가했다. +- `./gradlew tasks --all`: 종료 코드 0, `BUILD SUCCESSFUL in 17s`, `1 actionable task: 1 executed`. 이 명령은 task 목록 조회이며 앱 컴파일이나 테스트 통과를 뜻하지 않는다. +- 관찰: Gradle 9.0과 호환되지 않는 deprecated feature 경고가 출력됐다. 이번 Markdown 변경과 무관한 빌드 환경 경고이며 수정하지 않았다. +- Markdown LSP: 현재 도구에 `lsp_diagnostics`가 없어 실행하지 못했다. 문서 검색·파일 검사 결과와 별도로 이 제한을 남긴다. +- 생략: 문서 전용 변경으로 앱 전체 회귀·빌드·UI·기기 검증은 실행하지 않았다. 이슈 생성, 스킬 설치, 원격 설정 변경, 커밋·푸시는 하지 않았다. diff --git a/docs/20261019_엔지니어링_스킬_로컬_설정/prd.md b/docs/20261019_엔지니어링_스킬_로컬_설정/prd.md new file mode 100644 index 00000000..2b975d46 --- /dev/null +++ b/docs/20261019_엔지니어링_스킬_로컬_설정/prd.md @@ -0,0 +1,57 @@ +# 엔지니어링 스킬 로컬 설정 PRD + +## 문서 정보 + +| 항목 | 내용 | +|---|---| +| 문서 상태 | 구현 완료 | +| 작성일 | 2026-10-19 | +| 대상 | SodaLive 엔지니어링 스킬 저장소 설정 | +| 결정권자 | 저장소 사용자 | +| 관련 구현 계획 | [plan-task.md](plan-task.md) | +| 관련 API Contract·review | 해당 없음: 문서 설정만 변경 | + +## 1. Overview + +엔지니어링 스킬이 이슈 관리 위치와 도메인 문서 읽기 규칙을 일관되게 찾도록 저장소 설정 문서를 추가한다. 사용자는 로컬 Markdown을 선택하고 설정 초안을 승인했다. + +## 2. Goals + +- 루트 `AGENTS.md`에서 이슈·도메인 설정 문서로 연결한다. +- 기존 PRD·계획 작성 절차를 유지하며 로컬 이슈 관리 규칙을 추가한다. +- single-context 도메인 문서를 필요한 시점에만 생성하도록 안내한다. + +## 3. Non-Goals + +- 앱 코드, Gradle 설정, 의존성, 비밀 파일 변경. +- 원격 이슈 생성, 스킬 설치, triage 라벨 설정, 커밋·푸시. +- 예시 이슈와 빈 `.scratch/`, `GLOSSARY.md`, `docs/adr/` 생성. +- UI·기기 검증과 앱 전체 회귀 테스트. + +## 4. 기능 요구사항 + +| ID | 상태 | 요구사항 | 수용 기준 | 연결 | +|---|---|---|---|---| +| SETUP-001 | 확정 | `AGENTS.md`에 `Agent skills` 안내 추가 | 이슈·도메인 설정 두 문서로 연결하고 기존 지침 보존 | P1-T1 | +| SETUP-002 | 확정 | 로컬 Markdown 이슈 규칙 설정 | 기능별 `.scratch/` 아래 개별 번호 티켓, 상태·댓글·Wayfinder 규칙 명시 | P1-T1 | +| SETUP-003 | 확정 | 기존 PRD·계획 경로 유지 | 정식 문서는 `docs/YYYYMMDD_작업명/`, 필요한 `spec.md`는 PRD 참조만 제공 | P1-T1 | +| SETUP-004 | 확정 | single-context 소비 규칙 설정 | 용어집·관련 ADR 읽기, 부재 시 조용히 진행, 필요 시 생성, 용어 준수·ADR 충돌 명시 | P1-T1 | +| SETUP-005 | 확정 | 관련 가이드 동기화와 검증 기록 | 작업 가이드 교차 참조, 문서 검사 및 Gradle 명령 결과를 계획에 기록 | P1-GATE | + +## 5. 성공 기준 + +- 설정 문서가 승인된 초안과 일치하고 `triage-labels.md`를 참조하지 않는다. +- 기존 PRD·계획 작성 규칙과 충돌하거나 내용을 중복 관리하지 않는다. +- 여섯 Markdown 파일만 변경하며 검증의 실제 결과·제한을 남긴다. + +## 6. Open Questions + +미결 사항 없음. + +## 7. Decision Log + +| 날짜 | ID | 상태 | 결정 | 근거 | +|---|---|---|---|---| +| 2026-10-19 | DEC-001 | 확정 | 로컬 Markdown 이슈 관리 | 사용자의 명시적 선택 | +| 2026-10-19 | DEC-002 | 확정 | 기존 PRD·계획 보존 및 single-context 적용 | 사용자가 초안 승인 후 진행 요청 | +| 2026-10-19 | DEC-003 | 확정 | 문서 전용 TDD 예외, 정합성 검사로 대체 | 실행 로직 변경 없음, 저장소 문서 Task 예외 규칙 |