feat: add devlog system (Index + Entry) + enhanced work lifecycle protocol from Deriva

This commit is contained in:
2026-03-08 08:27:01 +09:00
parent 6d7b120fab
commit 85dd8e0d68
3 changed files with 168 additions and 44 deletions

View File

@@ -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 주의사항