From 85dd8e0d68870857afb154044b99db66370a7503 Mon Sep 17 00:00:00 2001 From: Variet Date: Sun, 8 Mar 2026 08:27:01 +0900 Subject: [PATCH] feat: add devlog system (Index + Entry) + enhanced work lifecycle protocol from Deriva --- .agents/workflows/end.md | 104 +++++++++++++++++++++++++++------- .agents/workflows/services.md | 66 +++++++++++++++++---- .agents/workflows/start.md | 42 +++++++++----- 3 files changed, 168 insertions(+), 44 deletions(-) diff --git a/.agents/workflows/end.md b/.agents/workflows/end.md index 0356eb7..c6df446 100644 --- a/.agents/workflows/end.md +++ b/.agents/workflows/end.md @@ -1,5 +1,5 @@ --- -description: 세션 종료 시 학습 기록 + Vikunja 동기화 + git commit (끝, 마무리, 커밋해, 완료) +description: 세션 종료 시 devlog 기록 + git commit + Vikunja 동기화 (끝, 마무리, 커밋해, 완료) --- # 세션 종료 프로토콜 @@ -23,22 +23,68 @@ description: 세션 종료 시 학습 기록 + Vikunja 동기화 + git commit ( - **주의**: ... ``` -## 1. Vikunja 동기화 +## 1. Devlog 기록 + +### Index 업데이트 (필수 — 매 작업) + +오늘 날짜의 index 파일에 완료된 작업 1줄을 추가합니다. + +- **파일**: `docs/devlog/YYYY-MM-DD.md` +- **형식**: +```markdown +| NNN | HH:MM | 작업 설명 | `커밋해시` | ✅ 또는 🔧 | +``` + +> [!TIP] +> - ✅ = 완료, 🔧 = 미완료 (다음 세션에서 이어받기) +> - 파일이 없으면 새로 생성 (테이블 헤더 포함) + +### Entry 작성 (선택적 — 필요할 때만) + +> [!IMPORTANT] +> Entry는 **git/Vikunja/wiki에 없는 정보**가 있을 때만 작성합니다. + +**Entry 작성 기준:** +- ✅ 설계 결정이 있었을 때 (왜 A가 아닌 B를 선택했는지) +- ✅ 미완료 사항이 있을 때 (다음 세션이 이어받아야 할 맥락) +- ✅ 삽질/트러블슈팅이 있었을 때 (같은 실수 방지) + +**Entry 불필요:** +- ❌ 단순 버그 픽스 (커밋 메시지로 충분) +- ❌ 문서 업데이트 (git diff로 충분) +- ❌ 이미 Vikunja 태스크에 상세 설명이 있는 경우 + +**Entry 파일**: `docs/devlog/entries/YYYYMMDD-NNN.md` +```markdown +# 작업 제목 + +- **시간**: YYYY-MM-DD HH:MM~HH:MM +- **Commit**: `해시` +- **Vikunja**: #태스크번호 → done/진행중 + +## 결정 사항 +- 왜 이 방식을 선택했는지 + +## 미완료 +- 남은 작업 (있을 경우) +``` + +--- + +## 2. Vikunja 동기화 > [!CAUTION] > **반드시 `vikunja_helper.py` 사용.** 직접 API 호출 금지. +> Vikunja API는 POST 시 body에 없는 필드를 빈값으로 덮어씁니다. -### 1-1. 커밋 전수 검사 +### 2-1. 커밋 전수 검사 이번 세션의 **모든 커밋을 하나씩 검사**하고 Vikunja에 매핑합니다. -누락 없이 모든 커밋을 처리해야 합니다. ```powershell git log --oneline -20 ``` -각 커밋에 대해 아래 표를 기준으로 판단합니다: - | 커밋 유형 | Vikunja 액션 | |-----------|-------------| | 기존 태스크 해당 작업 **완료** | `python .agents\workflows\helpers\vikunja_helper.py done {ID}` | @@ -46,29 +92,43 @@ git log --oneline -20 | 작업 중 발견된 **미완료 TODO** | `python .agents\workflows\helpers\vikunja_helper.py create "제목" "설명" --labels Backend,Priority:Mid` | > [!IMPORTANT] -> - 커밋 1개 = Vikunja 액션 1개 이상 대응 -> - 여러 커밋이 같은 태스크에 해당하면 마지막 커밋에서 `done` 처리 -> - 매핑할 기존 태스크를 모르면 먼저 `list todo`로 조회 +> 모든 커밋이 기존 또는 신규 태스크에 매핑되었는지 확인. -### 1-2. Wiki 동기화 (해당 시에만) +### 2-2. 완료 처리 -코드 변경이 아키텍처에 영향을 주는 경우 Wiki를 업데이트합니다: +```powershell +python .agents\workflows\helpers\vikunja_helper.py done {TASK_ID} +``` + +### 2-3. 신규 태스크 생성 + +```powershell +python .agents\workflows\helpers\vikunja_helper.py create "제목" "설명" --labels Backend,Priority:High +``` + +### 라벨 규칙 + +**영역 (필수 1개 이상):** `Backend` / `Frontend` / `Engine` / `Infra` / `Test` +**우선순위 (필수 1개):** `Priority:High` / `Priority:Mid` / `Priority:Low` + +--- + +## 3. Wiki 동기화 (해당 시에만) | 코드 변경 | 대상 Wiki | |-----------|----------| -| 서버 변경 (새 API, 모듈) | Architecture | -| 프론트엔드 변경 (새 컴포넌트) | Architecture | -| 인프라 변경 (Docker, CI/CD) | Architecture | +| 서버 변경 | Architecture | +| 프론트엔드 변경 | Architecture | +| 인프라 변경 | Architecture | | 새 모듈/패키지 추가 | Architecture | ```powershell python .agents\workflows\helpers\wiki_helper.py update "Architecture" /tmp/wiki_content.md ``` -> [!TIP] -> Wiki 내용은 먼저 `read`로 기존 내용을 확인한 후, 수정된 전체 내용을 파일로 만들어 `update`합니다. +--- -## 2. Git Commit & Push +## 4. Git Commit & Push ```powershell git add -A @@ -86,15 +146,19 @@ git push origin main (): type: feat|fix|refactor|test|docs|chore|ci|infra -scope: (선택 — 모듈명 등) +scope: (선택) ``` -## 3. 최종 체크리스트 +--- + +## 5. 최종 체크리스트 > [!WARNING] > 아래 항목 중 하나라도 누락되면 세션 종료를 완료할 수 없습니다. -- [ ] known-issues 업데이트 완료 (새 이슈가 있었다면) +- [ ] known-issues 업데이트됨 (새 이슈가 있었다면) +- [ ] devlog index 업데이트됨 +- [ ] devlog entry 작성됨 (필요한 경우만) - [ ] Vikunja 태스크 생성/완료 처리됨 (커밋 전수 검사 기반) - [ ] Wiki 동기화됨 (아키텍처 변경이 있었다면) - [ ] git push 완료 diff --git a/.agents/workflows/services.md b/.agents/workflows/services.md index 48590ad..563533e 100644 --- a/.agents/workflows/services.md +++ b/.agents/workflows/services.md @@ -59,21 +59,67 @@ python .agents\workflows\helpers\vikunja_helper.py list todo ### Vikunja = Single Source of Truth (SSOT) - **Vikunja가 유일한 작업 현황 관리 도구**입니다. -- 새 TODO 발견 시 → Vikunja에 태스크 생성 -- 작업 완료 시 → Vikunja 태스크 완료 처리 +- 로컬 `task.md`는 현재 대화 내 세부 체크리스트용으로만 사용합니다. +- 새 TODO 발견 시 → Vikunja에 태스크 생성 (로컬 파일에만 적는 것은 금지) +- 작업 완료 시 → Vikunja 태스크 완료 처리 (로컬 체크만 하는 것은 금지) ### Vikunja 태깅 규칙 -**영역 라벨 (필수, 1개 이상):** `Backend` / `Frontend` / `Infra` / `Test` -**우선순위 라벨 (필수, 1개):** `Priority:High` / `Priority:Mid` / `Priority:Low` +태스크 생성 시 반드시 아래 라벨을 적절히 부여합니다: -### 커밋 메시지 컨벤션 -``` -(): +**영역 라벨 (필수, 1개 이상):** -type: feat|fix|refactor|test|docs|chore|ci|infra -scope: (선택) -``` +| ID | 라벨 | 적용 대상 | +|:--:|-------|-----------:| +| 1 | `Backend` | 서버, DB, API | +| 2 | `Frontend` | UI, 웹 프론트엔드 | +| 3 | `Engine` | 핵심 엔진/로직 | +| 4 | `Infra` | Docker, CI/CD, 모니터링 | +| 5 | `Test` | 테스트, E2E | + +**우선순위 라벨 (필수, 1개):** + +| ID | 라벨 | 기준 | +|:--:|-------|------:| +| 6 | `Priority:High` | 핵심 기능 미완성, 블로커 | +| 7 | `Priority:Mid` | 기능 개선, UX 향상, 리팩터링 | +| 8 | `Priority:Low` | nice-to-have, 문서, 코드 정리 | + +**태스크 제목 규칙:** +- 한글 + 핵심 키워드 (예: `WebSocket 재연결 로직 구현`) +- 50자 이내 + +### 작업 시작 시 +1. `git pull` 으로 최신 코드 동기화 +2. Vikunja 태스크 조회 (`/check-vikunja`) → 관련 태스크 ID 확인 +3. 관련 태스크가 있으면 Vikunja에서 진행중 표시 +4. 관련 태스크가 없으면 Vikunja에 새 태스크 생성 (태깅 규칙 준수) + +### 작업 중 +5. 의미 있는 단위마다 자주 커밋 (대규모 변경을 한번에 커밋하지 않음) +6. 커밋 메시지 규칙: + - `feat:`, `fix:`, `refactor:`, `test:`, `docs:`, `chore:`, `ci:` 접두사 사용 + - 관련 Vikunja 태스크가 있으면 `#task-{ID}` 참조 포함 + - 예: `feat(server): WebSocket 재연결 로직 #task-21` + +### 작업 완료 시 +7. 모든 변경사항 커밋 + `git push` +8. Vikunja 태스크 완료 처리 (**반드시 `vikunja_helper.py` 사용**): + ```powershell + python .agents\workflows\helpers\vikunja_helper.py done {TASK_ID} + ``` + +> [!CAUTION] +> **직접 `Invoke-RestMethod -Body '{"done": true}'` 사용 금지!** +> Vikunja API는 POST 시 body에 없는 필드를 빈값으로 덮어씁니다. + +9. 작업 중 발견된 새 TODO → Vikunja에 태스크 생성 + +### 멀티 AI 협업 시 추가 규칙 +- 작업 전 `git pull` 필수 (다른 AI가 push한 변경 반영) +- 같은 파일을 동시에 수정하지 않음 +- 공유 인터페이스 수정 시 즉시 commit + push +- 충돌 발생 시 유저에게 확인 요청 ## PowerShell 주의사항 diff --git a/.agents/workflows/start.md b/.agents/workflows/start.md index 806b7f8..5cb01ee 100644 --- a/.agents/workflows/start.md +++ b/.agents/workflows/start.md @@ -15,7 +15,28 @@ description: 세션 시작 시 프로젝트 맥락을 빠르게 복구하는 워 `.agents/AGENT.md`를 읽고 에이전트 행동 규칙을 로딩합니다. `.agents/references/known-issues.md`를 읽어 최근 이슈를 파악합니다. -### 1. Git 상태 확인 +### 1. Devlog 맥락 복구 + +오늘 + 어제 devlog index를 읽고 최근 작업 흐름을 파악합니다. + +```powershell +$today = Get-Date -Format "yyyy-MM-dd" +$yesterday = (Get-Date).AddDays(-1).ToString("yyyy-MM-dd") +if (Test-Path "docs\devlog\$today.md") { + Write-Host "=== Devlog: $today ===" + Get-Content "docs\devlog\$today.md" +} elseif (Test-Path "docs\devlog\$yesterday.md") { + Write-Host "=== Devlog: $yesterday (no entry for today yet) ===" + Get-Content "docs\devlog\$yesterday.md" +} else { + Write-Host "=== No recent devlog found ===" +} +``` + +미완료(🔧) 항목이 있으면 해당 entry 파일을 읽어 이어받기 맥락을 확보합니다: +- Entry 경로: `docs/devlog/entries/YYYYMMDD-NNN.md` + +### 2. Git 상태 확인 ```powershell git status --short @@ -24,28 +45,21 @@ git status --short git log --oneline -5 ``` -### 2. Vikunja TODO 태스크 +### 3. Vikunja TODO 태스크 ```powershell python .agents\workflows\helpers\vikunja_helper.py list todo ``` -### 3. Wiki 아키텍처 확인 (필요 시) - -```powershell -python .agents\workflows\helpers\wiki_helper.py read "Architecture" -``` - ### 4. 종합 보고 결과를 종합하여 사용자에게 보고: -- 마지막 커밋 + 미완료 태스크 -- known-issues에서 최근 추가된 항목 +- 마지막 작업 맥락 + 미완료 항목 (devlog 🔧 기반) - TODO 태스크 목록 (라벨 + 우선순위) - 다음 작업 제안 -**우선순위 판단 기준:** -- P0: 핵심 기능 연결 관련 (전체 기능 불가) -- P1: 서버/통신 장애 +**우선순위 판단 기준** (라벨만으로 판단 금지): +- P0: 최근 커밋에서 스키마/모델/인터페이스 변경 → 연쇄 영향 점검 +- P1: 서버 기동/API 응답 장애 - P2: 기능 미완성/UX 개선 -- P3: 문서, 코드 정리 +- P3: 정확도 향상, 신규 기능, CI/CD, 문서 정리