Obsidian 메모를 Claude Code가 오늘 구현할 수 있는 요청문으로 바꾸는 절차

금요일 밤, Obsidian에 “가입 유도가 약한 것 같다. 스크롤하지 않으면 무료 PDF 링크를 못 보고 지나치는 사람이 많을 듯”이라고만 메모를 남겼습니다. 월요일 아침, 그 메모를 통째로 Claude Code에 붙여넣고 “이거 고쳐줘”라고 부탁했더니 돌아온 건 화면 두 개 분량의 “현재 상태 정리”였습니다. 코드는 한 줄도 없었습니다.

메모가 나빴던 건 아닙니다. 문제는 메모를 그대로 넘긴 것이었습니다. 저는 그날 배경 설명만 듣다가 30분을 날렸습니다.

Obsidian에는 지식이 쌓여 있는데, 매번 Claude Code에 똑같은 서두를 다시 적고 있다. 짚이는 데가 있다면, 부족한 건 더 똑똑한 AI가 아니라 메모를 “요청문”으로 깎아내는 틀입니다.

핵심 요약

• Obsidian 메모를 그대로 붙이면 Claude Code는 요약 담당이 되고 구현이 늦어집니다. 넘길 건 전문이 아니라 오늘 끝나는 작업 하나뿐입니다.
• 메모에서 뽑는 건 6가지뿐입니다. 목적·건드리지 않을 범위·첫 한 수·확인 방법·유도 경로·되돌리는 법.
• “읽을 범위”와 “건드리지 않을 범위”를 먼저 적어 두면, 결제나 인증으로 멋대로 번지는 사고가 사라집니다.
• 요청문을 템플릿으로 만들어 Obsidian에 저장하면, 다음번부터 처음부터 다시 쓰는 수고가 없어집니다.
• 완료 보고를 믿는 대신, 화면 캡처나 빌드 결과 같은 확인 재료로 판단합니다.

왜 메모를 통째로 넘기면 안 되는가

Obsidian 메모는 미래의 나에게 보내는 편지입니다. 맥락도 망설임도 전부 적혀 있습니다. 바로 그래서 AI에 넘기면 “전부 읽고 이해하려고” 들게 됩니다.

사람 동료라면 긴 메모를 읽고 “요컨대 유도 링크 위치 얘기네”라고 알아서 깎아 줍니다. Claude Code는 그렇게까지 눈치를 봐주지 않습니다. 넘긴 글의 양에 비례해서 정성스러운 요약을 돌려줍니다. 친절한데, 제가 원하는 건 요약이 아닙니다.

그래서 넘기기 전에 사람 쪽에서 깎습니다. 1000자짜리 메모에서 구현에 필요한 30자만 남깁니다. 이 깎는 작업이야말로 매번 반복하던 서두를 없애는 지름길입니다.

메모 정리 자체를 Claude Code에 맡기고 싶은 사람은 먼저 Obsidian 연동의 기본을 읽어 두면, 이 글의 절차가 더 매끄럽게 이어집니다.

메모에서 뽑아낼 6가지 항목

제가 매번 메모에서 뽑아내는 건 다음 6가지뿐입니다. 메모에 이 6개가 다 갖춰져 있지 않아도 괜찮습니다. 비어 있는 칸은 깎을 때 제가 직접 정합니다.

항목	내용	예시
목적	사용자가 얻는 결과를 한 문장으로	방문자가 스크롤하기 전에 무료 PDF 링크를 알아챈다
건드리지 않을 범위	망가뜨리고 싶지 않은 곳	결제 처리, 로그인, 모바일 화면이 깨지는 것
첫 한 수	어디부터 손댈지	첫 화면에 섹션 하나 추가
확인 방법	끝났다고 판단하는 재료	빌드 통과, 변경 diff, 공개 URL의 모양
유도 경로	독자를 다음에 어디로 보낼지	무료 PDF 등록 페이지
되돌리는 법	실패했을 때의 퇴로	이 커밋만 취소하면 된다

핵심은 “건드리지 않을 범위”입니다. 여기를 비워 두면, 유도 링크를 고치는 김에 결제 쪽 코드까지 “겸사겸사 정리해 뒀습니다”라는 말을 들을 수도 있습니다. 먼저 금지 구역을 그어 두는 것이 가장 잘 듣습니다.

AI에 맡길 범위와 사람이 정할 범위

여기를 섞으면 사고가 납니다. 선을 분명히 긋습니다.

• 사람이 정한다: 목적·건드리지 않을 범위·되돌리는 법. 이건 사업 판단이니 AI에 통째로 던지지 않습니다.
• AI에 맡긴다: 첫 한 수의 구체화, 코드 구현, 확인 명령 실행.
• 사람이 마지막에 본다: 공개 URL의 모양과 diff가 의도대로인지. 여기만큼은 눈으로 확인합니다.

판단을 맡겨도 되는 건 “어떻게 만들지”이지 “무엇을 지킬지”가 아닙니다. 지킬 것을 정하는 건 언제나 사람 쪽입니다.

메모를 요청문으로 바꾸는 프롬프트 템플릿

뽑아낸 6항목을 그대로 Claude Code에 넘길 수 있는 형태로 만듭니다. 아래 템플릿을 복사하고, 마지막에 메모만 붙여넣으면 됩니다.

다음 Obsidian 메모를, 당신이 오늘 구현할 수 있는 요청문 하나로 변환하세요.
출력은 아래 6개 항목으로 나누세요. 아직 코드는 작성하지 마세요.

- 목적(사용자가 얻는 결과를 한 문장으로)
- 건드리지 않을 범위(변경하면 안 되는 곳)
- 첫 한 수(최소 변경 하나)
- 확인 방법(빌드·diff·공개 URL 등)
- 유도 경로(독자를 다음에 보낼 곳)
- 되돌리는 법(실패 시 원래대로 돌리는 절차)

【메모】
(여기에 Obsidian 메모를 붙여넣기)

중요한 건 마지막 한 문장, “아직 코드는 작성하지 마세요”입니다. 이게 없으면 Claude Code는 변환과 구현을 한 번에 해치우려 하면서 건드리지 않을 범위의 확인을 건너뜁니다. 일단 요청문을 먼저 뽑게 하고, 사람이 금지 구역을 확인한 뒤에 다시 “그럼 이 요청문대로 구현해 줘”라고 되돌려 줍니다. 이 2단 구성으로 사고가 줄어듭니다.

템플릿 정밀도를 더 끌어올리고 싶은 사람은 Claude Code 프롬프트 설계 심화에 세밀한 표현 요령을 정리해 두었습니다.

복사해서 바로 도는 변환 스크립트

매번 프롬프트를 손으로 짜는 게 번거롭다면, 메모를 객체로 적어서 요청문을 자동 생성해 버립니다. Node.js만 있으면 그대로 돕니다.

// 메모를 "오늘 구현할 수 있는 요청문"으로 바꾸는 최소 스크립트
// 사용법: node note-to-issue.mjs

const note = {
  goal: "방문자가 스크롤하기 전에 무료 PDF 링크를 알아챈다",
  doNotTouch: ["결제 처리", "로그인", "모바일 화면 깨짐"],
  firstStep: "첫 화면에 안내 섹션 하나 추가",
  proof: ["빌드 통과", "변경 diff", "공개 URL의 모양"],
  ctaPath: "무료 PDF 등록 페이지",
  rollback: "이 커밋만 취소하면 원래대로 돌아간다",
};

function toIssuePrompt(n) {
  // 필수 항목이 빠져 있으면, 요청문을 내보내기 전에 알아챌 수 있게 한다
  const required = ["goal", "doNotTouch", "firstStep", "proof"];
  const missing = required.filter((key) => {
    const v = n[key];
    return v === undefined || (Array.isArray(v) && v.length === 0);
  });
  if (missing.length > 0) {
    throw new Error(`요청문에 필요한 항목이 부족합니다: ${missing.join(", ")}`);
  }

  const line = (label, value) =>
    `${label}: ${Array.isArray(value) ? value.join(" / ") : value}`;

  return [
    line("목적", n.goal),
    line("건드리지 않을 범위", n.doNotTouch),
    line("첫 한 수", n.firstStep),
    line("확인 방법", n.proof),
    line("유도 경로", n.ctaPath),
    line("되돌리는 법", n.rollback),
    "아직 코드는 작성하지 말고, 이 범위에서 최소 구현 계획만 돌려주세요.",
  ].join("\n");
}

console.log(toIssuePrompt(note));

실행하면 6줄에 마지막 한 문장을 더한 요청문이 출력됩니다. doNotTouch를 빈 배열로 바꿔서 다시 돌리면, 요청문을 내보내기 전에 “항목이 부족합니다”라며 멈춥니다. 빈칸인 채로 넘겨 버리는 사고를 코드 쪽에서 먼저 걸러내는 장치입니다.

실제로 잘 듣는 장면 3가지

1. 유도 링크 개선 메모 “무료 PDF 링크가 약하다”는 메모를 그대로 붙이면 개선안 설명이 끝없이 이어집니다. 요청문으로 깎으면 첫 한 수가 “첫 화면에 섹션 하나 추가” 한 점으로 좁혀지고, 결제 쪽에는 손대지 못하게 됩니다. 개선 전후 모양을 공개 URL에서 비교하면, 효과를 분위기가 아니라 눈으로 판단할 수 있습니다.

2. 버그 조사 메모 “가끔 로그인 후 화면이 새하얘진다”는 메모는 정보가 너무 많습니다. 요청문에서는 첫 한 수를 “재현 조건과 에러 로그만 먼저 공유”로 좁힙니다. 원인 규명과 수정을 한꺼번에 시키지 않고 우선 재현에 집중시키면, 헛다리 짚는 수정을 피할 수 있습니다.

3. 글 기획 메모 “다음 글, 내부 링크를 제대로 걸고 싶다”는 모호한 메모도 목적을 “관련 글로 가는 내부 링크 2개를 고정한다”로 깎으면 구현 가능해집니다. 확인 방법을 “빌드 통과”로 잡아 두면, 끊어진 링크를 공개 전에 막을 수 있습니다. 글 관련 작업을 맡길 준비로는 비엔지니어를 위한 Claude Code 입문에서 한 번 손에 익혀 두면 든든합니다.

요청문을 템플릿으로 남긴다

한 번 만든 요청문은 일회용으로 버리지 말고 Obsidian으로 되돌립니다. 다음에 비슷한 메모가 왔을 때, 6개 항목째로 재사용할 수 있기 때문입니다.

저는 templates/issue-prompt.md라는 노트를 하나 만들어, 6개 항목의 빈 템플릿을 넣어 둡니다. 새 메모가 오면 그 템플릿을 복사해서 채우기만 하면 됩니다. 서두를 매번 적던 시간이 사라졌습니다.

여기에 더해 Claude Code가 읽어야 할 규칙 자체를 프로젝트에 고정해 두면 요청문이 더 짧아집니다. 프로젝트 공통 약속은 CLAUDE.md 작성법에 모아 두면, 요청문 쪽에서 매번 반복하지 않아도 됩니다.

걸려 넘어지기 쉬운 함정과 고치는 법

처음에 제가 저질렀던 실패를, 고치는 법과 함께 적습니다.

• 메모를 전문 그대로 붙인다: Claude Code가 요약 담당이 됩니다. 고치는 법은, 붙이기 전에 6항목으로 깎는 것. 깎을 수 없는 메모는 아직 요청으로 굳어지지 않았다는 증거이니, 먼저 결론을 한 문장 직접 적습니다.
• 건드리지 않을 범위를 안 적는다: 결제나 인증으로 멋대로 번집니다. 고치는 법은, 빈칸을 허용하지 않고 “특별히 없음”이라고도 적지 않는 것. 최소 하나는 금지 구역을 적는 습관을 들입니다.
• 확인 방법이 “돌아가면 OK”: 완료 보고를 믿을 수밖에 없어집니다. 고치는 법은, 빌드 결과·diff·공개 URL 중 최소 하나는 반드시 지정하는 것.
• 한꺼번에 구현시킨다: 변환과 구현이 섞여서 금지 구역 확인이 날아갑니다. 고치는 법은 “아직 코드는 작성하지 마세요”를 반드시 넣고, 요청문을 확인한 뒤에 구현을 부탁하는 것.

함정은 하나같이 “미리 한 줄만 정해 뒀으면 막을 수 있었던” 것들뿐이었습니다.

자주 묻는 질문

Q. 메모가 단편적이라 6항목을 다 못 채웁니다. 다 못 채워도 괜찮습니다. 최소한 “목적”과 “건드리지 않을 범위”만 정하면 요청문이 됩니다. 나머지는 요청문을 내보낸 다음, Claude Code의 제안을 보고 채워도 늦지 않습니다.

Q. Obsidian 메모를 직접 Claude Code에 읽히는 연동이 필요한가요. 처음에는 필요 없습니다. 메모를 손으로 복사해서 템플릿에 붙여넣는 것만으로 충분히 작동합니다. 같은 작업을 몇 번이고 반복하게 된 다음에 자동 연동을 검토해도 늦지 않습니다.

Q. “아직 코드는 작성하지 마세요”라고 적어도 구현을 시작해 버립니다. 프로젝트의 CLAUDE.md에 “요청문 변환 시에는 코드를 작성하지 않는다”라고 명시해 두면 안정됩니다. 프롬프트 한 번의 지시보다 프로젝트 공통 규칙이 더 잘 지켜집니다.

Q. 요청문은 어느 정도 길이가 적당한가요. 6개 항목으로 합쳐서 10줄 안팎을 기준으로 잡습니다. 그보다 길어지면 하나의 작업에 여러 목적이 섞여 있다는 신호입니다. 작업을 나눠 주세요.

Q. 확인 방법에 무엇을 넣어야 할지 모르겠습니다. 망설여지면 “빌드 통과”와 “공개 URL의 모양” 두 가지로 시작하세요. 이 둘만으로도 완료 보고를 곧이곧대로 믿는 상태에서는 빠져나올 수 있습니다.

실제로 시험해 본 결과

서두의 유도 링크 메모를, 이 6항목 템플릿으로 깎은 뒤 다시 Claude Code에 넘겨 봤습니다. 이번에는 요약이 돌아오지 않고, “첫 화면에 안내 섹션 하나 추가”라는 구현 계획이 맨 먼저 나왔습니다. 건드리지 않을 범위에 적었던 결제 처리에는 전혀 손이 닿지 않았습니다.

검증 스크립트 쪽도, doNotTouch를 일부러 비운 채 돌려 봤더니 요청문을 내보내기 전에 “항목이 부족합니다”에서 멈췄습니다. 빈칸인 채로 넘겨 버리는 가장 흔한 사고를, 실행 전에 막을 수 있다는 걸 확인했습니다.

똑똑한 지시를 매번 쥐어짜는 것보다, 메모를 깎는 틀을 하나 갖는 편이 빠르다. 이게 지금의 실감입니다. 같은 방식을 팀의 글 작성이나 문의 대응에도 넓히고 싶은 사람은 업무용 연수·상담에서 실제 운영에 맞춰 틀을 짤 수 있습니다. 공식 기준은 Anthropic 공식 문서에서 확인할 수 있습니다.