작업 일지

마지막 수정 2026-08-21

작업 일지는 이 앱의 존재 이유입니다. 에이전트가 무엇을 왜 했는지를 사람이 읽는 마크다운으로 남깁니다. 커밋 메시지보다 길고, 회의록보다 짧습니다.

언제 쌓이나 — 다섯 순간

에이전트는 작업 하나가 끝날 때마다 기록합니다. AGENTS.md 규칙이 정의하는 순간은 다섯입니다:

트리거언제
bug재현되던 결함이 해소된 것을 직접 확인했을 때
feature새 기능의 첫 happy-path 가 동작할 때
refactor기능은 그대로 두고 구조를 바꾼 묶음이 끝나고 테스트가 그린일 때
error진단·수정 사이클 한 번 — 실패해도 기록합니다
chore설정·문서 등 비기능 변경이 끝났을 때
참고

error 가 실패까지 기록하는 게 핵심입니다. "무엇을 시도했고 왜 안 됐는가" 가 남아야 다음 세션의 에이전트가 같은 벽에 다시 부딪히지 않습니다.

파일 구조

.oculpm/journal/20260821/Bugs/0010_bug_session-attribution.md
                └ 워크데이  └ 분류   └ 시각 └ 종류 └ 이름

분류 폴더는 다섯 가지입니다 — Bugs · Features_to_add · Errors · Refactors · Chores.

일지 한 편에 들어가는 것

머리말(frontmatter)에 기계가 읽는 사실이, 본문에 사람이 읽는 서술이 들어갑니다.

---
type: bug
status: done
difficulty: high
created_at: "2026-08-21T00:10:14+09:00"
session_id: "20260821-002"
agent:
  id: claude-code
  version: claude-opus-5
files_touched:
  - path: "src/cache.rs"
    op: update
related: []
tags: [dogfooding]
---

[x] 제목 한 줄

## 발생 원인
…
## 해결 방법
…
## 검증
어떻게 확인했는지 1~3줄
  • status — planned · in_progress · done · abandoned
  • difficulty — verylow ~ superhigh (선택)
  • 본문 헤더 순서는 종류마다 고정입니다: bug·error 는 발생 원인 → 해결 방법, refactor 는 동기 → 변경 요약, feature 는 추가 기능 → 동작 흐름. 공통으로 끝에 ## 검증 이 필수입니다.
팁

## 검증 이 강제인 이유는 하나입니다 — "고쳤습니다" 와 "고쳤고 이렇게 확인했습니다" 의 신뢰도 차이가 크기 때문입니다. 나중에 그 일지를 읽는 사람(혹은 에이전트)이 재확인할 실마리가 됩니다.

변경 diff — 그때 실제로 바뀐 것

일지마다 그 시점의 git diff 가 함께 보관됩니다. 작업 일지 화면에서 일지를 열면 왼쪽에 서술, 오른쪽에 변경 파일 목록과 줄 단위 diff 가 뜹니다.

나중에 그 파일이 몇 번 더 바뀌어도 일지에 붙은 diff 는 그때 그대로입니다. 커밋 여러 개에 흩어진 변경도 일지 하나로 묶여 보입니다.

참고

이 일지에는 기록된 변경이 없어요 가 뜬다면 대개 둘 중 하나입니다 — git 저장소가 아니거나, 적힌 파일 경로를 git 이력에서 못 찾은 경우. 그때는 화면 아래에서 현재 변경을 직접 확인할 수 있습니다.

세션 — 일지를 묶는 단위

앱은 파일이 바뀌는 것을 지켜보다 세션을 엽니다. 에이전트가 일하기 시작하면 열리고, 한동안 조용하면 닫힙니다. 세션 하나는 보통 "한 번 앉아서 한 일" 에 해당하고, 20260821-002 처럼 날짜와 순번으로 불립니다.

일지는 어느 세션의 산물인지로 묶입니다. 에이전트가 세션 번호를 직접 알 수 없는 경우(터미널에서 파일을 직접 쓰는 등)에도 앱이 작성 시각으로 알아서 귀속시키므로, 여러분이 신경 쓸 것은 없습니다.

정직성 감사

오늘 현황(⌘1) 화면 아래쪽에 가끔 뜨는 카드입니다. 앱이 실제로 관측한 파일 변경과, 일지에 적힌 files_touched 를 맞춰 보고 어느 일지에도 안 적힌 변경을 보여 줍니다.

  • 오늘 바뀐 파일이 전부 어딘가에 기록돼 있으면 카드가 아예 안 뜹니다 — 깨끗한 날에 소음을 내지 않습니다
  • 임시 파일·에디터 부산물·에이전트 내부 상태 파일은 애초에 세지 않습니다
  • 커버리지 80% 이상이면 「경미」, 50% 이상 「주의」, 그 아래 「심각」

이 카드가 자주 뜬다면 플러그인(훅 브리지)을 설치하는 게 가장 확실한 해법입니다. 기록이 "모델이 규칙을 기억해 주는 만큼" 에서 "세션이 끝나면 구조적으로" 로 바뀝니다.

일지를 다루는 법

  • 검증 표시 — 사람이 읽고 맞다고 확인한 일지는 「검증됨」으로 걸러 볼 수 있습니다
  • 직접 고치기 — 평범한 마크다운입니다. 에디터로 열어 고치면 앱이 알아서 다시 읽습니다
  • 내보내기 — 회고 화면에서 구간을 골라 .md 로 묶어 내보낼 수 있습니다
주의

.oculpm/index/ 안은 앱이 관리하는 캐시입니다 — 직접 고치지 마세요. 나머지(journal/·planner/·discussion/)는 전부 여러분의 파일입니다.

다음 걸음