왜 에이전트에게 일을 시키는데 별도의 매니저가 필요한가
Claude Code 에게 기능 구현을 맡기고 며칠이 지나면 한 가지 낯선 비용이 눈에 띕니다. 지난주에 어느 파일을 왜 수정했는지, Cursor 가 고쳤다고 한 버그가 실제로 해결되었는지를 확인하려면 git log 와 개인 기억을 뒤져야 합니다. 코드 자체는 커밋 히스토리에 남지만, 그 변경을 일으킨 맥락은 어디에도 남지 않기 때문입니다. 세션이 쌓일수록 이 맥락을 복원하는 일이 개발 시간의 상당한 몫을 차지하게 됩니다.
Ocul-PM 은 이 빈 공간을 채우기 위해 만들어진 로컬 우선 AI 프로젝트 매니저 입니다. 에이전트가 코드를 작성하는 동안 작업 기록을 자동으로 수집하고, 할루시네이션 여부를 로컬 diff 로 검증하며, 쌓인 기록을 스탠드업 요약과 PR 본문, 회고 문서로 되돌려 줍니다. 클라우드 서버도, 별도 계정도, 텔레메트리 수집도 없습니다.
Ocul-PM 의 핵심 특징
이 도구를 다른 기록 도구와 구분 짓는 설계 원칙은 명확합니다. 프로젝트 폴더 안에 마크다운 파일로 모든 기록을 저장한다는 점입니다. 데이터베이스에 종속되지 않는 플랫 파일 기반의 단일 진실 원천 방식을 채택하여, 앱이 없어도 일지를 그냥 텍스트 파일로 읽을 수 있고 코드와 함께 git commit 할 수 있습니다.
서버가 없다는 것은 데이터가 프로젝트의 .oculpm/ 폴더와 로컬 SQLite 캐시에만 존재한다는 뜻입니다. 외부로 나가는 통신은 사용자가 직접 호출한 LLM API 요청과 새 버전 확인뿐입니다. 이런 구조 덕분에 오프라인 환경에서도 기록 조회가 가능하고, 민감한 프로젝트 코드가 외부 서버로 전송될 우려가 없습니다.
번들 크기는 60MB 미만이며 Electron 대신 Tauri 네이티브로 빌드되어 콜드 스타트 시간이 1.5초 미만입니다. 현재 Apple Silicon 기반 macOS 용 .dmg 파일을 무료로 다운로드 할 수 있으며, Windows 버전은 추후 지원 예정입니다.
자동 기록 대상 에이전트는 Claude Code, Codex, Cursor, Gemini CLI 등 11종입니다. 에이전트가 작업을 마칠 때마다 기능 추가, 버그 수정, 리팩토링, 에러 사이클, 잡일이라는 다섯 가지 트리거 기준으로 변경 내역을 자동 분류합니다.
다운로드 및 설치 절차
Ocul-PM 을 사용하려면 먼저 데스크톱 앱을 설치하거나 Claude Code 플러그인만 추가하는 두 가지 경로 중 하나를 선택할 수 있습니다. 앱 없이도 플러그인만으로 핵심 기능을 사용할 수 있어 진입 장벽이 매우 낮습니다.
데스크톱 앱을 설치하는 경우의 절차는 다음과 같습니다.
- 공식 홈페이지에서 Apple Silicon 용
.dmg파일을 다운로드합니다. - 다운로드한 디스크 이미지를 열고 앱을 응용 프로그램 폴더로 드래그합니다.
- 앱을 실행하면 프로젝트 폴더를 등록할 수 있는 화면이 나타납니다.
- 추적할 프로젝트 폴더를 선택하면
.oculpm/디렉터리와AGENTS.md규칙 파일이 자동으로 생성됩니다.
앱 설치 없이 Claude Code 플러그인으로 시작하는 방법은 터미널에서 두 줄만 입력하면 됩니다. Claude Code 세션 안에서 아래 명령어를 실행하면 마켓플레이스에서 플러그인을 추가하고 설치합니다.
/plugin marketplace add bunhine0452/Ocul-PM
/plugin install oculpm@oculpm이 명령어를 실행하면 프로젝트 폴더에 .oculpm/ 기록 저장소, AGENTS.md 에이전트 기록 규칙 파일, .gitignore 보호 블록이 생성됩니다. 명령어를 직접 실행한 것 자체가 명시적 동의로 간주되어 별도의 재확인 과정 없이 진행됩니다. 이미 추적 중인 프로젝트에서 실행하면 누락된 구성만 보완합니다.
플러그인 커맨드 사용법
Ocul-PM 플러그인은 프로젝트 시작부터 설계, 구현 루프, 보고까지 전체 과정을 커버하는 다섯 가지 커맨드를 제공합니다. 이 커맨드들은 플러그인 문서 페이지 에서 살아있는 문서로 관리되며, 새 커맨드가 추가되면 함께 갱신됩니다.
권장 작업 흐름
프로젝트를 시작할 때 권장되는 커맨드 순서는 정해져 있습니다.
/oculpm:project_init— 프로젝트를 Ocul-PM 추적 대상으로 초기화합니다./oculpm:inception— 설계 단계를 시드합니다./oculpm:next— 활성 플랜의 다음 미완료 항목을 잡아 구현 사이클을 돕니다./oculpm:standup— 오늘 일지와 플랜 진행을 모아 스탠드업 요약을 만듭니다.
프로젝트 초기화
/oculpm:project_init 커맨드는 현재 프로젝트를 Ocul-PM 추적 대상으로 만듭니다. 실행하면 .oculpm/ 기록 저장소, AGENTS.md 에이전트 기록 규칙, .gitignore 보호 블록이 생성됩니다. 이 커맨드는 유일하게 .oculpm/ 이 없는 비추적 프로젝트에서도 동작하는 예외 커맨드입니다. 앱이 설치되어 있지 않아도 터미널에서 바로 실행할 수 있습니다.
프로젝트 인셉션
/oculpm:inception 커맨드는 project-inception 스킬을 사용하여 설계 단계를 시드합니다. 이 커맨드가 수행하는 작업 흐름은 구체적입니다. 먼저 최소 문제 파악을 수행하고, 웹 리서치로 환경을 탐색한 뒤, 버전과 출처가 명시된 선택지를 사용자와 함께 검토하여 사양을 확정합니다. 그 다음 plan_create 로 3단계 상세 계획을 세우고, EVALS.md 에 완료 정의를 작성하며, 초기 .claude/rules 를 생성합니다.
아이디어를 인자로 전달하여 인셉션을 시작할 수도 있습니다. 예를 들어 /oculpm:inception 할 일 앱을 만들고 싶어 라고 입력하면, 해당 아이디어를 바탕으로 위 과정을 진행합니다.
다음 작업 실행
/oculpm:next 커맨드는 활성 플랜의 다음 미완료 리프 항목을 잡아서 구현 사이클을 돕습니다. 구현 → 게이트 확인 → 일지 작성 → 플랜 갱신의 한 사이클을 수행합니다. 이 커맨드는 앱 플래너의 실행 버튼과 같은 역할을 터미널에서 수행하는 플러그인 대응물입니다. 특정 항목을 지정하여 실행할 수도 있습니다. /oculpm:next login-happy-path 와 같이 입력하면 해당 항목을 바로 작업 대상으로 삼습니다.
기능 추가를 할 때 낯선 영역이라면 /oculpm:inception 으로 계획을 확장하는 것이 적절합니다. 이미 익숙한 영역이라면 인셉션의 인터뷰와 리서치 과정을 생략하고 바로 /oculpm:next 부터 시작해도 됩니다.
스탠드업 요약
/oculpm:standup 커맨드는 오늘 일지와 플랜 진행 상황을 모아서 스탠드업 요약을 생성합니다. 한 일, 진행 중이거나 막힌 일, 다음에 할 일이라는 세 가지 구분으로 정리하여 보여줍니다. 팀 스탠드업 미팅이나 개인 일일 리뷰에 바로 활용할 수 있는 형식입니다.
MCP 도구와 안전 계약
에이전트가 마크다운 규격을 흉내 내어 직접 파일을 작성하는 대신, Ocul-PM 은 전용 도구를 통해 기록을 남깁니다. 경로, frontmatter, 항목 id 규격은 서버가 보장하여 기록 형식이 일관되게 유지됩니다. 모든 MCP 도구는 .oculpm/ 이 있는 추적 프로젝트에서만 동작합니다.
플러그인은 커맨드 5개, MCP 도구 5개, 스킬 5개, 훅으로 구성되어 있습니다. 이 전체 표면을 레퍼런스 카드 한 장으로 보여주고, 현재 상황에 맞는 다음 한 걸음을 추천하는 기능도 제공합니다.
안전 계약은 도구가 읽고 쓰고 절대 하지 않는 작업의 범위를 명확히 정의합니다. 이 계약은 저장소의 플러그인 계약 문서에서 확인할 수 있으며, 에이전트가 프로젝트 코드를 임의로 수정하거나 의도하지 않은 범위의 파일을 건드리는 것을 방지합니다.
앱과 플러그인의 연동
데스크톱 앱을 설치하면 플러그인으로 남긴 기록을 시각적인 타임라인과 일일 브리프로 확인할 수 있습니다. v2.7.0 에서 도입된 메인 화면은 벤토 콕핏 형태로, 이어서 일할 프로젝트의 다음 할 일, 최근 기록, 14일 활동 추이, 마지막 에이전트 작업 내역을 한 화면에 모아 줍니다. 오늘의 흐름 기능은 전 프로젝트 일지를 시간순으로 모아서 보여줍니다.
키보드만으로 전체 조작이 가능합니다. 아무 데서나 타이핑을 시작하면 검색이 되며, 한국어 초성 검색을 지원합니다. 방향키와 엔터로 이동 및 열기를 수행하고, ⌘O 로 폴더를 열며, ⌘N 으로 새 프로젝트를 만들고, ⌘E 로 이름을 변경하며, ⌘⌫ 로 제거할 수 있습니다.
일지 없이 끝난 Claude Code 세션을 감지하는 기능도 있습니다. 미기록 세션 신호는 일지 없이 종료된 세션을 Today 화면에 카드 형태로 알려 주어, 사후 기록을 유도합니다. 사후 기록이 완료되면 카드는 자동으로 해소됩니다. 상태줄 배지와 /oculpm:inception, /oculpm:next 커맨드를 통해 이러한 미기록 세션을 관리할 수 있습니다.
회고 생성과 스킬 승격
v2.6.0 부터는 회고 문서도 Claude Code 가 직접 작성합니다. 별도 API 키나 과금 없이 터미널 세션이 회고 내용을 생성하여 .oculpm/retro/ 폴더에 마크다운으로 저장합니다. 회고 생성 과정과 사용된 모델 정보가 실시간으로 표시됩니다.
반복되는 작업 패턴을 스킬로 승격하는 기능도 있습니다. 같은 태그가 반복되어 나타나면 회고 화면이 스킬 후보를 제안합니다. 사용자가 승인하면 해당 스킬이 .claude/skills/ 디렉터리에 저장되어 이후 작업에서 재사용할 수 있습니다. 이 기능은 반복되는 작업 패턴을 자동으로 학습하고 재사용 가능한 형태로 추출하여 작업 효율을 높여 줍니다.
계획이 구현을 끌고 가는 작업 방식
v2.5 에서 v2.7 로 이어지는 업데이트의 핵심 방향은 기록에서 계획으로의 전환입니다. 기록은 시작점일 뿐이었으며, 이제는 계획이 구현을 이끄는 구조로 발전했습니다. 플래너의 실행 버튼을 누르면 계획 항목이 곧바로 에이전트 실세션이 되어 작업이 시작됩니다.
백미러가 핸들이 되는 릴리스.
이전까지는 작업을 마친 뒤에 기록을 남기는 방식이었습니다. 이제는 플랜의 각 항목이 실행 단위가 되어, 계획된 순서대로 에이전트가 구현을 진행하고 완료된 항목은 자동으로 일지에 기록됩니다. 리서치 확정 버전으로 셋업을 자동화하고, 이메일 로그인 happy-path 같은 구체적인 항목을 플랜에 넣으면 실행 버튼 하나로 에이전트 세션이 시작됩니다.
이 흐름을 터미널에서 재현하면 /oculpm:inception 으로 계획을 세우고 /oculpm:next 로 각 항목을 순차적으로 실행하는 방식이 됩니다. 플랜의 리프 항목이 끝날 때까지 /oculpm:next 를 반복하며, 모든 작업이 끝나면 /oculpm:standup 으로 결과를 정리합니다.
Ocul-PM 은 에이전트가 코드를 쓰는 동안 기록과 관리, 검증을 맡아 주는 로컬 우선 동료입니다. 프로젝트 폴더에 규칙 파일 하나를 심는 것으로 시작하여, 세션이 끝난 뒤에도 작업 맥락이 마크다운 일지로 남아 언제든 다시 꺼내 볼 수 있습니다. GitHub 저장소 에서 한국어 문서와 변경 이력, 이슈 트래커를 확인할 수 있습니다.