DDungjae.github.io — agent notes

개인 사이트. Jekyll + Minimal Mistakes (remote theme), GitHub Pages 가 main 브랜치를 그대로 빌드합니다 (Actions 없음, gh-pages 없음). 사람이 읽는 개요는 README.md.

작업 시작 전에

항상 git pull --rebase origin main 먼저. 사용자가 GitHub 웹에서 직접 파일을 고치기도 합니다.
노션 글을 올리거나 고치는 작업이면 notion-import 스킬을 먼저 부릅니다 (아래 “노션 글” 참고). 이 스킬(.claude/skills/notion-import/SKILL.md)이 노션 DB 구조, 변환 스크립트 사용법, 새 과목 추가 방법 등 세부 절차를 담고 있습니다. 이 문서는 스킬을 대신하지 않고, 스킬 밖에서도 반드시 지켜야 할 것과 과거에 실제로 터졌던 사고만 요약합니다.

수식 — 절대 헷갈리지 말 것

이 사이트는 kramdown (input: GFM, math_engine: mathjax) + MathJax 3 조합입니다. 이 조합에 비직관적인 함정이 두 개 있고, 둘 다 실제로 글을 깨뜨린 적이 있습니다 (2026-09-29).

인라인 수식도 항상 $$...$$ 를 씁니다. 절대 홑 $...$ 로 바꾸지 마세요. $$...$$ 가 문장 중간에 있어도 kramdown 이 알아서 인라인()으로 바꿔주고, 그 안의 \{ \} 같은 백슬래시 이스케이프도 그대로 보존합니다. 반면 홑 $...$ 는 kramdown 이 수식으로 인식하지 않고 일반 텍스트로 취급하면서 markdown 이스케이프 규칙을 적용해 \{, \} 의 백슬래시를 조용히 지워버립니다 (예: $\mathbf{Z}=\{(x,y)\}$ → 렌더링에서 중괄호 이스케이프가 깨짐). “MathJax 설정에 인라인 $...$ 를 지원하니 그쪽이 더 표준적이지 않나” 라고 생각해서 $$ 를 $로 “고치지” 마세요 — 실제로 한 세션이 이 생각으로 고쳤다가 위 버그를 만들었습니다.
수식 안에 맨 파이프 문자 | 를 쓰면 안 됩니다 (조건부확률 P(y|x) 처럼). kramdown 의 GFM 파서가 문단이나 리스트 항목 안의 | 를 표(table) 구분자로 착각해서, $$...$$ 로 감싸져 있어도 그 문장 전체를 깨진 HTML <table> 로 바꿔버립니다. 단, $$...$$ 가 그 문단/리스트 항목의 유일한 내용으로 독립된 한 줄일 때는 안전합니다 (kramdown 이 그 한 줄 전체를 수식 블록으로 보호함). 위험한 건 “다른 글자와 같은 줄에 섞인” $$ 뿐입니다.
- 고치는 법: | 를 그냥 지우고 \vert{} 로 씁니다 (\| 는 쓰지 마세요 — MathJax 에서 \Vert(겹선 ‖)로 렌더링되어 조건부확률의 홑선과 달라집니다). {} 는 바로 뒤 글자와 명령 이름이 붙어버리는 것(\vertx처럼 파싱되는 것)을 막기 위한 빈 그룹입니다.
- tools/notion_to_jekyll.py 의 fix_math_inline/escape_pipes 가 노션에서 받은 인라인 수식은 이걸 자동으로 처리합니다. 하지만 이미 올라간 글을 손으로 고칠 때는 직접 \vert{} 로 바꿔줘야 합니다 — 스크립트를 다시 돌리지 않는 한 자동으로 안 고쳐집니다.
- 절대 표시값 \lvert x \rvert (절댓값)는 이 문제와 무관합니다 (| 문자가 아니라 \lvert/\rvert 명령이라서 안전). \lvert...\rvert, \lVert...\lVert 처럼 여는 것과 닫는 것을 짝 틀리게 쓰지 않았는지도 확인하세요 (\lvert...\lvert 는 오타).
여러 줄로 된 수식 유도는 \begin{aligned}...\end{aligned} 로 감쌉니다. $$...$$ 안에서 그냥 \\ 로 줄바꿈만 하면 MathJax 가 제대로 못 그립니다.
글을 올리거나 고친 뒤에는 반드시 빌드된 HTML 에서 <table 이 뜬금없이 생기지 않았는지 확인합니다 (아래 “빌드 확인” 참고). $ 개수를 세는 것만으로는 이 버그를 못 잡습니다 — 브라우저에 실제로 그려지는 게 아니라 정적 HTML 에서 이미 깨져 있는 문제라서, 꼭 빌드 결과물을 봐야 잡힙니다.

빌드 확인 (수정 후, 푸시 전 필수)

export PATH="/c/Ruby40-x64/bin:$PATH" SSL_CERT_FILE="/c/Program Files/Git/mingw64/etc/ssl/certs/ca-bundle.crt"
bundle exec jekyll build 2>&1 | tail -20   # "done in" 만 나오고 error 없어야 함

# 이번에 고친 글/노트만 체크 (경로는 permalink 규칙에 따라 날짜 없이 나올 수 있음, _site 에서 찾기)
F="_site/posts/<slug>/index.html"   # 또는 _site/lectures/<course>/<slug>/index.html
grep -q "<table" "$F" && echo "⚠️ 표로 깨짐 — 그 줄에 이스케이프 안 된 | 가 있는지 확인"
grep -c '\\(' "$F"   # 인라인 수식 개수(대략) — 0 이면 뭔가 안 바뀜
grep -c '\\\[' "$F"  # 블록 수식 개수

로컬 빌드용 스크래치 폴더가 따로 있다면(%TEMP%\newsite 등) 거기서 확인해도 되지만, 그 폴더는 가끔 _config.yml/Gemfile/gem 설치가 빠져서 깨지므로 레포 전체를 다시 복사해 넣고 시작하세요.

노션 글 가져오기·수정하기

절차는 .claude/skills/notion-import/SKILL.md 를 그대로 따릅니다. 특히:

이미 변환되어 _posts/(또는 _lectures/, _projects/)에 있는 파일을 다시 스크립트 입력으로 넣지 마세요. 그 파일 자체가 이미 front matter + 본문 형태라서, 스크립트가 그 front matter 를 다시 “노션 제목/속성 줄”로 오인해 제목이 파일명 그대로 들어가고 본문이 --- 로 시작하는 완전히 깨진 글이 만들어집니다 (2026-09-29 에 LoRA/PiSSA 글 두 개가 이렇게 중복·손상되었던 사고). 항상 원본 노션 fetch 결과로 새로 임시 파일을 만들어서 스크립트에 넣으세요. 기존 글을 고칠 뿐이면 그냥 _posts/...md 를 직접 Edit 하는 게 더 안전합니다.
글을 올리기 전(재올리기 포함) 반드시 오타, 수식 가독성(위 항목들), 논문/강의 내용과 실제로 맞는지(수식 괄호 균형, 부등식 방향, 용어)를 검토합니다. 이건 사용자가 매번 명시적으로 요청하지 않아도 기본으로 하는 절차입니다 — “그냥 올려줘” 라고만 해도 이 검토를 생략하지 않습니다.
요약(excerpt) 문장을 지어내지 않습니다. 논문 리뷰는 노션 Authors/Venue/Year 속성에서 자동 생성되는 서지 한 줄(Jason Wei et al., NeurIPS 2022)만 씁니다. 강의 노트는 노션 Excerpt 속성이 있을 때만 옮기고, 없으면 비워둡니다.
검토·수정 중 발견한 오타/오류는 사이트와 노션 원본 양쪽 다 고칩니다 (노션 쪽만 고치고 끝내지 않기). 노션 쪽 텍스트 교체는 mcp__notion__notion-update-page (update_content, content_updates 배열)를 씁니다. 위 수식 관련 이스케이프(\vert{} 등)는 사이트 렌더링 전용 처리이므로 노션 원본에는 넣지 않습니다 (노션 원본은 그냥 읽기 좋은 | 그대로 둡니다).
커밋·푸시는 사용자가 명시적으로 올려달라고 했을 때만 합니다.

그 외

색인: README.md (사람용 빠른 참조), .claude/skills/notion-import/SKILL.md (노션 변환 절차), tools/notion_to_jekyll.py (변환 스크립트, --help 로 옵션 확인).