---
title: "참조 자동 갱신이 문서를 망가뜨린다, 링크를 데이터로 쓸 때"
description: "파일 이름을 바꾸면 참조를 자동으로 고쳐 주는 도구가 이름 때문에 생긴 문제를 기록한 문서까지 새 이름으로 바꿔 진단 근거를 지웁니다. 링크가 참조와 데이터 두 역할을 겸할 때 구분하는 방법입니다."
date: 2026-11-12
updated: 2026-11-12T04:46:43.049Z
tags: [tooling, refactoring, documentation]
canonical: https://blog.wooncloud.com/posts/auto-rename-breaks-documented-references
---

파일 이름을 바꾸면 그 파일을 가리키는 참조를 전부 자동으로 고쳐 주는 도구가 많습니다. IDE 의 rename symbol, 위키형 노트 앱의 링크 자동 갱신, 코드모드 스크립트가 다 같은 일을 합니다. 보통은 고마운 기능입니다.

그런데 "이 이름 때문에 참조가 이렇게 걸려 있다"는 사실을 기록해 둔 문서가 같은 저장소에 있으면 이야기가 달라집니다.

## 기록한 문장이 새 이름으로 바뀝니다

점검 리포트에 이런 줄이 있다고 해 봅시다.

```markdown
`Setup Guide.md` 는 파일명 규칙(소문자, 하이픈) 위반입니다. 이 이름으로 걸린 [[Setup Guide]] 참조가 6곳 있습니다.
```

규칙에 맞게 `setup-guide.md` 로 rename 하면, 도구는 저장소를 훑어 이 리포트 안의 `[[Setup Guide]]` 까지 새 이름으로 바꿉니다.

```markdown
`Setup Guide.md` 는 파일명 규칙(소문자, 하이픈) 위반입니다. 이 이름으로 걸린 [[setup-guide]] 참조가 6곳 있습니다.
```

![파일을 rename 하면 일반 표기 [[Setup Guide]] 는 자동 갱신 대상이 되어 기록 속 근거까지 바뀌지만, 코드로 감싼 `[[Setup Guide]]` 는 스캔에서 제외돼 기록이 그대로 남는다](/images/posts/auto-rename-breaks-documented-references/741ae4a1-76ed-4234-8113-8999d0a3b281.svg)

문장은 문법적으로 멀쩡한데 의미가 어긋났습니다. 리포트는 옛 이름으로 걸린 참조를 기록한 건데, 이제는 규칙을 지킨 새 이름이 위반이라고 말하는 문장이 됐습니다. 왜 그 파일을 고쳐야 했는지 근거가 같이 사라집니다.

![코드로 감싸지 않은 링크는 자동 갱신 때 함께 바뀌어 기록이 가리키던 근거가 사라진다.](/images/posts/auto-rename-breaks-documented-references/400e159c-4e11-4f1e-9470-f745be072232.webp)

에러도 경고도 나지 않습니다. 도구 입장에서는 완벽하게 성공한 작업이니까요.

## 링크가 두 역할을 겸합니다

도구의 버그가 아닙니다. 한 문법이 두 가지 역할을 겸하는 게 원인입니다.

하나는 참조로서의 링크입니다. "저기로 가라"는 뜻이라 대상이 움직이면 따라가야 합니다. 다른 하나는 데이터로서의 링크입니다. "이런 문자열이 있었다"는 기록이라 절대 바뀌면 안 됩니다. 둘이 같은 표기를 쓰는 한 도구는 구분할 방법이 없습니다.

그래서 쓰는 쪽에서 구분을 만들어 줘야 합니다. 가장 싼 방법은 데이터일 때 인라인 코드로 감싸는 겁니다.

```markdown
깨짐: [[Setup Guide]] 를 가리키는 참조가 6곳 있다
안전: `[[Setup Guide]]` 를 가리키는 참조가 6곳 있다
```

대부분의 도구는 코드 스팬과 코드 블록 안을 스캔 대상에서 제외합니다. 표기 하나 바꿨을 뿐인데 자동 갱신의 사정권 밖으로 나갑니다.

## 코드에서도 똑같습니다

마이그레이션 기록, 감사 로그 스키마, 폐기된 API 이름 목록처럼 과거의 이름을 보존하는 것이 목적인 데이터는 전부 이 함정에 걸립니다.

```ts
// 위험: 문자열 안까지 바꾸는 옵션으로 rename 하면 같이 끌려간다
const DEPRECATED_FIELDS = ['userName', 'userEmail']
```

리팩터링 도구가 "친절하게" 최신 이름으로 바꿔 주는 순간 이 목록은 존재 이유를 잃습니다. 의도를 주석과 별도 파일로 못박아 두는 편이 안전합니다.

```ts
// legacy-field-names.ts (리팩터링 제외 대상)
// v1 스키마의 필드명. 현재 코드에는 없다. 이 값은 rename 대상이 아니다.
export const LEGACY_FIELD_NAMES: readonly string[] = ['userName', 'userEmail']
```

자동 갱신이 있는 저장소에서 문서를 쓸 때 기준은 하나입니다. **이 참조가 가리키는 것인가, 기록하는 것인가. 기록이라면 코드로 감쌉니다.**

스타일 가이드, 점검 리포트, 폐기 목록처럼 도구와 규칙을 메타로 서술하는 문서는 문서 전체가 데이터에 가깝습니다. 이런 문서에서는 살아 있는 참조를 기본값으로 두지 않는 편이 안전합니다.

## 참고

- [Markdown Guide, Code](https://www.markdownguide.org/basic-syntax/#code)
- [VS Code Refactoring](https://code.visualstudio.com/docs/editor/refactoring)
