oculpm-journal

ocul-pm 기록 규격 (풀 스펙)

MCP 도구가 보이면 이 스킬 대신 도구를 쓴다 — journal_write / plan_status / plan_update 가 경로·파일명·frontmatter 규격을 서버에서 보장한다. 아래는 도구가 없을 때 파일을 직접 쓰는 규격이다.

plan_update 는 base_hash 가 필수다 — 먼저 plan_status 로 그 플랜의 hash 를 읽고 그대로 넘긴다. 병렬 세션이 같은 플랜을 고칠 때 한쪽 변경이 조용히 사라지는 것을 막는 장치다. 어긋나면 아무것도 쓰지 않고 현재 hash 를 담은 오류가 오니, 다시 읽어 판단한 뒤 새 hash 로 재호출한다.

1. 작업 일지

경로: .oculpm/journal/{YYYYMMDD}/{TypeFolder}/{HHMM}_{type}_{slug}.md

• TypeFolder = Bugs | Features_to_add | Errors | Refactors | Chores
• type ∈ {bug, feature, error, refactor, chore}, slug = ASCII kebab-case ≤40자
• 하나의 파일에 두 개 이상의 작업을 묶지 말 것. 기존 일지 수정 금지 (새 파일 + related 링크).

frontmatter (8개 필수 — 자주 틀리는 3가지: ① created_at 은 +09:00 형태 tz offset 필수, ② agent 는 id/version 키를 가진 mapping, ③ files_touched[].op 은 create|update|delete|rename|correct enum 만):

---
schema_version: 1
type: bug
slug: short-kebab-slug
status: done            # planned | in_progress | done | abandoned
created_at: "2026-07-31T14:03:00+09:00"
session_id: "manual-<workday>-HHMMSS"
agent: { id: claude-code, version: "모델명" }
language: ko
verified_by_user: false
files_touched: [{ path: src/x.rs, op: update }]
related: []
tags: []
---

본문: 첫 줄 [x] 제목 체크박스. 타입별 강제 헤더 — bug/error: ## 발생 원인 → ## 해결 방법, feature: ## 추가 기능 → ## 동작 흐름, refactor: ## 동기 → ## 변경 요약. 공통 끝: ## 검증 (필수, 1~3줄), ## 메모 (선택).

학습 품질 (growth-log 규율): 일지는 성과 나열이 아니라 다음 세션이 헛수고를 안 하게 하는 기록이다 — 실패한 접근·막다른 길·의외였던 사실을 성공보다 우선 기록한다 ("X 를 시도했지만 Y 라서 안 됨"이 "X 완료"보다 값지다). 같은 실패를 반복하지 않도록 ## 메모 에 다음 독자를 위한 학습 1줄을 남긴다.

금지: .oculpm/index/** 쓰기, secrets/API key 포함, 기존 일지 수정.

2. 플래너 갱신 (일지 직후)

.oculpm/planner/*.md 의 대응 항목이 있으면: ① 상태 글리프 변경 — [ ] 할일 · [~] 진행중 · [x] 완료 · [!] 막힘 · [>] 이월 · [-] 폐기, ② 하단 managed block 에 한 줄 append (기존 행 수정 금지):

<!-- oculpm:plan-log begin v1 -->
| 시각 | 항목 | 에이전트 | 변화 | 일지 | 메모 |
|---|---|---|---|---|---|
| 2026-07-31T14:03:00+09:00 | #item-id | claude-code | ~→x | journal/…/x.md | |
<!-- oculpm:plan-log end -->