내 폴더를 지도 한 장으로 — 문서가 어떻게 이어져 있는지 보기 (graphify)

문서가 쌓이면 「이 불량은 어느 회의·어느 시정조치·어느 협력사와 이어져 있지?」를 읽어서 찾기가 어렵습니다. graphify(그래피파이)는 폴더의 문서를 읽어 중요한 것(점)과 그 사이의 관계(선)를 뽑고, 서로 가까운 것끼리 무리로 묶어 지도로 만듭니다. 지도는 폴더에 남아서, 새 대화에서도 그 지도로 답합니다. 아래 말을 순서대로 한 줄씩 치면 됩니다. (예시 자료는 가짜 이름입니다.)

시작 전에

• 빈 폴더 하나를 만들고(이름은 영문으로, 예: 문서 폴더 안 team-docs), 그 폴더에서 클로드(Claude Code)를 엽니다. 데스크톱 앱이면 Code 탭에서 Local → Select folder, 터미널이면 그 폴더 안에서 claude 를 입력합니다. 설치·구독·승인 방식은 02편 「준비물 자세히」와 같습니다.
• graphify 는 파이썬 프로그램입니다(파이썬 3.10 이상). 깔려 있는지는 1단계에서 클로드가 봐 줍니다. 안 깔려 있으면 「준비물 자세히」를 보세요.
• 클로드가 파일을 만들거나 명령을 실행하려고 허락을 물으면 무엇을 하는지 읽고 허락하세요. 이 편에서는 graphify 나 python 으로 시작하는 명령이 나옵니다.
• 이 편의 🤖 답은 모두 2026-10-10 에 실제로 돌려 받은 것을 줄인 것이고, 줄인 곳은 「…」로 표시했습니다. 단 graphify 를 새로 설치하는 경우는 시험하지 않았습니다(「막히면」 2번). 시험은 GEMINI_API_KEY 를 뺀 상태에서 돌렸습니다.

1단계 · graphify 가 있는지, 문서가 밖으로 나가지 않는지 확인하기

아무것도 만들거나 설치하지 않고 보기만 합니다. 「키 값은 말하지 마」를 꼭 넣으세요. 키 값이 화면에 찍히지 않게 하려는 것입니다.

✅ 이렇게 나오면 성공 — 「graphify 가 설치돼 있다」와 키의 「있다/없다」가 나오면 다음 단계로. 키가 「있다」고 나오면 이 편의 3단계 전에 「막히면」 6번을 먼저 읽으세요(위 답은 제 PC 에 키가 있었던 경우입니다. 제 시험은 그 키를 뺀 상태로 돌렸고, 「현재 세션에는 없음」인 것은 그 때문입니다). 「깔려 있지 않다」고 나오면 「막히면」 2번.

2단계 · 연습 자료 6개를 폴더에 두기

가짜 회사 「가나다전자」 품질팀의 문서 6개입니다(회의록·NCR 요약·시정조치·협력사 평가·교육 계획·고객 불만). 서로 이름(김가나·납땜불량·라마바전자)과 번호(CAR-2026-04)로 이어져 있어서, 지도가 무엇을 찾아내는지 보기 좋습니다. 아래 상자의 글을 통째로 복사해서 클로드에게 붙여 넣고 보내면, 클로드가 파일 6개로 저장합니다.

아래 6개 글을 이 폴더에 파일로 저장해 줘. 파일 이름은 「=== 파일:」 줄에 적힌 그대로, 내용은 한 글자도 바꾸지 마. 답은 한국어로.

=== 파일: 회의록-0902.md ===
# 주간회의 2026-09-02 (가나다전자 품질팀)

참석: 김가나(품질), 박나나(생산), 이다라(구매)

- 8월 한 달 NCR 6건 중 납땜불량이 2건으로 가장 많았다. 조립 공정에서 나온다.
- 박나나: 납땜 온도 프로파일이 지난 점검 때 기준을 벗어난 적이 있다. 시정조치(CAR)를 열기로 했다.
- 이다라: 납땜 페이스트는 협력사 라마바전자에서 들여온다. 로트가 바뀐 시점과 불량이 늘어난 시점이 겹치는지 확인한다.
- 담당: 시정조치 문서는 김가나가 쓴다. 납땜 교육 계획은 이다라가 잡는다.

=== 파일: NCR-요약-9월.md ===
# 9월 NCR 요약 (가나다전자)

9월에 발행된 NCR 은 9건이다.

| 원인 | 건수 |
|---|---|
| 납땜불량 | 3 |
| 치수불량 | 2 |
| 도장불량 | 2 |
| 부품불량 | 1 |
| 서류누락 | 1 |

- 납땜불량 3건은 모두 조립 공정이다. 담당은 김가나.
- 부품불량 1건(NCR-011)은 협력사 사아자부품이 납품한 커넥터 문제다.
- 진행 중인 건은 2건(NCR-013 납땜불량, NCR-015 도장불량).

=== 파일: 시정조치-납땜.md ===
# 시정조치(CAR-2026-04) 납땜 불량

- 발행: 2026-09-05, 담당 김가나
- 원인 후보: (1) 납땜 온도 프로파일 이탈 (2) 라마바전자 납땜 페이스트 로트 변경
- 조치: 리플로 오븐 온도 프로파일을 다시 맞추고, 페이스트 로트별 입고 검사를 추가한다.
- 확인: 박나나가 10월 첫 주에 불량률을 다시 본다.
- 관련 문서: 회의록 2026-09-02, NCR 요약 9월

=== 파일: 공급업체-평가.md ===
# 협력사 평가 (2026 하반기, 구매팀 이다라)

## 라마바전자
- 납땜 페이스트 공급. 납기 준수 양호. 8월 말 로트 변경 이후 납땜불량 문의가 늘었다.
- 다음 점검: 로트 성적서 요청 (이다라)

## 사아자부품
- 커넥터 공급. 9월 NCR-011 부품불량 1건. 시정 요구서 발송 예정.

=== 파일: 교육계획-납땜.md ===
# 납땜 교육 계획

- 대상: 조립 공정 작업자 전원
- 강사: 박나나(생산)
- 일정 담당: 이다라
- 내용: 온도 프로파일 읽는 법, 페이스트 보관 조건, 육안 검사 기준
- 계기: 시정조치 CAR-2026-04 (납땜 불량), 주간회의 2026-09-02 결정

=== 파일: 고객불만-0915.md ===
# 고객 불만 접수 2026-09-15

- 고객: 바사차유통
- 내용: 납품한 제어 기판 일부에서 납땜 부위가 들뜬다는 신고. 5개 반품.
- 접수: 김가나. 조립 공정 납땜불량 NCR 과 연결해서 보고 있다.
- 조치: 시정조치 CAR-2026-04 에 고객 재발 방지 항목을 추가했다.

✅ 이렇게 나오면 성공 — 폴더에 .md 파일 6개가 생기면 다음 단계로. (내 폴더로 바로 가려면 이 단계는 건너뛰고, 문서가 든 폴더에서 클로드를 열어 3단계로 가세요.)

3단계 · 지도 만들기

/graphify 한 줄이면 됩니다. 뒤의 . 은 「지금 열린 폴더」입니다. 클로드가 문서를 읽고 정리하는 데 몇 분이 걸립니다. 끝날 때까지 기다리세요. 중간에 허락 창이 여러 번 뜨면 명령 내용을 읽고 허락합니다.

✅ 이렇게 나오면 성공 — 폴더에 graphify-out 폴더가 생기고 그 안에 graph.html·GRAPH_REPORT.md·graph.json 세 파일이 있으면 다음 단계로. 점·선 수는 매번 조금 다르게 나올 수 있습니다. (영어로 답하거나 한참 걸려도 이상한 것이 아닙니다. 「막히면」 3·5번.)

4단계 · 지도 열어 보기 (내가 직접)

이 단계는 클로드에게 말하지 않고 내가 직접 합니다.

1. graphify-out 폴더의 graph.html 을 더블클릭합니다. 브라우저에서 열립니다. (인터넷이 연결돼 있어야 합니다. 「막히면」 1번.)
2. 어두운 바탕에 동그란 점들이 선으로 이어져 있습니다. 많이 이어진 점일수록 크게 그려지고, 같은 무리는 같은 색입니다. 점 이름이 한글로 보입니다.
3. 오른쪽에 Search nodes…(점 이름 찾기) 칸, NODE INFO(「Click a node to inspect it」, 점을 누르면 그 점의 정보를 보여 주는 자리), COMMUNITIES(무리마다 색 표시와 체크칸이 있는 목록)가 있고, 맨 아래에 「24 nodes · 46 edges · 5 communities」 같은 숫자가 있습니다.
4. 점 하나를 눌러 보고, 검색칸에 「라마바」처럼 이름 일부를 쳐 보세요.

✅ 이렇게 나오면 성공 — 점과 선이 보이고 오른쪽에 위 세 칸이 보이면 됩니다. (점을 눌렀을 때의 동작은 제가 화면에서 직접 눌러 보지는 못했습니다. 안 되면 새로고침해 보세요.) 점들이 어떤 덩어리로 모여 있는지 눈으로 보는 것이 이 지도의 쓸모입니다. 빈 화면이면 「막히면」 1번.

5단계 · 지도에 물어보기

이제 말로 묻습니다. 클로드는 문서를 다시 읽지 않고 지도에서 찾아 답합니다. 먼저 한가운데가 무엇인지 묻습니다.

이어서 두 항목이 어떻게 이어지는지 묻습니다.

✅ 이렇게 나오면 성공 — 점 이름과 근거 문서가 나오고, 「문서에 적혀 있음」과 「확인 필요」가 구분되어 있으면 성공입니다. 지도가 이은 선 중 짐작·불확실 표시가 붙은 것은 확정이 아닙니다. 위 답에서도 클로드가 「확인 필요」로 따로 알려 줬습니다. 중요한 판단은 꼭 원문에서 확인하세요.

6단계 · 새 파일을 넣고 지도 갱신하기

문서가 늘면 지도도 고칩니다. 먼저 새 문서 하나를 폴더에 둡니다. 아래 상자의 글을 통째로 복사해서 클로드에게 붙여 넣고 보내면 회의록-1007.md 로 저장됩니다(2단계와 같은 방식입니다. 내 폴더라면 새로 쓴 문서를 폴더에 넣기만 하면 됩니다).

아래 글을 이 폴더에 회의록-1007.md 로 저장해 줘. 한 글자도 바꾸지 말고, 답은 한국어로.

# 주간회의 2026-10-07 (가나다전자 품질팀)

참석: 김가나(품질), 박나나(생산), 이다라(구매)

- 박나나: 시정조치 CAR-2026-04 이후 리플로 오븐 온도 프로파일을 다시 맞췄고, 10월 첫 주 납땜불량은 NCR-018, NCR-019 두 건이다.
- 이다라: 라마바전자에서 로트 성적서를 받았다. 8월 말 로트의 점도가 규격 하한에 가깝다. 구매 쪽에서 교체를 요청한다.
- 결정: 페이스트 로트별 입고 검사는 계속한다. 다음 주 월요일에 CAR-2026-04 효과 확인을 다시 한다. 담당 김가나.

파일이 저장되면 새 파일만 반영하게 합니다. 처음부터 다시 만들면 사용량이 또 듭니다.

✅ 이렇게 나오면 성공 — 점·선 수가 늘고 「새 파일 한 파일만 읽었다」는 말이 나오면 됩니다. 브라우저에서 열어 둔 graph.html 은 새로고침해야 새 지도가 보입니다. (점·선 수와 무리 수는 매번 조금 다르게 나올 수 있습니다.)

7단계 · 새 대화에서도 지도로 답하는지 시험하기

지금 대화를 닫고 같은 폴더에서 새 대화를 엽니다. 터미널이면 /exit 로 나갔다가 그 폴더에서 claude 를 다시 입력하고, 데스크톱 앱이면 같은 폴더로 새 대화를 시작하세요. 이전 대화는 이어지지 않습니다. 지도는 폴더의 graphify-out 안에 남아 있습니다.

✅ 이렇게 나오면 성공 — 클로드가 graphify-out 의 지도를 근거로 문서 이름을 대면서 답하면 성공입니다. 새 대화라 앞 단계 이야기는 없으니, 지도를 읽어서 답한 것이 확실합니다. 위 답처럼 지도가 짐작한 연결은 원문에서도 확인했다고 알려 주면 더 믿을 만합니다.

다 됐습니다 — 이제 이렇게 말하면 됩니다

문서가 든 폴더에서 클로드를 열고 이야기합니다.

• 「/graphify . 끝나면 결과를 한국어로 알려 줘」 (내 문서 폴더를 처음 지도로 만들 때)
• 「지도에서 ○○ 와 △△ 가 어떻게 이어져 있는지 알려 줘.」
• 「지도에서 다른 것과 거의 안 이어진 항목을 알려 줘. 문서가 빠진 건지 보고 싶어.」
• 「GRAPH_REPORT.md 를 쉬운 말로 요약해 줘.」
• 「새 문서를 넣었어. 새 파일만 반영해서 지도를 갱신해 줘.」

막히면

1. graph.html 이 빈 화면이다 → 이 파일은 그림을 그리는 부품을 인터넷(unpkg.com)에서 받아 씁니다(파일 안에 그 주소가 적혀 있습니다). 회사 망이 막으면 빈 화면일 수 있습니다(제가 일부러 막아 보지는 않았습니다). 그때는 인터넷이 되는 곳에서 열거나, 이렇게 말하세요: "GRAPH_REPORT.md 를 쉬운 말로 요약해 줘." 보고서는 인터넷 없이도 읽힙니다.
2. graphify 가 안 깔려 있다고 나오거나 설치가 필요하다 → 설치는 사람이 허락하고 합니다. 이렇게 말하세요: "graphify 를 설치해 줘. 공식 명령은 uv tool install graphifyy 이고, 안 되면 pipx install graphifyy 야. 끝나면 graphify install 도 해 줘." 허락 창에서 명령이 이 세 가지인지 읽고 허락하세요. 파이썬 3.10 이상이 없다고 하면 파이썬부터 깔아야 합니다. (이 PC 에는 이미 깔려 있어 설치 단계는 제가 시험하지 못했습니다.)
3. 클로드가 영어로 답한다 → 처음에 /graphify . 만 쳤을 때 영어로 답했습니다. 말 뒤에 「끝나면 결과를 한국어로 알려 줘」를 붙이면 우리말로 답했습니다. 이미 영어로 답했으면 이렇게 말하세요: "방금 결과를 한국어로 다시 알려 줘."
4. 보고서 맨 위에 「그래프가 필요 없을 수도 있다」고 나온다 → 문서가 아주 짧으면 나오는 안내입니다(제 연습 자료는 약 305단어였고 보고서에 "fits in a single context window. You may not need a graph." 가 적혔습니다). 문서가 몇 개 안 되면 그냥 통째로 읽게 하는 편이 싸고 정확합니다. 이 연습은 작동을 보려는 것이고, 지도는 문서가 많아질수록 쓸모가 큽니다.
5. 사용량이 많이 든다, 오래 걸린다 → 작은 연습 폴더도 첫 지도에 약 6만 4천 토큰이 들었습니다. 문서가 많으면 더 듭니다. 프로젝트별 폴더로 나눠서 따로 만들고, 새 문서는 6단계처럼 갱신으로 더하세요. 처음에는 문서 몇십 개 안쪽 폴더로 시작하세요.
6. 문서 내용이 Gemini 로 갔다고 나온다 / 1단계에서 키가 「있다」고 나왔다 → GEMINI_API_KEY 나 GOOGLE_API_KEY 환경 변수가 있으면 graphify 가 그 키로 문서를 구글 Gemini 에 보냅니다(스킬 설명서에 적힌 동작입니다). 제 첫 시험에서 연습 문서(가짜) 약 2,600토큰이 실제로 나갔고, 결과도 부실해서(점 13개, 파일 경로를 틀림) 클로드가 버리고 다시 했습니다. 진짜 문서라면 이렇게 말해 시작 전에 막으세요: "GEMINI_API_KEY 나 GOOGLE_API_KEY 가 있으면 지도를 만들기 전에 멈추고 내게 물어봐. 문서는 클로드 밖으로 보내지 마."
7. 지도가 이은 선을 그대로 믿어도 되나 → 짐작(INFERRED)이나 불확실(AMBIGUOUS) 표시가 붙은 선은 확정이 아닙니다. 이렇게 말하세요: "이 답의 근거 중 짐작이나 불확실로 표시된 연결이 있으면 알려 줘. 원문에서도 찾아서 확인해 줘." (갱신한 뒤 graph.html 오른쪽의 무리 이름 목록이 GRAPH_REPORT.md 의 이름과 다르게 보인 적이 있습니다. 점·선 수는 같았고 원인은 확인하지 못했습니다. 이름이 어긋나 보이면 보고서의 이름과 점 이름으로 판단하세요.)

한 번에 맡기기 (익숙해진 다음에)

역할: 너는 내 PC 에서 일하는 도우미다. 폴더 하나의 문서들을 graphify 로 「지도」(점과 선으로 이어 그린 그림과 요약 보고서)로 만들고, 그 지도로 내 질문에 답한다. 나는 초보자이니 어려운 말은 풀어서, 한 단계씩 말해 줘.

맥락: graphify 는 클로드 스킬(/graphify)이고 파이썬 프로그램이다. 폴더의 글 파일을 읽어 중요한 것(점)과 그 사이의 관계(선)를 뽑아, graphify-out 폴더에 graph.html(브라우저로 여는 지도)·GRAPH_REPORT.md(요약 보고서)·graph.json(지도 자료)을 만든다. 글 파일의 내용은 클로드가 읽고 정리하므로 그만큼 토큰(사용량)이 든다. 환경 변수 GEMINI_API_KEY 나 GOOGLE_API_KEY 가 설정돼 있으면 graphify 가 문서를 클로드가 아니라 Gemini 로 보내므로, 그럴 때는 멈추고 내게 묻는다. 지도의 선 중 「짐작」(INFERRED)이나 「불확실」(AMBIGUOUS)로 표시된 것은 확정이 아니다. 아무것도 새로 설치하지 않는다.

입력: <운영체제>, <지도로 만들 폴더: 예 지금 열려 있는 폴더>, <확인용 질문 한두 개: 예 가장 많이 이어진 것 세 가지, 두 항목 사이의 길>

작업:
① 확인 — 아무것도 만들기 전에 먼저 본다.
 - graphify 를 쓸 수 있는지 본다(스킬과 graphify 명령). 안 되면 아무것도 만들지 말고 멈춰서, 설치 명령(uv tool install graphifyy 또는 pipx install graphifyy, 이어서 graphify install)을 안내하고 내 허락을 기다린다.
 - GEMINI_API_KEY 와 GOOGLE_API_KEY 가 설정돼 있는지 본다(값은 말하지 말고 「있다/없다」만). 하나라도 있으면 멈추고 내게 묻는다.
 - 폴더 안 글 파일의 개수를 알려 주고, graphify-out 폴더가 이미 있으면 덮어쓰지 말고 멈춰서 묻는다.
② 만들기 — /graphify 로 지도를 만든다. 끝나면 점·선·무리의 수와 든 토큰을 알려 준다.
③ 시험 — 내가 준 확인용 질문에 지도로 답한다. 답의 근거가 「짐작」이나 「불확실」 선이면 따로 알려 준다.
④ 마무리 — 초보자 눈높이로 graph.html 을 여는 법(더블클릭하면 브라우저에서 열린다. 인터넷이 막혀 있으면 빈 화면일 수 있다), 새 파일을 넣은 뒤 지도를 갱신하는 말(예: "새 파일만 반영해서 지도를 갱신해 줘"), 갱신에도 토큰이 든다는 것을 설명한다.

제약: 비밀키·토큰·비밀번호·개인정보를 출력하거나 파일에 쓰지 않기. 오류나 경고를 건너뛰지 않기. 기존 파일을 지우거나 덮어쓰지 않기. 이 폴더 밖에 파일을 쓰지 않기. 내가 허락하기 전에는 아무것도 설치하지 않기. 문서 내용을 클로드 밖으로 보내지 않기(위 Gemini 키 경우).

출력: 한 일, 확인된 상태(글 파일 수·Gemini 키 유무), 만든 파일 목록, 지도 요약(점·선·무리 수, 든 토큰), 확인용 질문의 답과 근거, 검증 결과((가)~(라) 각각 통과/실패), 남은 문제와 다음 조치.

검증: 아래를 파일을 다시 열어서 전부 확인해야 "자동 확인 통과"라고 보고한다. 하나라도 실패하면 완료로 보고하지 말 것.
 (가) graphify-out 폴더에 graph.html, GRAPH_REPORT.md, graph.json 이 있다.
 (나) GRAPH_REPORT.md 맨 위 요약의 점·선 수가 네가 말한 수와 같다.
 (다) graphify-out 말고는 이 폴더 안팎에 새로 생긴 파일이 없다.
 (라) 문서가 Gemini 로 가지 않았다(키가 없었거나, 내가 허락했다).

내가 만들 때는

처음엔 이렇게 시켰습니다. 2026-08-06 14:26, 파이스(제 개인 비서 AI)의 「뇌」 화면을 실제 데이터로 바꾸던 날, 이 도구를 처음 만났습니다. 「클로드야.. 내가 방금 굉장한거 발견했어.. https://github.com/Graphify-Labs/graphify 이거 graphify 이거야..」 그날 파이스의 뇌 화면은 옵시디언 노트 그래프와, graphify 가 파이스의 코드를 읽어 뽑은 코드 지도 두 가지로 바뀌었습니다. 코드 지도는 453점·904선·22무리였고, 그중 연결이 많은 220개만 그렸습니다. 가장 많이 이어진 파일 셋(app.js 73·tools.js 60·server.js 54)이 실제 구조와 맞았습니다.

다음은 문서였습니다. 9월 2일 14:09 이렇게 시켰습니다. 「우리회사 nas 모든 자료 색인한걸 graphify로 표현해줄수 있어?? AI 갈라쇼에 넣을자료인데.. 넌 지금 자기 코드 설계 문서만 지식 그래프로 나타냈는데.. nas자료를 그런씩으로 해줄수 있어??」 회사 공유 서버의 색인 전체를 지도로 걸렀는데, 발표용으로는 더 풍성한 그림이 좋아 기준을 낮춰 점을 더 많이 남겨 다시 그렸습니다. 9월 18일에는 「그래프파이도 스킬로 등록 해 놓고 바탕화면에 하나 복사해서 꺼내줘」라고 해서, 스킬 꾸러미(zip) 하나를 바탕화면에 꺼냈습니다.

실패도 있었습니다. 폴더를 한 번에 색인했더니 지도의 점이 2,465개로 불어나서 「무리 필터」와 「800점 상한」을 넣었습니다. 이 편을 쓰려고 연습 자료로 시험할 때도 걸렸습니다. 제 PC 에 GEMINI_API_KEY 가 있어서 graphify 가 연습 문서를 클로드가 아니라 Gemini 로 보냈습니다. 가짜 문서라 괜찮았지만 진짜 문서였다면 문제입니다. 결과도 부실해서(점 13개, 파일 경로를 틀림) 클로드가 버리고 다시 했고, 그 뒤 시험은 키를 뺀 상태로 돌렸습니다. 그래서 1단계에 키 확인을 넣었습니다. 사용량도 놀랐습니다. 약 305단어짜리 문서 6개의 첫 지도가 6만 4천 토큰이었습니다.

→ 뒷이야기 5단계에서 자세히 보세요. (옵시디언 노트 그래프는 4단계에 있습니다.)