자주 묻는 질문

마지막 수정 2026-08-21

처음 며칠 동안 실제로 자주 나오는 질문들입니다. 개념이 헷갈리는 것과 겁나는 것을 먼저 풀었습니다.

이게 뭘 해주나요

한 줄로

AI 에이전트가 여러분의 코드에 무슨 짓을 했는지, 사람이 읽을 수 있는 기록으로 남깁니다.

커밋 메시지는 무엇이 바뀌었나만 말합니다. Ocul-PM 은 왜 그렇게 했고, 무엇을 시도했다 실패했고, 어떻게 확인했는지를 남깁니다.

일지는 제가 써야 하나요?

아니요. 에이전트가 씁니다. 여러분은 읽기만 하면 됩니다.

프로젝트를 추가하면 루트에 AGENTS.md 라는 규칙 파일이 생기고, Claude Code·Cursor·Gemini CLI 같은 에이전트가 이 파일을 읽습니다. "작업 하나를 끝내면 일지를 남겨라" 가 그 규칙입니다. 여러분이 시킬 필요조차 없습니다.

AI 를 대신 실행해 주는 앱인가요?

둘 다 됩니다. 앱 안에 Claude Code 를 띄워 쓸 수도 있고, 평소처럼 터미널에서 쓰면서 기록만 받을 수도 있습니다. 앱을 켜 두기만 하면 터미널에서 한 작업도 잡힙니다.

돈과 프라이버시

돈이 드나요?

앱은 무료고, 기록 기능 자체는 API 키가 필요 없습니다. 파일 변경을 관측하고 에이전트가 쓴 마크다운을 읽는 게 전부라 비용이 0입니다.

돈이 드는 건 AI 가 새 글을 쓰는 기능뿐입니다:

제 코드가 어디로 나가나요?

기본적으로 아무 데도 안 나갑니다. 코드 검색의 임베딩도 로컬에서 계산합니다. 밖으로 나가는 건 셋뿐입니다 — 여러분이 설정한 LLM 호출, 새 버전 확인, 앱 안 Claude Code 를 쓸 때의 Anthropic 통신. 계정 서버도 텔레메트리도 없습니다. (자세히)

인터넷 없이 되나요?

됩니다. 기록·타임라인·변경 diff·코드 검색·코드 맵·회고 지표는 전부 로컬입니다. AI 호출과 업데이트 확인만 안 됩니다.

Windows / Linux 는요?

지금은 macOS (Apple Silicon) 전용입니다.

git 과 팀

.oculpm/ 을 git 에 커밋해야 하나요?

네, 커밋하는 걸 권합니다 — 그리고 앱이 알아서 준비해 둡니다.

프로젝트를 추가하면 .gitignore 에 관리 블록이 하나 붙어서, 캐시성 파일만 제외합니다:

# oculpm:begin v1
.oculpm/index/
.oculpm/hooks/
.oculpm/.lock
.oculpm/.schema-version
.oculpm/oculpm.log
.oculpm.backup-*/
# oculpm:end

그래서 일지·플래너·토의·규칙은 커밋되고, 앱이 다시 만들 수 있는 것은 빠집니다. 여러분이 손댈 일이 없습니다.

팀원과 공유되나요?

커밋해서 push 하면 그대로 공유됩니다. 팀원은 앱이 없어도 GitHub 에서 마크다운으로 읽을 수 있고, 앱을 설치하면 그 기록이 화면에 그려집니다.

충돌나지 않나요?

일지는 파일 하나에 작업 하나고 이름에 시각이 들어가서(2337_fix_...md) 서로 겹칠 일이 거의 없습니다. 플래너는 한 파일을 여럿이 고칠 수 있는데, 변경 로그가 덧붙이기 전용이라 충돌이 나도 양쪽 줄을 다 남기면 끝입니다.

남의 저장소에 일지를 남기고 싶지 않으면요?

.gitignore 에 .oculpm/ 을 통째로 넣으면 로컬에만 쌓입니다. 앱 동작에는 아무 영향이 없습니다.

개념이 헷갈려요

「워크데이」가 뭔가요?

하루의 경계를 여러분이 정하는 것입니다. 기본은 자정이지만, 새벽까지 코딩하는 사람에게 자정 경계는 불편합니다 — 새벽 2시에 한 일이 "내일" 로 넘어가 버리니까요.

프로젝트의 .oculpm/config.toml 에서 day_starts_at = "03:00" 처럼 바꾸면, 새벽 3시 전의 작업은 전날 폴더에 쌓입니다.

「세션」이 뭔가요?

앱이 파일 변경을 지켜보다가 에이전트가 일하기 시작하면 열고, 한동안 조용하면 닫는 단위입니다. 대략 "한 번 앉아서 한 일" 에 해당하고 20260821-002 처럼 불립니다. 일지가 어느 세션의 산물인지 자동으로 묶입니다.

일지 · 플래너 · 문제 해결, 뭐가 다른가요?

시간축이 다릅니다:

「UI 언어」와 「AI 작성 언어」가 따로 있던데요?

다릅니다. UI 언어는 화면에 보이는 텍스트고, AI 작성 언어는 AI 가 새로 만드는 일지·플래너 항목·회고의 언어입니다.

영어 화면으로 쓰면서 기록은 한국어로 남기는 게 가능합니다. 이미 기록된 문서는 언어를 바꿔도 그대로입니다.

쓰다 보면

일지가 안 쌓여요

가장 흔한 원인은 터미널에서 에이전트를 쓰는데 플러그인을 안 깐 경우입니다. AGENTS.md 규칙만으로는 모델이 긴 세션 끝에 기록을 잊을 수 있습니다. 플러그인을 설치하면 세션 종료 훅이 걸려 구조적으로 남습니다.

빠진 게 있는지는 오늘 현황의 정직성 감사가 알려 줍니다 — 관측된 변경 중 어느 일지에도 안 적힌 파일을 보여 줍니다. (자세히)

일지를 고쳐도 되나요?

됩니다. 평범한 마크다운이고, 고치면 앱이 알아서 다시 읽습니다. 다만 에이전트에게는 기존 일지를 고치지 말라고 규칙이 걸려 있습니다 — 이력이 조용히 바뀌면 신뢰할 수 없게 되니까요. 에이전트는 새 일지를 쓰고 related 로 잇습니다.

일지가 너무 많아지면요?

날짜별로 접히고, 검색·필터가 있고, 회고가 구간별로 요약해 줍니다. 「검증됨」 으로 걸러 사람이 확인한 것만 볼 수도 있습니다. 그리고 일지는 지워도 됩니다 — 그냥 파일입니다.

앱을 지우면 기록은요?

남습니다. 기록은 전부 프로젝트 폴더 안의 마크다운이고, 앱의 데이터베이스는 화면을 빠르게 그리기 위한 캐시일 뿐입니다.

여러 프로젝트를 동시에 쓸 수 있나요?

됩니다. ⌘T 로 프로젝트 탭을 열고 ⌘P 로 전환합니다. 창을 여러 개 띄워도 됩니다. (자세히)

에이전트를 여러 개 섞어 써도 되나요?

됩니다. 일지에 누가 어느 모델로 했는지 함께 적히고, 회고의 「에이전트 기여」 가 분포를 보여 줍니다. (자세히)

AGENTS.md 를 지워도 되나요?

지우면 에이전트가 기록 규칙을 못 봅니다 — 일지가 끊깁니다. 이미 여러분이 쓰던 AGENTS.md 가 있었다면 걱정 마세요, 앱은 <!-- oculpm:begin --> 블록만 소유하고 나머지는 건드리지 않습니다.

앱을 항상 켜 둬야 하나요?

파일 변경을 관측하려면 켜져 있어야 합니다. 설정에서 「창 닫기 = 메뉴바로 최소화」 를 켜면 창을 닫아도 메뉴바에 남아 계속 관측합니다.

여기 없는 질문이라면

문제 해결을 먼저 보시고, 그래도 없으면 GitHub 이슈로 알려 주세요.