Claude Code나 Codex 같은 AI 에이전트에게 일을 맡기면, 지시는 채팅창에 쓰고 결과는 터미널에 흘러가 버려요. 며칠 지나면 "그때 뭘 시켰더라? 왜 이렇게 고쳤지?"가 기억나지 않죠.
이 문제는 생각보다 간단하게 풀 수 있어요. 지시를 채팅 대신 마크다운 노트에 쓰고, 에이전트가 같은 노트에 결과를 적게 하면 돼요. Obsidian을 이미 쓰고 있다면 따로 도구를 들일 필요도 없어요.
노트 한 장 = 지시서 + 작업 기록#
작업 하나를 노트 한 장으로 만들어요. 위쪽에는 내가 쓰는 지시, 아래쪽에는 에이전트가 쓰는 결과가 들어가요.
---
status: todo
agent: claude
created: 2026-10-01
---
## 목표
로그인 화면에서 비밀번호 오류 메시지가 두 번 뜨는 문제 고치기
## 맥락
- 관련 파일: `src/auth/LoginForm.tsx`
- 지난주 폼 검증 로직을 바꾼 뒤부터 생긴 것 같음
## 완료 조건
- 오류 메시지가 한 번만 뜬다
- 기존 로그인 테스트가 통과한다
## 하지 말 것
- 폼 라이브러리 교체 같은 큰 리팩터링
## 결과
(에이전트가 작성)채팅창에 한 줄로 던질 때보다 손이 조금 더 가요. 대신 완료 조건과 하지 말 것을 적는 순간 지시가 훨씬 또렷해지고, 에이전트가 엉뚱한 방향으로 가는 일도 줄어요.
에이전트에게 넘기는 방법#
노트 경로만 알려주면 돼요. 에이전트는 파일을 직접 읽을 수 있거든요.
tasks/로그인-오류-메시지.md 읽고 작업해줘. 끝나면 노트의 ## 결과에 정리해줘.Obsidian 볼트 안에서 에이전트를 실행하거나, 볼트 경로를 알려주면 같은 방식으로 쓸 수 있어요.
결과를 남기는 규칙 정하기#
결과를 매번 어떻게 적으라고 말하기는 번거로워요. 에이전트가 매 세션 읽는 지침 파일에 한 번만 적어두면 돼요. Claude Code라면 CLAUDE.md, Codex라면 AGENTS.md예요.
## 작업 노트 규칙
- 작업 노트를 받으면 끝난 뒤 `## 결과`에 아래 항목을 적는다.
- 바꾼 파일 목록
- 왜 그렇게 고쳤는지 (선택하지 않은 방법이 있으면 함께)
- 확인한 방법 (실행한 테스트나 명령)
- 남은 일이나 확인하지 못한 부분
- frontmatter의 `status`를 `done` 또는 `failed`로 바꾼다.핵심은 왜 그렇게 고쳤는지예요. 코드 변경은 git에도 남지만, 판단 이유는 따로 적지 않으면 사라지거든요.
status는 보조 정보로만 생각하세요. 에이전트가 중간에 멈추면 값이 안 바뀔 수 있어서, 실시간 상태판으로 믿기엔 부족해요. "끝난 것과 실패한 것을 나중에 골라내는 표시" 정도로 쓰면 충분해요.
쌓인 노트 다시 꺼내 쓰기#
노트가 쌓이면 이게 그대로 작업 기록이 돼요. 이때부터 Obsidian의 장점이 살아나요.
- 검색 — "로그인 오류" 같은 키워드로 당시 지시와 결과를 한 번에 찾아요
- 링크 — 이어지는 작업은
[[로그인-오류-메시지]]처럼 이전 노트를 링크해서 맥락을 넘겨요 - 템플릿 — 잘 굴러간 노트의 구조를 템플릿으로 저장해서 다음 지시에 재사용해요
Dataview 플러그인을 쓴다면 실패한 작업만 모아서 다시 맡길 목록을 만들 수도 있어요.
LIST
FROM "tasks"
WHERE status = "failed"
SORT created DESC이 방식이 맞지 않는 경우#
모든 상황에 맞는 건 아니에요. 여러 에이전트를 동시에 돌리면서 누가 무엇을 잡고 있는지 정확히 추적해야 한다면, GitHub 이슈 같은 전용 도구가 더 확실해요. 노트의 frontmatter는 잠금 장치가 아니라서 두 에이전트가 같은 노트를 동시에 집을 수도 있거든요.
반대로 혼자서 에이전트 몇 개를 번갈아 쓰고, 이미 Obsidian에 생각을 정리하는 사람이라면 잘 맞아요. 기획하던 노트에서 바로 지시서를 쓰고, 결과도 같은 곳에서 읽을 수 있으니까요.
다음 작업 하나부터#
거창하게 시작할 필요는 없어요. 다음에 에이전트에게 맡길 일 하나를 채팅 대신 노트로 써보세요. 목표, 완료 조건, 하지 말 것 세 칸만 채워도 지시가 달라지고, 결과가 노트에 남는 순간 그 작업은 다시 찾을 수 있는 기록이 돼요.
The reasonable man adapts himself to the world; the unreasonable man persists in trying to adapt the world to himself. Therefore, all progress depends on the unreasonable man.
— George Shaw
