feat: add devlog system (Index + Entry) + enhanced work lifecycle protocol from Deriva
This commit is contained in:
@@ -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>(<scope>): <description>
|
||||
|
||||
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 완료
|
||||
|
||||
@@ -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`
|
||||
태스크 생성 시 반드시 아래 라벨을 적절히 부여합니다:
|
||||
|
||||
### 커밋 메시지 컨벤션
|
||||
```
|
||||
<type>(<scope>): <description>
|
||||
**영역 라벨 (필수, 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 주의사항
|
||||
|
||||
|
||||
@@ -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, 문서 정리
|
||||
|
||||
Reference in New Issue
Block a user