연재: AI에게 일자리를 빼앗길 불안으로부터 시작하는 하네스 작성 입문

제10회 ← 이전 회차(9회): RAG / Knowledge MCP가 SE 경험자에게 적합한 이유

AI 에이전트, RAG, 로컬 LLM——배워야 할 기술이 차례차례 등장하면서, "어디서부터 손을 대야 할지" 고민하는 분들이 적지 않을 것입니다. 이전 연재까지는 하네스의 기본 구조나 프롬프트 설계(Prompt Design)를 다루어 왔지만, 개발을 진행할수록 "그때 결정한 설계 방침을 어디에 적어두었더라?" 하는 상황이 늘어납니다.

이번에는 설계 메모를 Knowledge MCP(지식 관리 서버)에 등록하는 것을 전제로 한 Markdown 템플릿을 소개합니다. "정리하는 틀"을 가짐으로써 학습의 불안을 경감하고, 지식을 재사용 가능한 자산으로 바꾸어 나갑시다.

회차	제목	상태
1〜4	기초편 (불안의 언어화~하네스의 개념)	✅
5〜9	실전편 (프롬프트 설계~MCP 연동)	✅
10	설계 메모를 Knowledge MCP에 등록하는 것을 전제로 한 Markdown 템플릿	📖
11	로컬 LLM을 사용해야 하는 상황과 외부 LLM에 맡기는 상황	─
12	모델 라우터(Model Router)의 의사 코드(Pseudo code)로 LLM 전환을 설계한다	─
13〜24	운용 설계·테스트·발전편	─

AI 하네스 개발은 판단의 연속입니다. "왜 이 프롬프트 구성으로 했는가", "어떤 조건에서 폴백(Fallback)할 것인가"——이러한 설계 의도는 코드의 주석만으로는 다 추적할 수 없습니다.

설계 메모를 쓰는 것뿐만 아니라, 검색 및 재사용 가능한 형태로 저장하는 것이 중요합니다. Knowledge MCP는 텍스트를 벡터화하여 의미 검색(Semantic Search)할 수 있는 지식 베이스를 제공합니다. "그 설계 판단의 근거는?"이라고 물으면 관련 메모가 돌아오는 환경을 만들 수 있습니다.

Knowledge MCP는 MCP 프로토콜에 준거한 지식 관리 서버입니다. 주요 기능은 다음과 같습니다.

기능	설명
knowledge_upsert	텍스트를 등록·갱신한다
search_knowledge	의미 검색으로 지식을 검색한다
knowledge_list	등록된 지식 목록을 취득한다
knowledge_delete	불필요한 지식을 삭제한다

포인트는 등록하는 텍스트에 구조를 갖추는 것입니다. 자유 기술형 메모를 그대로 집어넣는 것보다 템플릿에 따라 작성하는 것이 나중에 검색했을 때의 히트 정밀도가 높아집니다.

템플릿을 설계함에 있어 3가지 방침을 세웠습니다.

• **YAML 프런트매터(Frontmatter)**로 메타 정보를 기계 판독 가능하게 한다
• 정해진 섹션 구성으로 검색 히트율을 높인다
• 최소한의 필드로 기입 부담을 낮춘다

"템플릿이 무거우면 쓰지 않게 된다"——이는 많은 개발자가 경험하는 함정입니다. 필수 필드는 5개로 압축하고 나머지는 옵션으로 두었습니다.

다음은 Knowledge MCP 등록을 전제로 한 템플릿입니다.

---
title: "설계 메모의 제목"
category: "architecture | prompt | model | integration | operation"
...

필드	필수	설명
title	✅	검색 시 표시될 이름. 구체적으로 작성
category	✅	5가지 종류 중 선택. 검색 필터로 사용
status	✅	메모의 라이프사이클을 관리
created	✅	생성일 (ISO 8601 형식)
updated	✅	최종 수정일
tags	─	자유 기술 태그. 3개 이내 권장

• 배경·동기: Knowledge MCP의 의미 검색에서 가장 히트하기 쉬운 부분입니다. "왜"를 명확하게 작성합시다.
• 검토한 선택지: 나중에 "왜 안 B를 선택하지 않았는가"를 되돌아볼 수 있습니다.
• 결정 사항: 결론을 1~2문장으로. 긴 논의의 요약입니다.
• 영향 범위: 변경이 어디까지 파급되는지 기록합니다.
• 다음 액션: 설계 메모에서 구현 태스크로의 가교 역할을 합니다.

작성한 Markdown을 knowledge_upsert로 등록합니다.

의사코드: Knowledge MCP 등록 예시

import json
def register_design_memo(filepath: str, namespace: str = "design_memos"):
...

등록한 메모는 search_knowledge로 의미 검색(semantic search)할 수 있습니다.

# 검색 예시
results = mcp_client.call(
    server="pgvector-knowledge",
    ...
)

5가지 카테고리는 AI 하네스(Harness) 개발의 주요 설계 영역에 대응합니다.

category	대상	예
architecture	전체 구성 · 레이어 설계	하네스의 모듈 구성
prompt	프롬프트 설계 · 템플릿	시스템 프롬프트 방침
model	모델 선택 · 파라미터	로컬 LLM vs API 판단
integration	외부 연동 · MCP 연결	도구 호출(Tool calling) 설계
operation	운용 · 로그 · 모니터링	에러 핸들링 방침

망설여질 때는 그 설계 판단이 가장 큰 영향을 미치는 레이어로 선택하세요. 완벽한 분류보다 쓰는 것 자체가 더 중요합니다.

구체적으로 어떻게 작성하는지 한 가지 예를 보여드립니다.

---
title: "프롬프트 폴백(Fallback) 전략"
category: "prompt"
...

이 템플릿은 개인 개발뿐만 아니라 팀 개발에서도 활용할 수 있습니다.

개인 개발: 1개월 후의 내가 "왜 이렇게 설계했는가"를 떠올릴 수 있음 -
팀 공유: 새로운 멤버가 설계 경위를 검색할 수 있음 -
AI와의 협업: 에이전트가 search_knowledge를 통해 과거의 설계 판단을 참조하여 일관성 있는 제안을 해줌

특히 세 번째가 AI 하네스 개발만의 고유한 가치입니다. 설계 메모를 등록해 두면, AI 에이전트 스스로가 과거의 방침을 바탕으로 제안을 할 수 있게 됩니다.

Q: 모든 설계 판단을 메모해야 하나요?

A: 아니요. "나중에 이유를 질문받을 것 같은 판단"만으로 충분합니다. 판단 기준은 "1주일 후에 잊어버릴 것 같은가"입니다.

Q: status는 어떻게 운용하나요?

A: draft로 쓰기 시작하여, 구현에 반영되면 approved로 변경합니다. 방침이 바뀌면 archived로 처리하고 새로운 메모를 만듭니다.

Q: Markdown 파일은 어디에 두나요?

A: 프로젝트의 docs/design/ 디렉토리를 권장합니다. Git으로 이력 관리도 가능합니다.

이번 회차의 핵심 포인트를 정리합니다.

• 설계 메모는 "쓰는" 것뿐만 아니라 "검색 가능하게 만드는 것"을 통해 가치가 배가된다
• YAML 프론트매터(Frontmatter) + 고정 섹션 구성의 템플릿으로, 작성 부담과 검색 정밀도의 균형을 맞춘다
• Knowledge MCP의 knowledge_upsert로 등록하고, search_knowledge로 활용한다
• 카테고리는 5종류. 망설여지면 "가장 영향이 큰 레이어"로 선택한다
• 전부 메모할 필요는 없다. "1주일 후에 잊어버릴 것 같은 판단"이 기준이다

배워야 할 기술이 많다고 느껴질 때일수록, 먼저 눈앞의 판단을 정리하는 틀을 갖추는 것이 다음 단계로 나아가는 토대가 됩니다.

제11회: 로컬 LLM을 사용해야 하는 상황과 외부 LLM에 맡겨야 하는 상황

설계 메모를 정리하는 틀을 손에 넣었으니, 다음 회차에서는 AI 하네스 개발에서 피할 수 없는 "모델 선택"의 판단 기준을 깊이 있게 다룹니다. 로컬 LLM(Ollama 등)과 API LLM(OpenAI, Claude 등)을 비용 · 레이턴시(Latency) · 프라이버시 · 정밀도의 4가지 축으로 비교하여, 프로젝트 상황에 맞는 선택을 할 수 있도록 돕는 판단 기준표를 제시합니다.

"전부 API를 쓰면 되지 않나요?", "로컬은 설정이 어려워 보여요" — 이러한 의문에 구체적인 유스케이스(Use case)와 함께 답해 드립니다.

연재: AI에게 일자리를 빼앗길 불안으로부터 시작하는 하네스 작성 입문

저자: @singula00991 ｜ 주 2회 업데이트

다음 회차 (제11회): 로컬 LLM을 사용해야 하는 상황과 외부 LLM에 맡겨야 하는 상황