프로젝트 시작부터 구현 루프까지
기능 추가는 /oculpm:inception(계획만 확장) 또는 바로 /oculpm:next 부터 — 인셉션의 질문·리서치는 낯선 영역일 때만 처음부터 다시 돕니다.
슬래시 커맨드 4종
타이핑 한 줄로 부르는 것.
/oculpm:inception새 프로젝트/기능 영역의 시작
어떻게 시작하든 결과가 좋도록 순서를 잡습니다: 「이게 되면 그다음 무엇이 일어나야 하나」로 결과를 정하고 → 깊이 네 질문(최고의 전문가라면 무엇을 더 하나 · 어떤 날것의 재료에서 · 어떤 도구로 · 나나 모델이 아닌 무엇이 맞다고 보여 주나) → 목표를 동사로 바꿔 닿는 분야의 방법 둘~셋(역할극이 아니라 그 전문가가 하는 조사) → 어려운 숫자 목표 한 줄 → plan_create. 계획의 첫 항목은 확인 명령을 만들어 지금 실패(빨강)함을 보이는 것입니다. 스택을 골라야 하면 기억이 아니라 웹 검색으로 버전·출처를 붙여 추천합니다. 질문은 한 번에 지금 답해야 할 것만, 추천 답과 함께. 아이디어를 인자로 줄 수 있습니다: /oculpm:inception 할 일 앱을 만들고 싶어
/oculpm:next구현 루프 — 반복 실행
활성 플랜의 다음 미완 리프를 먼저 진행중([~])으로 잡고 — 병렬 세션이 같은 항목을 잡지 않습니다 — 구현 → 확인 명령 → 일지 → 플랜 갱신 한 사이클을 돕니다. 확인 명령의 결과는 플랜 로그에 판정 ✓/판정 ✗ 로 남아 다음 세션의 시작 훅이 「마지막 판정」으로 싣습니다. /oculpm:next until-done 이면 판정이 통과하거나, 막히거나, 사용자 결정이 필요하거나, 바꿀 접근이 없을 때까지 리프를 이어 잡습니다. 앱 플래너의 ▶실행과 같은 역할의 플러그인 대응물입니다. 특정 항목을 지정하려면: /oculpm:next login-happy-path
/oculpm:redteam합류·릴리스 직전, 「뭐가 틀렸지」
플랜·일지의 주장을 원재료(테스트·로그·diff)와 대조하고 직접 돌려 반례·검증 불가·유지된 주장으로 나눠 보고합니다. 숏셀러처럼 쓰는 게 아니라 숏셀러가 하는 일을 합니다 — 자기 판단은 증거가 아닙니다. 고치지는 않습니다.
/oculpm:help뭐가 있는지 잊었을 때
플러그인 표면 전체(커맨드 4 · MCP 도구 8 · 스킬 1 · 훅)를 레퍼런스 카드 한 장으로 보여주고, 지금 상황에 맞는 다음 한 걸음을 추천합니다.
MCP 도구 8종
에이전트가 마크다운 규격을 흉내 내는 대신 도구로 기록하고, 쌓인 기록을 도구로 되찾습니다 — 경로·frontmatter·항목 id 규격은 서버가 보장합니다. 모든 도구는 .oculpm/ 이 있는 추적 프로젝트에서만 동작합니다 (유일한 예외: project_init).
| 도구 | 하는 일 |
|---|---|
| journal_search | 과거 일지 검색 — 질의(제목·본문·태그)에 더해 그 파일을 건드린 일지·종류·상태·기간·태그로 좁힘. 본문 전문 대신 압축 히트 목록을 돌려주고, 관련도순(제목>태그>슬러그>경로>본문 가중치 + 최신성 소량 가산)으로 정렬 — 오래된 일지도 강하게 걸리면 위로 온다. 앱이 켜져 있으면 SQLite 캐시를, 아니면 디스크를 읽는다(응답의 source). 작업 시작 전 호출이 규칙. |
| journal_read | 검색이 고른 일지 1건의 본문 전체. 목록을 훑는 용도가 아니라, 읽을 값어치가 있다고 판단한 뒤에만. |
| journal_write | 작업 단위(버그/기능/리팩토링/에러/잡일) 하나가 끝날 때마다 일지 1건을 규격대로 기록. 과거 일지와의 related 링크와 session_id 를 받고, 본문의 시크릿은 마스킹한 뒤 응답으로 알림. 같은 파일을 만진 지난 결함이 있으면 followup 으로 자동 연결(auto_related), 태그는 정규화하고 기존 어휘와 비슷하면 tag_hints 로 제안. 제목은 영역: 무엇을 했다 한 문장, 40자 안 — 형식이 아니면 기록하지 않고 고칠 말과 이 프로젝트가 쓰는 영역을 돌려줌(영역은 area 인자로도, 첫 태그로도 남음). |
| plan_status | 활성 플랜의 항목·상태를 조회 — 「지금 어디까지 됐나」의 근거. 플랜마다 현재 파일 hash 가 함께 오고, 그것이 plan_update 의 base_hash 재료입니다. |
| plan_update | 플랜 항목의 상태를 갱신하고 plan-log 를 남김. 하위를 가진 부모는 롤업 자동이라 직접 갱신 거부. 확인 명령을 돌렸으면 메모를 판정 ✓ <결과 끝 줄> / 판정 ✗ … 로 — 시작 훅이 「마지막 판정」으로 싣습니다. base_hash 필수 — plan_status 로 읽은 해시와 디스크가 어긋나면 덮어쓰지 않고 현재 해시를 담아 거절합니다. 병렬 세션이 같은 플랜을 고칠 때 한쪽 변경이 조용히 사라지던 자리입니다. |
| plan_create | 새 계획을 3-depth(마일스톤→작업→하위 작업)로 생성 — frontmatter·id 규격 서버 보장. done_when(완료 조건)과 check(그것을 통과/실패로 판정하는 명령)을 받아 본문 첫 줄에 두고, 시작 훅이 항목보다 먼저 싣습니다. 제목·id 가 겹치는 활성 계획이 있으면 만들지 않고 그 후보를 돌려줘 재사용을 권합니다(allow_similar 로 통과). check 를 생략하면 매니페스트(package.json · Cargo.toml · pyproject · go.mod · Makefile)에서 확인 명령을 감지해 적고 warnings 로 알립니다 — 틀리면 그 줄을 고치세요. |
| project_init | 미추적 저장소의 추적 시작 — 사용자의 명시적 요청·확인(confirm)이 있을 때만. 심볼릭 링크 거부·홈 디렉터리 가드. |
| ask_user | 사람의 결정이 필요한데 사람이 터미널을 보고 있지 않을 수 있을 때 — 질문(과 고를 수 있는 답, 최대 6개)을 Ocul 앱의 오늘 화면에 띄우고 답을 기다려 그대로 돌려줌. 25분 안에 답이 없으면 질문을 거두고 answer: null — 그때는 터미널에서 묻는다. 사소한 확인에는 쓰지 않는다. |
동봉 스킬 1종
상황에 맞게 스스로 발동하는 방법론입니다. 플러그인을 설치하면 함께 들어옵니다. (3.x 의 앱 「스킬·규칙」 화면과 개별 설치 딥링크는 4.0 에서 걷었습니다 — 스킬은 플러그인이 맡습니다.)
oculpm-journal v2.36.0기록 규격의 풀 스펙 캐리어
일지·플랜 규칙의 세부가 필요할 때 로드됩니다 — 폴더 규약·frontmatter 필드·섹션 순서·related 링크 규칙의 전문.
안전 계약(무엇을 읽고 쓰고 절대 하지 않는지)은 저장소의 플러그인 계약 문서에 테스트와 함께 고정돼 있습니다. 훅은 네트워크 없는 로컬 append 한 줄이고, 대화 로그가 담기는 .oculpm/hooks/ 는 gitignore 관리 블록이 커밋을 막습니다. 여기에 배달 게이트가 하나 더 있습니다 — 코드 변경이 있는데 일지 없이 세션을 마치려 하면 세션당 한 번 에이전트에게 일지 작성을 지시합니다 (규칙 주입만으로는 헤드리스 세션 기록 준수가 0% 였던 자체 벤치 실측이 근거). 그리고 재수정 경고 — 최근 7일 안에 버그를 고친 파일을 다시 고치기 직전, 그 버그와 그때 돌린 확인 명령을 에이전트에게 알려 줍니다. 막지 않고, 대화마다 파일당 한 번입니다.