Ocul-PM: Instructions file for Codex

ocul-pm 작업 기록 규칙

당신은 ocul-pm 추적 프로젝트에서 작업 중입니다. 하나의 논리적 작업 단위(버그 수정 / 기능 / 리팩토링 / 에러 사이클 / 잡일)를 끝낼 때마다 즉시 기록하세요 — 사용자에게 묻지 말 것.

MCP 도구 우선: oculpm 도구(journal_search / journal_read / journal_write / plan_status / plan_update / plan_create)가 보이면 아래 §2 의 파일 직접 작성 대신 도구를 쓰라 — 경로·frontmatter·{#id} 규격은 서버가 보장한다 (§4 의 플래너 갱신도 plan_update, 새 plan 은 plan_create). 도구가 안 보일 때만 직접 쓴다.

0. 시작하기 전 — 과거를 먼저 찾는다

기록은 쌓으라고 있는 게 아니라 다시 쓰라고 있습니다. 시작 전에 과거 일지를 찾아보세요 — 원인·이미 내려진 결정·이미 실패한 접근이 그 안에 있을 수 있고, 오래 추적한 저장소는 일지가 수백 건이라 훑어서는 못 찾습니다.

• 고칠 파일을 알면 journal_search(file: "watcher.rs") — 가장 정확한 필터이니 이것부터.
• 증상·기능 이름이 있으면 journal_search(query: "IME 조합", types: ["bug"]).
• 읽을 가치가 있는 것만 journal_read(path: …) 로 펼칩니다. 계획 맥락은 plan_status.

찾은 것이 이어지면 새 일지의 related 에 그 경로를 넣으세요. 도구가 없으면 .oculpm/journal/** 를 grep.

1. 언제 기록하는가 (5 trigger)

bug fix(재현되던 결함의 해소를 직접 확인) · feature done(첫 happy-path 동작) · refactor batch(기능 동일+구조 변경 완료, 테스트 그린) · error cycle(진단·수정 사이클 1회 — 실패도 기록) · chore(config/문서 등 비기능 변경 완료).

의도적 지름길(천장이 있는 단순화)을 남길 땐 코드 주석 // oculpm-defer: <천장>; <재방문 트리거> 를 붙이세요 — 회고 화면이 수확해 원장으로 보여줍니다 (트리거 없는 마커는 '썩는 중'으로 표시).

2. 일지 파일 규격 (도구가 없을 때만)

경로 .oculpm/journal/{YYYYMMDD}/{TypeFolder}/{HHMM}_{type}_{slug}.md — workday/시각은 OS 로컬 그대로(묻지 말 것) · TypeFolder = Bugs|Features_to_add|Errors|Refactors|Chores · type = bug|feature|error|refactor|chore · slug = ASCII kebab ≤40자.

frontmatter 필수: schema_version: 1 · type · slug · status(planned|in_progress|done|abandoned) · created_at(⚠ tz offset 반드시 +09:00 형태 — Z/+0900 금지) · session_id(없으면 "manual-<workday>-HHMMSS") · agent(⚠ id/version 키의 mapping, 문자열 금지 — id 는 네 에이전트 id(claude-code/cursor/gemini-cli/…), version 은 네 모델명) · language(ko|en) · verified_by_user: false · files_touched(⚠ [{path, op}] — op 는 create|update|delete|rename|correct enum) · related: [] · tags: []. 선택: difficulty(verylow~superhigh), updated_at.