2부 6장. Prompts: 재사용 가능한 워크플로우 템플릿

지난 장에서 우리는 PKM-MCP에 읽을거리를 넣었다. note://{id} 같은 Resource 덕분에 AI는 이제 메모를 검색 결과의 짧은 조각이 아니라, 실제 문서로 읽을 수 있게 되었다. 여기까지 오면 자연스럽게 다음 질문이 생긴다.

그래서 매번 같은 일을 시킬 때도, 같은 설명을 계속 반복해야 할까?

예를 들어 이런 부탁을 자주 한다고 해 보자. 최근 메모를 훑고, 이번 주에 한 일과 떠오른 아이디어를 묶고, 막힌 점과 다음 행동까지 정리해 달라는 요청 말이다. 이 작업은 단순히 문장 하나로 끝나지 않는다. 먼저 어떤 메모를 볼지 고르고, 필요한 메모를 읽고, 겹치는 내용을 묶고, 형식에 맞춰 요약해야 한다. 즉, 이건 질문 한 줄이 아니라 작은 워크플로우에 가깝다.

바로 이 지점에서 Prompt가 빛난다.

Tool이 AI에게 동사를 가르친다면, Resource는 읽을거리를 건넨다. 그리고 Prompt는 그 둘을 어떤 순서로 써야 하는지 알려 주는 작업 템플릿이다. 이제 PKM-MCP는 단순히 기능 목록만 내놓는 서버가 아니라, 일을 처리하는 방식까지 제안하는 서버가 된다.

아주 짧게 정리하면 셋의 역할은 이렇다.

이번 장에서는 Prompt를 단순한 저장 문구가 아니라, 재사용 가능한 작업 템플릿으로 이해해 볼 것이다. 그리고 마지막에는 PKM-MCP에 이번 주 메모 요약 Prompt를 추가해, 서버가 작업 방식까지 제공하도록 만들어 보겠다.

6.1 Prompt가 단순 텍스트 템플릿이 아닌 이유

처음에는 Prompt를 이렇게 생각하기 쉽다. 자주 쓰는 질문을 메모장에 저장해 두었다가, 필요할 때 붙여 넣는 것. 물론 그것도 재사용이긴 하다. 하지만 MCP의 Prompt는 거기서 한 걸음 더 나간다.

MCP의 Prompt는 단순한 복붙 문장이 아니라, 서버가 공식적으로 제공하는 작업 템플릿이다. 이름이 있고, 설명이 있고, 필요한 인자가 있고, 실제 대화에 넣을 메시지 묶음이 있다. 클라이언트는 이 Prompt를 목록으로 보여 줄 수 있고, 사용자는 값을 채워 넣어 실행할 수 있다. 즉, Prompt는 숨겨진 개인 메모가 아니라, 서버가 바깥으로 꺼내 놓은 기능이다.

이 차이는 생각보다 크다. 그냥 저장된 문장은 사람만 알고 쓴다. 하지만 MCP Prompt는 클라이언트와 AI도 발견할 수 있다. 그래서 서버 입장에서는 기능을 하나 더 추가한 것과 비슷한 효과가 난다.

잘 만든 Prompt에는 보통 세 가지가 들어 있다.

• 무엇을 하려는지에 대한 분명한 목적

• Tool과 Resource를 어떤 순서로 쓸지에 대한 작업 흐름

• 결과를 어떤 형식으로 내놓을지에 대한 출력 규칙

예를 들어 이번 주 메모 요약을 그냥 한 줄로 적으면 이럴 것이다.

최근 메모를 보고 이번 주를 요약해 줘.

이 문장도 나쁘진 않다. 하지만 너무 많은 것이 비어 있다. 최근이 며칠인지, 어떤 메모를 먼저 봐야 하는지, 검색이 필요한지, 결과를 어떤 형식으로 써야 하는지 모두 AI의 즉흥 판단에 맡겨 버린다. 날이 좋으면 괜찮은 답이 나오고, 날이 흐리면 엉뚱한 답이 나온다.

반대로 Prompt를 워크플로우로 만들면 이야기가 달라진다. 먼저 note://index를 읽고 최근 수정된 메모를 추리고, 필요하면 search_notes로 특정 주제를 더 찾고, 각 메모의 uri를 따라 본문을 읽고, 마지막에는 이번 주 한 일, 떠오른 아이디어, 막힌 점, 다음 행동 형식으로 정리하라고 지정할 수 있다.

이렇게 되면 서버는 단지 기능만 제공하는 것이 아니라, 좋은 일 처리 습관을 함께 제공하게 된다. 마치 요리 재료만 주는 것이 아니라, 레시피 카드까지 같이 건네는 셈이다.

Prompt를 Tool이나 Resource와 헷갈리지 않으려면 이렇게 기억하면 편하다. Tool은 손이고, Resource는 책장이고, Prompt는 체크리스트다. 손만 있어도 일은 할 수 있다. 책장만 있어도 읽을 수 있다. 하지만 체크리스트가 있으면 덜 빼먹고, 덜 흔들리고, 결과도 더 일정해진다.

특히 팀에서 같은 MCP 서버를 함께 쓸 때 Prompt의 장점은 더 크게 드러난다. 누구는 길게 설명하고 누구는 짧게 설명하는 식의 편차가 줄어든다. 서버가 권장하는 작업 방식이 그대로 노출되기 때문이다. 결국 Prompt는 AI에게 말을 더 잘 거는 장치이면서, 사람 사이의 작업 표준을 만드는 장치이기도 하다.

6.2 인자가 있는 Prompt 만들기

재사용 가능한 템플릿이 진짜로 편해지려면, 내용을 통째로 바꾸지 않고도 상황에 맞게 조절할 수 있어야 한다. 이때 필요한 것이 인자다.

주간 요약 Prompt를 생각해 보자. 어떤 날은 최근 7일만 보고 싶고, 어떤 날은 최근 14일을 보고 싶을 수 있다. 또 어떤 때는 메모 전체를 요약하고 싶지만, 어떤 때는 oauth나 배포처럼 특정 주제만 집중해서 보고 싶을 수도 있다. 이럴 때 본문을 매번 고쳐 쓰기보다 days, focus 같은 인자를 받도록 만들면 훨씬 재사용하기 쉬워진다.

좋은 Prompt 인자는 많이 받는 인자가 아니라, 꼭 필요한 것만 받는 인자다. 독자가 처음 보더라도 용도가 바로 이해되어야 하고, 기본값만으로도 그럴듯하게 동작해야 한다.

주간 요약 Prompt라면 이 정도면 충분하다.

• days: 최근 며칠의 메모를 볼지 정한다

• focus: 특정 주제에 집중할지 정한다

• 필요하다면 나중에 audience 같은 인자를 추가해 출력 톤을 바꿀 수 있다

여기서 중요한 점이 하나 있다. 인자는 구현 세부사항이 아니라 사용자의 의도를 반영해야 한다. 예를 들어 use_resource_first=True 같은 인자는 개발자 머릿속에는 편해도, 사용자에게는 전혀 친절하지 않다. 반면 focus='oauth'는 누가 봐도 의미를 이해할 수 있다.

인자가 있는 Prompt를 만들 때는 세 가지를 기억하면 좋다.

• 기본값만으로도 바로 쓸 수 있어야 한다

• 인자 이름은 사용자의 언어에 가까워야 한다

• 너무 많은 옵션을 넣어 작은 설정 화면으로 만들지 말아야 한다

Prompt의 역할은 복잡한 조정판을 만드는 것이 아니라, 자주 쓰는 흐름을 부드럽게 꺼내 쓰게 하는 데 있다. 버튼은 버튼다워야 한다. 전투기 조종석처럼 생기면 아무도 누르지 않는다.

이번 장의 PKM-MCP에서는 days=7, focus=None을 기본값으로 잡겠다. 즉, 아무 값도 주지 않으면 최근 7일 메모를 기준으로 한 주를 돌아보게 하고, 필요할 때만 특정 주제를 더 좁혀 보도록 만든다.

만들기: PKM에 '이번 주 메모 요약' Prompt 추가하기

이제 직접 붙여 보자. 앞 장까지 만든 PKM-MCP 서버에 아래 함수를 추가하면 된다. 핵심은 Prompt가 직접 요약을 수행하는 것이 아니라, 어떤 순서로 Tool과 Resource를 사용해 요약할지 안내한다는 점이다.

@mcp.prompt()
def weekly_notes_summary(days: int = 7, focus: str | None = None) -> str:
    '''최근 메모를 검토해 주간 요약을 만드는 재사용 가능한 워크플로우.'''
    if days < 1 or days > 30:
        raise ValueError('days는 1 이상 30 이하로 입력하세요.')

    if focus:
        focus_text = f'- 초점 주제: {focus}n'
        search_step = (
            f'2. `search_notes(query='{focus}')` 도구를 호출해 '
            '주제와 관련된 메모 후보를 찾고, 1단계에서 고른 최근 메모와 합친다.n'
        )
    else:
        focus_text = '- 초점 주제: 없음. 최근 메모 전반을 살핀다.n'
        search_step = '2. 필요하면 `search_notes` 도구로 특정 키워드의 메모를 추가로 찾는다.n'

    return f'''당신은 사용자의 개인 지식 관리 비서다.

목표는 최근 {days}일 동안 작성되거나 수정된 메모를 바탕으로 한 주를 돌아보는 요약을 만드는 것이다.

범위:
- 기간: 최근 {days}일
{focus_text}
작업 순서:
1. 먼저 `note://index` Resource를 읽어 메모 목록과 수정 시각을 확인하고, 최근 {days}일 안의 메모만 고른다.
{search_step}3. 최종 후보 메모의 `uri`를 따라 `note://{{id}}` Resource를 읽고, 본문을 확인한다.
4. 서로 비슷한 메모는 하나의 주제로 묶고, 중복된 내용은 합친다.
5. 아래 출력 형식에 맞춰 한국어 마크다운으로 정리한다.

출력 형식:
## 이번 주 한 일
- 실제로 진행한 일과 결정 사항

## 떠오른 아이디어
- 새로 나온 발상, 메모할 만한 관찰

## 막힌 점
- 이해되지 않았던 부분, 미뤄진 일, 장애물

## 다음 행동
- 바로 실행할 수 있는 짧은 체크리스트

규칙:
- 메모에 없는 사실은 추측하지 않는다.
- 중요한 항목 옆에는 근거가 된 메모 제목이나 `uri`를 괄호로 덧붙인다.
- 같은 이야기가 여러 메모에 반복되면 한 번만 요약한다.
- 설명은 짧고 선명하게 쓰고, 장황한 문장은 피한다.
'''

코드는 길어 보이지만, 실제 아이디어는 단순하다. 먼저 인자로 작업 범위를 정한다. 그다음 Resource와 Tool을 어떤 순서로 쓸지 문장으로 정리한다. 마지막으로 결과 형식을 고정한다. 이 세 가지가 Prompt의 뼈대다.

여기서 눈여겨볼 부분을 하나씩 보자.

첫째, days와 focus는 작업 범위를 좁혀 준다. 같은 Prompt라도 최근 7일을 볼지 14일을 볼지에 따라 완전히 다른 결과가 나온다. focus가 있으면 특정 주제 중심으로 읽게 되므로, 메모가 많아져도 훨씬 덜 흐려진다.

둘째, Prompt 안에 Tool과 Resource의 사용 순서가 들어 있다. 이것이 가장 중요하다. note://index로 최근 메모를 고르고, 필요하면 search_notes로 관련 후보를 더 찾고, 마지막에 note://{id}를 읽어 근거를 확인한다. 이 순서가 바로 워크플로우다.

셋째, 출력 형식을 미리 고정해 둔다. 요약 결과를 매번 다른 모양으로 받으면, 읽는 사람도 불편하고 다음 단계 자동화도 어렵다. 반대로 섹션 제목을 고정해 두면 주간 회고 문서로 붙여 넣기도 쉽고, 나중에 다른 도구로 넘기기도 편하다.

Prompt를 추가한 뒤 Inspector나 클라이언트에서 보면 weekly_notes_summary가 Prompt 목록에 나타난다. 값을 입력하지 않으면 기본적으로 최근 7일 메모 요약을 만들고, focus=oauth처럼 주제를 넘기면 해당 주제와 관련된 메모를 더 적극적으로 살핀다.

예를 들어 days=7, focus='oauth'로 실행하면 AI는 대략 이런 식의 일을 하게 된다. 먼저 최근 7일 메모를 추리고, 그 안에서 oauth와 관련된 메모를 더 찾고, 해당 메모 본문을 읽은 뒤, 한 주 동안의 결정 사항과 막힌 점, 다음 행동을 정리한다. 중요한 점은 이 흐름이 매번 대충 그때그때 정해지는 것이 아니라, 서버가 권장하는 방식으로 재사용된다는 것이다.

Prompt를 추가하면 PKM-MCP가 어떻게 달라질까

여기까지 오면 PKM-MCP는 꽤 재미있는 모양이 된다. 처음에는 빈 서버였다. 그다음에는 Tool이 생겨 검색을 할 수 있게 되었고, Resource가 생겨 메모 원문을 읽을 수 있게 되었다. 이제 Prompt까지 붙으니, 서버가 잘하는 작업을 버튼처럼 꺼내 쓸 수 있게 된다.

이 변화는 보기보다 크다. 기능만 모아 둔 서버는 공구함에 가깝다. 망치도 있고 드라이버도 있지만, 무엇을 먼저 해야 할지는 사용자가 매번 생각해야 한다. 반면 Prompt가 있는 서버는 공구함 옆에 작업 안내서가 놓인 셈이다. 초보자도 덜 헤매고, 숙련자도 덜 반복한다.

특히 개인 지식 관리 시스템에서는 이 차이가 크게 난다. 메모를 모으는 것만으로는 생산성이 잘 오르지 않는다. 메모를 읽고, 묶고, 요약하고, 다음 행동으로 연결하는 흐름이 있어야 진짜 도움이 된다. Prompt는 바로 그 흐름을 서버 차원에서 제공한다.

그래서 잘 만든 Prompt는 단순히 친절한 문구가 아니다. 서버의 개성을 만드는 장치다. 어떤 서버는 검색을 잘하고, 어떤 서버는 계산을 잘한다. 그리고 어떤 서버는 일을 정리하는 방식 자체를 잘 제공한다. PKM-MCP는 이제 세 번째 방향으로 한 걸음 들어섰다.

다음 장에서는 여기서 한 걸음 더 나아가 보겠다. 지금까지의 search_notes는 키워드에 의존한다. 하지만 사람의 메모는 꼭 같은 단어를 쓰지 않는다. 비슷한 뜻인데 표현이 다른 경우가 훨씬 많다. 그래서 다음 장에서는 RAG와 의미 검색을 붙여, PKM-MCP가 말뜻까지 더듬어 메모를 찾도록 만들어 볼 것이다.