마크다운 한 장으로
팀을 운영하는 법

배경

문서는 있는데, 찾기가 어렵습니다. 키워드를 정확히 알아야 하고, 결국 사람한테 물어보게 됩니다.

기록은 남기는데, 이어서 보기가 어렵습니다. 관련 이슈끼리 맥락을 연결해서 한눈에 보고 싶은데 안 됩니다.

협업하는 사람들의 문서를 연결해서 하나의 지식으로 볼 수 있는 방법이 없을까?

2021

Roam Research와 Obsidian을 접함. 거의 완벽한 도구였지만, 진입장벽이 높고 관리 리소스가 많이 필요했음. 포기.

"A note-taking tool for networked thought"

팀에 공유하던 시절

2026

이번엔 달랐습니다.
처음부터 배울 필요가 없고, 관리도 Claude가 해줍니다.

Obsidian을 Claude의 뇌로 사용하자.

로컬 파일 — 전부 .md로 내 컴퓨터에 저장. 작업은 로컬에서, 공유는 Git으로.

위키링크 — [[문서명]]으로 문서 간 연결. Graph View로 시각화.

태그 — WORK.md에서 #상현 #은별로 담당자, #고도화 #루틴으로 분류. 검색·필터가 바로 됨.

Claude 호환 — 같은 폴더에서 검색·읽기·쓰기. 별도 연동 없음.

무료.

실제 vault의 Graph View — 문서끼리 연결된 구조

읽고, 쓰고, 쌓인다

1. 기준을 마크다운으로 정리
SQL 규칙, 기관별 기준, 과거 실수를 파일로 남겨둠.

2. Claude가 읽고 작업
CLAUDE.md는 세션 시작 시 자동 로드. docs·sql은 작업 중 Claude가 직접 검색해서 읽음.

3. 새로 알게 된 기준을 다시 저장 → 반복
다음 세션은 이번에 쌓인 지식까지 포함해서 시작됨.

CLAUDE.md 안에 실제로 뭐가 있나

우리 팀 CLAUDE.md는 이런 것들이 적혀있음:

· SQL 키워드 소문자, where true로 시작, 조인 alias는 t1·t2·t3
· KRW 금액은 amount / 1e4, any_value() 사용 금지
· 마트 컬럼명: 기간 > 집계함수 > 대상명사 > 속성 순서
· prod 테이블 조회 전 반드시 사람에게 확인
· 작업 완료 후 docs에 기준 문서 남기기

처음엔 10줄이었는데 지금은 200줄. 팀이 틀렸던 것, 반복했던 것이 전부 규칙이 됨. 이걸 매 세션 자동으로 읽으니까, 누가 Claude를 써도 같은 기준에서 출발.

이 문서들을 처음부터 앉아서 작성한 게 아님. CLAUDE.md만 직접 작성했고, Memory는 Claude가 알아서 저장. 62개 문서 + 30개 Memory는 수개월간 일하면서 자연히 쌓인 것.

CLAUDE.md — 팀 규칙서

Memory — 실수 교훈, 도메인 지식

WORK.md — Jira를 대체한 상태판

Jira에선 이슈 323건 중 본문이 있는 건 92건(28%). 나머지는 제목만 있는 빈 티켓.
WORK.md는 체크박스 한 줄에 담당자, 시작 주차, 기한, 태그, 기준 문서 링크가 다 붙어있음:

- [ ] DAXA 공통기준 마련 요청 회신 (W18, 04/28) #외부요청 — CDE-1547 → [[daxa_공통기준_회신_초안]]
- [x] 스테이블코인 보유량/유출입 규모 제출 (성훈, W16, 04/15) #성훈 #외부요청 — CDE-1699 → [[CDE-1699]]

체크박스를 누르면 끝. 상세는 [[문서명]] 링크로 연결된 docs/에 있음.
한 파일에서 진행 중·완료·블로킹이 다 보이고, 기준 문서까지 한 클릭.

실제 WORK.md를 Obsidian에서 열면 이렇게 보임:

MOC 링크 모음 + 체크박스 목록 + 태그 + 위키링크가 한 페이지에

여기서 [[CDE-1699]]를 클릭하면 이런 문서가 열림:

요청 배경, 참조 링크, 요청 내용이 한 페이지에

기준 정리 — 시점별 테이블 차이, 결정 필요 사항, 일보 vs 월보 차이 분석

실제 쿼리까지 문서에 포함 — 다음에 같은 요청이 오면 여기서 시작

누가 Claude Code를 써도 동일한 기준이 적용된다.

LLM Wiki Pattern — Karpathy (2025)

보통 방식: AI에게 지식을 주려면 별도 시스템을 구축해야 함. 문서를 변환하고, 검색 엔진을 붙이고, 파이프라인을 운영.
Karpathy 제안: 그런 거 필요 없음. AI가 직접 위키를 읽고, 새로 알게 된 건 직접 써서 업데이트하면 됨.

CDE가 한 것 — 읽기(벡터 DB 없음), 쓰기(LLM이 위키 업데이트), 루프(쓸수록 정확도↑).

Karpathy gist →

로컬에서 단순하게 운영하기

저희는 관리할 게 적을수록 본업에 집중할 수 있다고 생각해서, 가능한 한 단순하게 운영하고 있습니다.

필요한 정보는 레포를 clone해서 로컬에 둔다.
dbt 모델이 필요하면 dbt-metric 레포를 clone. Airflow DAG 구조가 궁금하면 data-airflow-dags를 clone. Claude가 로컬 파일을 직접 읽으니까 별도 연동 없이 바로 작업 가능.

관리 포인트가 적다.
외부 서비스 연동 없이 로컬 파일만 쓰니까, 서버가 죽거나 키가 만료되는 걱정이 없음. 뭔가 틀리면 .md 파일 열어서 고치면 끝.

보안이 단순하다.
데이터가 로컬에서 벗어나지 않으니까 보안 리뷰가 간단함. 금융 데이터를 다루는 팀에겐 이게 편함.

셋업이 5분이다.
git clone → Obsidian vault 열기 → 기준 문서 작성. 새 팀원이 와도 5분이면 같은 환경에서 시작.

도구를 더 쓰면 더 잘 될 수도 있겠지만, 지금은 마크다운 파일과 git만으로 저희한테 필요한 건 충분히 되고 있습니다.

요청이 들어오면

금융 당국 및 외부 기관에 데이터를 제출하는 팀입니다. 기한은 짧고, 기관마다 기준이 다르고, 작업할 때 2~3년치 변경 이력까지 고려해야 합니다. 이 기준이 사람 머릿속에만 있어서, 파일에 쌓아두고 AI가 조합하는 방식을 택했습니다.

01

Slack 요청을 그대로 붙여넣기

DAXA 코인 이전 데이터 긴급 추출 요청. 요청서 텍스트를 Claude에 그대로 전달.

02

Claude가 관련 기준을 직접 찾아 읽음

· cp_address_info MOC에서 구조와 기존 패턴 확인
· Memory에서 v1/v2 차이, CDE-1673 선례 참조
· CLAUDE.md에서 SQL 규칙, 컬럼 명명 규칙 로드

03

SQL 초안 작성 + 검증 포인트 제시

초안을 파일로 작성하고, 사람이 확인해야 할 것 2가지를 알아서 짚어줌. 초안 작성까지 수 분.

같은 방식으로 처리한 다른 건

AML 스테이블코인 테마모니터링 — 기한 4일
4개 소스 테이블을 조합하는 작업. 업무용 계정 제외, 단위 환산 같은 규칙을 Claude가 Memory와 CLAUDE.md에서 알아서 적용. 이 조합을 사람이 처음부터 파악하면 반나절인데, 초안은 바로 나왔고 검증 1회로 확정.

의원실 스테이블코인 보유·유출입 — 기한 1일
25년 3월 vs 26년 3월 보유량 비교. 함정: 두 시점에 써야 하는 소스 테이블이 다름. 모르고 같은 테이블로 추출하면 에러 없이 숫자가 조용히 틀림. Memory가 이 차이를 알고 있어서 자동 구분 적용.

여기에 쓰인 건 마크다운 파일과 텍스트 파일뿐입니다. RAG도, 프롬프트 엔지니어링도, 별도 프레임워크도 없음.
기준만 글로 남겨두면, 어떤 팀이든 바로 시작할 수 있습니다.

전과 후

정기보고 자동화 → 주 5시간 확보 → 수시 요청 + 고도화에 재투입.
기한 4일 요청을 2시간에 처리할 수 있었던 건 기준을 이미 알고 있었기 때문.
인원은 그대로인데, 일하는 방식이 완전히 달라졌습니다.

기준 자동 적용 — 시점별 테이블 차이, 필터 조건 변경 등을 Memory가 기억. 설명 없이 맞는 테이블, 맞는 필터가 적용됨.

반복 설명 제거 — "이건 금감원 기준이야, 금융위 기준이야?" 같은 확인이 필요 없어짐.

기록의 질 — 의사결정 근거, 기준 변경 이력, 실수 원인까지 문서에 남아있음.

따라하기

발표에서 본 것을 직접 해보고 싶다면. 순서대로 따라하면 됩니다.

Step 1. Obsidian 설치 + 폴더 열기

obsidian.md에서 다운로드 (무료). 설치 후 "Open folder as vault"로 아무 폴더나 열면 됩니다.

폴더 구조를 미리 잡으려 하지 마세요. 빈 폴더 하나면 충분합니다. 구조는 쓰면서 자연히 생깁니다.

Step 2. 기준 문서 하나 쓰기

"매번 AI에게 같은 말 반복하는 것"을 마크다운으로 적으면 됩니다. 처음엔 10줄이면 충분.

예를 들면:

# 우리 팀 규칙

## 코드 컨벤션
- 변수명은 snake_case
- 커밋 메시지는 한국어로

## 자주 쓰는 테이블
- 유저 정보: user_account (PII 주의)
- 거래 내역: trade_history (파티션: _PARTITIONTIME)

## 반복되는 실수
- prod 테이블 조회 전 반드시 확인 받기
- 금액 단위 환산 빠뜨리지 말 것

Claude Code를 쓴다면 → 파일명을 CLAUDE.md로 저장. 매 세션 시작할 때 자동으로 읽힘.
Claude 웹을 쓴다면 → 프로젝트에 파일을 첨부하거나, 대화 시작할 때 내용을 붙여넣기.

Step 3. 평소처럼 일하기

AI에게 기준 문서를 읽게 하고 평소 하던 작업을 시키면 됩니다. 특별한 프롬프트가 필요하지 않습니다.

작업 중 "이건 다음에도 기억하면 좋겠다" 싶은 게 있으면 같은 폴더에 메모. Claude Code라면 작업 중에 알아서 Memory에 저장하기도 합니다.

Step 4. 작업 끝나면 "정리해줘" 한마디

작업이 끝나면 이렇게 말해보세요:

"이번 작업 배경이랑 기준 정리해서 md로 남겨줘"

AI가 작업 내용을 정리해서 마크다운 파일을 만들어줍니다. 이게 한 장씩 쌓이면서 팀의 기준 문서가 됩니다.

처음부터 문서 구조를 잡으려 하면 안 하게 됩니다. 일단 쌓고, 10개쯤 모이면 그때 정리해도 늦지 않습니다.

Step 5. 공유하기

혼자 쓴다면 여기서 끝. 팀과 공유하고 싶다면:

· 폴더를 Git 레포로 초기화 → GitHub에 push
· 팀원은 clone해서 같은 폴더를 Obsidian vault로 열면 됨
· 이후 pull/push로 동기화

Git을 안 쓴다면 공유 드라이브에 폴더를 두는 것만으로도 됩니다. 핵심은 같은 기준 문서를 여러 사람이 쓰는 것.

Step 6. 반복 — 쓸수록 두꺼워진다

Step 3~5를 반복하면 이런 일이 생깁니다:

· 기준 문서가 10줄 → 50줄 → 200줄로 자람
· 작업 기록이 docs/ 폴더에 하나씩 쌓임
· 문서가 10개 넘으면 주제별 목차 노트(MOC)로 묶기 시작
· AI가 다음 작업할 때 이전 기록을 참고해서 정확도가 올라감

처음엔 빈 폴더 + 10줄짜리 파일 하나. 수개월 후에는 62개 문서 + 30개 Memory + 11개 MOC.
일하면서 자연히 쌓인 것이지, 앉아서 작성한 게 아닙니다.

주의할 점

플러그인은 최소한으로.
Obsidian은 커뮤니티 플러그인이 많지만, 추가할수록 관리 리소스가 늘어남. 특히 클라우드 동기화(Obsidian Sync 등)를 켜는 순간 보안 검토가 필요해짐. 처음엔 기본 기능만으로 충분합니다.

AI 초안은 반드시 사람이 검증.
특히 숫자가 들어가는 작업은 크로스체크 필수. AI가 자신 있게 틀린 숫자를 내놓을 수 있습니다. 초안을 만드는 속도가 빨라진 만큼, 검증에 시간을 더 써야 합니다.

기준 문서에 너무 많이 넣으면 역효과.
CLAUDE.md(기준 문서)는 매 세션 전체를 읽기 때문에, 너무 길면 핵심이 묻힘. 핵심 규칙만 남기고, 상세한 내용은 별도 파일로 분리하는 게 좋습니다.

AI가 저장한 정보에 틀린 것도 섞임.
Memory나 docs에 AI가 쓴 내용이 100% 맞다고 보장할 수 없습니다. 한 달에 한 번 정도 훑어보면서 틀린 내용을 수정하거나 삭제하세요.

이런 경우에도 쓸 수 있습니다

팀 간 협업
상대 팀의 기준 문서가 있으면 AI가 두 팀의 컨텍스트를 함께 읽고 작업 가능. 지금은 협업할 때마다 서로의 기준을 구두로 설명하고 있다면, 문서 하나 공유하는 것만으로 상당 부분 해결됩니다.

새 팀원 온보딩
기준 문서가 있으면 구두 설명 없이 AI를 통해 팀 컨텍스트에 접근 가능. "이 프로젝트 처음인데 뭐부터 보면 될까요?"를 AI에게 물으면, 기준 문서를 바탕으로 안내할 수 있습니다.

담당자 변경
기준과 판단 근거가 파일에 남아있으면 사람이 바뀌어도 컨텍스트가 유지됩니다. "왜 이렇게 했지?"가 문서에 있으니까.