학습 노트의 구조 — 개념 / 절차 / 함정을 분리해서 쓰는 이유

새로운 기술을 학습하면서 노트를 만들 때, "그냥 시간 순서대로 쓴 일기"가 되어버리는 일이 자주 있습니다. 한 달 뒤 그 노트를 다시 보면 어디가 정의이고 어디가 단계이고 어디가 함정인지 구분이 안 가서, 결국 처음부터 다시 검색하게 됩니다. 학습 노트를 개념 / 절차 / 함정 세 영역으로 분리해 두면 이런 재탐색을 줄일 수 있습니다.

1. 세 영역의 차이

영역	무엇을 적나	다시 볼 때
개념 (Concept)	"이게 뭐다", 정의, 동작 원리	다른 도구와 비교할 때
절차 (Procedure)	"이렇게 한다", 단계, 명령어, 코드 템플릿	같은 작업을 반복할 때
함정 (Pitfall)	"이런 실수를 했다", 원인, 해결	같은 에러를 만났을 때

같은 주제 안에서도 세 영역이 섞여 있으면 다시 볼 때 가치가 줄어듭니다. 분리해서 적으면 검색이 빨라집니다.

2. 예시 — Vite 마이그레이션

개념

Vite는 dev에서 esbuild로 의존성을 사전 번들링하고, 브라우저에 ESM을 직접 보낸다. build는 Rollup으로 청크 분할 + tree-shaking.

절차

1pnpm create vite@latest my-app -- --template react-ts
2pnpm install
3pnpm dev

vite.config.ts에서 alias, env prefix, plugin 추가.

함정

• process.env는 동작하지 않는다. import.meta.env 사용.
• __dirname도 없음. path.dirname(fileURLToPath(import.meta.url)) 패턴.
• CommonJS-only 패키지는 optimizeDeps.include에 명시 필요한 경우 있음.

세 영역으로 나뉘어 있으면, 다음에 같은 함정에 막혔을 때 "함정" 섹션만 보면 됩니다.

3. 코드 노트의 구성

코드 예제도 세 종류가 있습니다.

• 개념 예제 — 동작을 보여주는 최소 코드. "이게 뭔가" 답.
• 템플릿 예제 — 복붙할 수 있는 형태. "이렇게 한다".
• 반례 — 잘못된 사용. "이러지 마세요".

각 예제 위에 어떤 종류인지 짧게 적어 두면, 나중에 어디서 가져올지 헷갈리지 않습니다.

4. 영역 사이의 링크

세 영역이 분리됐다고 단절되는 건 아닙니다. 함정 섹션에서 해당 개념으로 다시 가는 짧은 링크를 두면 좋습니다.

1## 함정
2
3### `import.meta.env`가 undefined
4원인: `.env` 파일에서 prefix가 `VITE_`가 아닐 때.
5참고: [개념 — Vite 환경변수](#vite-env)

5. 시간 순서 노트와 병행

일기 형식의 학습 일지("오늘 했던 것")를 따로 두는 것도 좋습니다. 다만 "재참조용 노트"와 "기록용 일기"는 다른 곳에 둡니다. 일기는 시간이 지나면 가치가 줄지만 노트는 늘어납니다.

6. 도구

특정 도구가 필요한 건 아닙니다. Markdown 파일에 H2로 세 섹션만 만들어도 충분합니다. Obsidian/Notion처럼 링크가 강한 도구를 쓰면 함정 → 개념 link가 자연스러워집니다.

1# Vite
2
3## 개념
4...
5
6## 절차
7...
8
9## 함정
10...

7. 정리

다시 볼 때 무엇을 찾는지가 다릅니다.

• 개념을 찾을 때는 "이게 뭐였더라"
• 절차를 찾을 때는 "어떻게 시작하더라"
• 함정을 찾을 때는 "이 에러 본 적 있는데"

세 검색이 각각 다른 위치에 있으면 분리해 두는 게 가장 효율적입니다. 이 글의 구조 자체도 세 영역(개념 / 절차 / 함정 + 정리)을 따랐습니다.

참고: Andy Matuschak — Evergreen notes / Tiago Forte — Building a Second Brain.