지식 연결을 검토하고 정리하기

Link Map의 유지보수 도구는 문서를 자동으로 고치는 기능이 아니다. Glif가 검토할 후보와 원문 문맥을 모아 보여 주고, 사용자가 각 후보를 확인한 뒤 연결·숨기기·병합을 명시적으로 선택하는 작업면이다. 추천이나 중복 후보는 판단을 돕는 단서이지 확정된 사실이 아니다.

이 장에서는 하나의 작은 지식 베이스로 다음 흐름을 재현한다.

명시적 내부 링크에 pointer를 올려 대상 문맥을 미리 본다.
링크되지 않은 제목·별칭 언급 두 곳을 찾아 원문을 연다.
한 언급은 현재 세션에서 숨기고, 다른 언급은 Markdown link로 변환한다.
현재 문서와 직접 연결되지 않은 추천 세 개를 검토하고 하나를 삽입한다.
중복 후보를 비교하고 대표 문서를 정해 병합한다.
병합된 문서가 삭제되지 않고 merged_into 안내 문서로 남는지 확인한다.

ℹ️

화면의 파란 원과 아래 안내 문구는 클릭·hover 위치를 설명하기 위한 캡처 표시다. 원문 Markdown이나 Glif 프로젝트에는 저장되지 않는다.

실습 문서

예제는 서로 다른 신호와 동작을 분리해 확인할 수 있도록 여덟 파일로 구성했다.

문서	실습에서 맡는 역할
`knowledge-hub.md`	현재 문서이자 병합 후 대표 문서
`release-knowledge-hub-draft.md`	제목·별칭·내용이 겹치는 중복 후보
`release-checklist.md`	링크 추천 후보
`incident-playbook.md`	링크 추천 후보
`quality-gate.md`	링크 추천 후보
`meeting-note.md`	미연결 제목 언급 원문
`retrospective.md`	미연결 별칭 언급 원문
`metadata-contract.md`	명시적 link와 hover preview 대상

원본 fixture를 보존하려면 위 파일을 별도 폴더로 복사해 그 폴더를 Scope로 연다. 이 장의 변환과 병합 단계는 복사본을 실제로 수정한다.

1. 상태 점검과 유지보수를 구분한다

링크 상태와 로컬 그래프 읽기가 backlink·forward link·broken link의 현재 상태와 위치를 보여 준다면, 이 장의 검토 도구는 아직 명시되지 않은 관계와 중복 가능성에 행동을 연결한다.

작업면	답하는 질문	원문 변경 여부
링크 상태	지금 들어오고 나가는 link는 몇 개인가?	없음
문맥 미리보기	이 명시적 link의 대상은 어떤 문서인가?	없음
미연결 언급	제목·별칭을 썼지만 link하지 않은 위치는 어디인가?	변환을 선택할 때만 변경
링크 추천	현재 문서에서 함께 볼 만한 직접 미연결 문서는 무엇인가?	삽입을 선택할 때만 변경
중복 검토	같은 지식을 가리킬 가능성이 있는 문서는 무엇인가?	병합을 확정할 때만 변경

어떤 후보도 자동 확정되지 않는다. 후보가 정확하지 않거나 지금 연결할 이유가 없다면 원문을 그대로 둔다.

2. Link Map을 준비한다

복사한 knowledge-maintenance 폴더를 Scope로 연다.
launcher에서 knowledge-hub.md를 연다.
Ctrl+P를 누르고 링크 맵을 검색해 연다.
오른쪽 요약의 상태가 인덱스 완료가 될 때까지 기다린다.
현재 문서가 knowledge-hub인지 다시 확인한다.

파일을 추가하거나 이름·frontmatter·본문을 바꾼 직후에는 후보가 갱신되는 동안 이전 결과가 잠시 보일 수 있다. 검토와 기록은 인덱스 완료 뒤에 한다.

3. 명시적 링크의 문맥을 미리 본다

knowledge-hub.md에는 다음 명시적 내부 링크가 있다.

[메타데이터 계약](metadata-contract.md)

editor에서 이 link에 pointer를 올리면 작은 문맥 카드가 열린다.

미리보기에서 확인할 정보는 다음과 같다.

대상 문서의 제목과 실제 경로
내용을 식별할 수 있는 짧은 요약
현재 자리에서 열기, 옆에서 열기, 경로 복사 같은 후속 동작
대상 문서에서 사용할 수 있는 projection 보기

미리보기만 열어서는 현재 문서도 대상 문서도 바뀌지 않는다. 이름이 비슷한 문서가 여럿이면 제목만 보지 말고 경로와 요약을 함께 읽는다. 외부 URL이나 아직 해결되지 않은 target은 로컬 문서 미리보기와 같은 정보가 나오지 않을 수 있다.

4. 미연결 언급 후보를 검토한다

미연결 언급 section은 현재 문서의 제목 또는 별칭이 다른 Markdown 문서에 일반 텍스트로 쓰였지만 아직 link가 아닌 위치를 모은다. 이번 fixture에서는 두 후보가 나타난다.

후보 카드에서 다음을 확인한다.

언급이 들어 있는 원문 문서
제목으로 일치했는지 별칭으로 일치했는지
heading과 line·column
앞뒤 문장을 포함한 snippet

같은 단어가 보인다는 이유만으로 연결하지 않는다. 제품명과 일반 명사가 겹치거나, 인용문·예제·과거 기록처럼 link가 불필요한 문맥일 수 있다. 먼저 snippet을 읽고 모호하면 원문을 연다.

5. 언급마다 다른 action을 선택한다

후보의 더보기 메뉴에는 원문 열기, 세션에서 숨기기, 링크로 변환이 있다.

원문을 열어 문맥을 확인한다

원문 열기를 선택하면 해당 문서를 열고 언급 위치로 이동한다. 후보 카드의 짧은 snippet만으로 의도를 판단하기 어려울 때 먼저 사용한다.

원문을 연 뒤 현재 Link Map의 기준 문서도 달라질 수 있다. 검토를 계속하려면 knowledge-hub.md를 다시 현재 문서로 연다.

이번 세션에서만 숨긴다

연결할 필요가 없는 후보는 세션에서 숨기기로 목록에서 치운다.

숨김은 Markdown을 수정하거나 영구 제외 규칙을 만들지 않는다. 같은 현재 문서와 앱 세션에서는 panel을 새로 열어도 유지되지만, 현재 문서를 바꾸거나 새 세션을 시작하면 다시 나타날 수 있다. 반복해서 불필요한 후보가 생기면 원문의 표현이나 문서 title·alias가 지나치게 넓지 않은지 검토한다.

정확한 한 곳을 링크로 변환한다

연결 의도가 분명한 후보에서 링크로 변환을 선택하면 검토한 occurrence 하나만 Markdown link로 바뀐다.

- 릴리즈 허브의 운영 기준을 다음 회의에서 확정한다.
+ [릴리즈 허브](knowledge-hub.md)의 운영 기준을 다음 회의에서 확정한다.

변환 전에 원문이 외부 편집으로 바뀌어 후보의 위치와 내용이 더는 일치하지 않으면 Glif는 추측해서 다른 텍스트를 바꾸지 않아야 한다. 목록을 갱신하고 새 위치를 다시 검토한다. 변환 뒤에는 저장된 Markdown target과 backlink 증가를 확인한다.

6. 링크 추천을 검토하고 삽입한다

추천 section은 현재 문서와 아직 직접 연결되지 않은 로컬 문서 중 검토 가치가 높은 후보를 최대 세 개 보여 준다. 추천은 현재 Scope의 index를 바탕으로 로컬에서 결정되며 AI, 외부 provider 또는 원격 전송을 요구하지 않는다.

각 카드의 문서 제목·경로·요약과 화면에 표시된 추천 이유를 읽는다. “추천됨”은 관계가 참이라는 뜻이 아니며, 문서의 목적상 직접 link가 필요한지 사용자가 결정한다.

동작	사용 시점	결과
링크 삽입	대상 문서로 이동할 참조가 필요할 때	현재 selection에 Markdown link 삽입
임베드 삽입	대상 내용을 현재 문맥에 투영할 때	현재 selection에 embed 문법 삽입
옆에서 열기	두 문서를 비교한 뒤 결정할 때	원문을 바꾸지 않고 나란히 열기

7. 중복 후보를 비교한다

중복 검토 section에는 현재 문서와 같은 지식을 가리킬 가능성이 있는 문서가 나타난다. 이번 fixture에서는 knowledge-hub.md와 release-knowledge-hub-draft.md가 한 후보 쌍이다.

중복 여부는 badge 하나로 결정하지 않는다. 두 문서를 열어 다음을 비교한다.

제목과 alias가 같은 개념을 가리키는가?
본문이 보완 관계인가, 서로 다른 책임을 가진 문서인가?
어떤 경로가 기존 link와 외부 공유에서 더 안정적인가?
한쪽의 고유 heading, tag, alias를 대표 문서에 보존해야 하는가?
병합하지 않고 서로 link하는 편이 독자에게 더 명확한가?

내용이 비슷해도 대상 독자, 시점, 책임이 다르면 별도 문서로 유지한다. 중복 후보는 자동 삭제 목록이 아니다.

8. 대표 문서를 정하고 병합한다

병합을 선택하면 확인 창에서 대표 문서와 병합되는 문서를 다시 확인한다.

이번 실습에서는 knowledge-hub.md를 대표 문서로 둔다. 병합 결과는 다음 원칙을 따른다.

대표 문서의 정체성과 경로를 유지한다.
병합되는 문서의 유용한 alias·tag와 본문을 대표 문서에 보존한다.
병합되는 경로를 삭제하지 않고 merged_into가 있는 안내 문서로 남긴다.
기존에 옛 경로를 가리키던 참조가 새 대표 문서를 찾을 단서를 유지한다.

병합된 release-knowledge-hub-draft.md는 다음과 같은 stub이 된다.

---
merged_into: knowledge-hub.md
---

> Merged into [운영 지식 허브](knowledge-hub.md).

이 보존 방식은 병합을 “한 파일 삭제”로 끝내지 않는다. 기존 경로를 열어도 이동 대상을 알 수 있고, history와 참조를 점검한 뒤 별도 정리 시점을 결정할 수 있다. 병합 직후 대표 문서에서 제목·alias·tag·본문이 의도대로 합쳐졌는지 반드시 확인한다.

권장 유지보수 순서

여러 종류의 경고가 함께 보이면 다음 순서가 안전하다.

인덱스 완료 확인 — 갱신 중인 후보로 판단하지 않는다.
깨진 링크 수정 — 이미 명시된 관계의 오류를 먼저 해결한다.
명시적 링크 preview 확인 — 연결된 target의 정체성을 검증한다.
미연결 언급 검토 — occurrence별로 열기·숨기기·변환을 선택한다.
추천 검토 — 현재 문서에 필요한 직접 관계만 삽입한다.
중복 비교와 병합 — 영향이 가장 큰 작업을 마지막에 수행한다.
Link Health 재확인 — backlink·forward·broken count와 원문을 다시 읽는다.

전체 조작 영상

미연결 언급과 링크 문맥 미리보기

다음 7.9초 영상은 명시적 link의 hover preview를 확인하고, 미연결 언급 두 곳에서 원문 열기·세션 숨기기·링크 변환을 각각 수행한다.

링크 추천 검토

다음 4.4초 영상은 추천 세 개를 확인하고 카드 동작을 펼친 뒤, 현재 문서에 link를 삽입해 결과를 확인한다.

중복 검토와 병합

다음 4.9초 영상은 중복 후보를 열고 대표 문서를 선택해 병합한 뒤, 옛 경로에 merged_into stub이 남는지 확인한다.

예상과 다를 때

증상	먼저 확인할 것	조치
후보 section이 비어 있다	현재 문서와 인덱스 상태	`knowledge-hub.md`를 다시 열고 `인덱스 완료`를 기다린다
미연결 언급 수가 다르다	제목·alias와 이미 link된 occurrence	fixture 원본을 새 폴더에 복사하고 기존 변환 결과가 섞이지 않았는지 확인한다
원문 열기 뒤 후보가 바뀌었다	Link Map의 현재 문서	`knowledge-hub.md`를 다시 열어 기준 문서를 복원한다
숨긴 후보가 다시 나타났다	앱 세션 또는 현재 문서 변경	세션 숨김의 경계를 확인하고 필요하면 다시 숨긴다
변환이 적용되지 않는다	후보 생성 뒤 원문 변경 여부	저장하고 index를 갱신한 뒤 새 후보에서 다시 시도한다
추천 link가 엉뚱한 위치에 들어갔다	editor selection	undo한 뒤 원하는 문단에 cursor를 놓고 다시 삽입한다
예상 문서가 추천되지 않는다	직접 link 여부와 최대 세 후보	이미 연결됐는지 확인하고 다른 후보를 정리한 뒤 index를 갱신한다
중복 후보가 없다	두 문서의 title·alias·본문과 Scope	fixture 두 파일이 같은 Scope에 있고 원본 내용인지 확인한다
병합 뒤 옛 문서가 사라진 것처럼 보인다	원래 경로와 Scope tree	원래 경로를 직접 열어 `merged_into` stub과 대표 link를 확인한다

완료 확인

knowledge-hub.md가 현재 문서이고 인덱스 완료 상태에서 시작했다.
명시적 link hover preview에서 제목·경로·요약을 확인했다.
미연결 언급 두 곳의 원문 위치와 snippet을 확인했다.
원문 열기, 세션 숨기기, 링크 변환의 차이를 설명할 수 있다.
변환된 occurrence 하나가 올바른 Markdown target을 가리키는지 확인했다.
추천 후보가 최대 세 개이며 자동 확정이 아님을 확인했다.
현재 selection에 link를 삽입하고 forward relation을 확인했다.
중복 후보의 두 원문을 비교한 뒤 대표 문서를 직접 선택했다.
병합된 경로에 merged_into stub과 대표 문서 link가 남았는지 확인했다.
마지막으로 Link Health의 backlink·forward·broken 상태를 다시 점검했다.