개념 — 지식체계의 터를 잡을 때 나오는 말들

세부계획의 첫 단계는 knowledge/ 폴더 뼈대를 만드는 일이에요. 그런데 폴더를 만드는 명령 자체는 3초면 끝나요. 하루가 걸리는 쪽은 **“이 폴더를 왜 이렇게 나누는가”**를 정하는 일이고, 그 판단에 낯선 말 여섯 개가 끼어 있어요. 손만 움직이고 넘어가면 2주차에 논문을 열 편 넣을 때 “이걸 왜 이렇게 했지”가 되니까, 먼저 익혀요.

여섯 개를 세 묶음으로 나눠서 볼게요. 묶음마다 답하는 질문이 달라요.

① 스키마 — 칸을 미리 정해두는 것

스키마는 “이 자료엔 어떤 칸이 들어간다”를 미리 정해둔 틀이에요. 서류 양식과 똑같아요. 병원 접수표에 이름·생년월일·증상 칸이 정해져 있는 것처럼요.

왜 미리 정해야 하냐면, 안 정하면 논문 열 편이 열 가지 모양이 되기 때문이에요. 첫 편은 결과를 자세히 쓰고 둘째 편은 방법만 쓰고 셋째 편은 인용을 빠뜨리면, 나중에 “방법이 비슷한 논문 찾아줘”라고 물어도 답이 안 나와요. 어떤 노트엔 방법 칸이 아예 없으니까요.

우리 논문 노트의 칸은 PRD에서 이미 일곱 개로 정했어요.

서지정보 · 연구문제 · 방법 · 데이터 · 결과 · 한계 · 원문 인용

이 중 한계가 특별해요. 논문 요약 도구 대부분이 결과만 뽑고 한계는 버려요. 그런데 “이 방법을 내가 진짜 쓸 수 있나”를 판단할 때 결정적인 건 한계예요. 칸을 정해두면 빠뜨리고 싶어도 빈칸이 눈에 보여서 빠뜨릴 수가 없어요. 규칙을 의지에 맡기지 않고 양식에 박아두는 거예요.

이미 익숙한 것과 이어보면 — 우리 사이트 글 맨 위의 frontmatter(title, date, 종류, 주차)도 스키마예요. config.ts가 “위키 글엔 이 칸이 들어간다”를 정해뒀고, 칸을 어기면 빌드가 실패해요. 이미 쓰고 있던 거예요.

② 원본을 지키는 두 폴더

불변 — 한번 넣으면 고치지 않는다

불변은 한번 넣으면 고치지 않는다는 뜻이에요. knowledge/raw/에 들어간 논문 원본은 불변으로 둬요.

왜 그러냐면, 고칠 수 있게 두면 나중에 “이게 원본이었나 내가 고친 건가”를 매번 의심해야 하기 때문이에요. 논문 인용문이 원문과 정말 같은지 확인할 방법이 사라지면, “원문에 없는 인용은 0건”이라는 우리 기준(S3)을 지킬 수가 없어요. 믿을 수 있는 바닥이 하나 있어야 그 위에 쌓은 것도 믿을 수 있어요.

소스 레이어와 지식 레이어 — 위치로 실수를 막는다

raw/와 wiki/를 굳이 두 폴더로 나누는 이유예요. 이건 1일차에 배운 AKM의 두 레이어와 같아요.

같은 폴더에 섞어두면 규칙을 기억에 의존해야 해요. 사람은 반드시 까먹어요. 폴더를 나눠두면 위치가 실수를 막아줘요 — “이건 raw 폴더 안이니까 손대면 안 되는 거구나”가 눈으로 보이니까요. 규칙을 머리에 두지 말고 구조에 박아두는 것, 이게 AKM이 레이어를 나누는 이유예요.

③ Git에 무엇을 담고 무엇을 뺄지

.gitignore — “이건 기록하지 마” 목록

.gitignore는 Git이 무시할 파일 목록을 적어두는 파일이에요. 여기 적힌 파일은 커밋에 안 들어가요.

논문 원본 PDF를 여기 넣으려고 해요. 이유가 둘이에요. 하나는 저작권 — 논문 PDF는 대개 출판사에 권리가 있어서, 저장소에 담아두면 나중에 공개 전환을 검토할 때 위험이 커져요. 하나는 용량 — PDF 열 편이면 금방 무거워지고, Git은 한번 담은 파일을 히스토리에서 지우기가 아주 번거로워요.

원본을 잃는 게 아니라는 점이 중요해요. 보존은 내 컴퓨터 폴더에서 하고, Git에는 옮긴 마크다운만 올려요. 어느 논문이었는지는 노트에 적힌 서지정보와 DOI로 언제든 되짚을 수 있어요.

우리 사이트에도 이미 .gitignore가 있어요. node_modules/(부품 폴더), dist/(빌드 결과), .env(비밀 열쇠)가 들어 있죠. 전부 “다시 만들 수 있거나 남에게 보이면 안 되는 것”이에요. 논문 PDF도 같은 부류예요.

와일드카드 — “아무 글자나”를 뜻하는 기호

.gitignore에 논문 PDF를 적을 때 파일 이름을 하나하나 적지 않아요. knowledge/raw/*.pdf라고 한 줄 쓰면 끝이에요.

여기서 *가 와일드카드예요. “아무 글자나”라는 뜻이라, *.pdf는 이름이 무엇이든 pdf 파일 전부를 가리켜요. 앞으로 넣을 논문까지 미리 덮어주니까 논문을 추가할 때마다 .gitignore를 고칠 필요가 없어요.

조심할 것 하나 — 패턴을 적어도 틀리면 조용히 안 먹어요. 에러가 안 나니까 모르고 지나가다 나중에 PDF가 커밋에 섞여 들어가요. 그래서 적은 뒤에 정말 무시되는지 Git한테 직접 물어봐야 해요. 그 확인용 명령이 따로 있어요.

.gitkeep — 빈 폴더를 붙잡아 두는 빈 파일

Git은 파일을 기록하고 폴더는 기록하지 않아요. 그래서 빈 폴더는 커밋해도 사라져요. 다음에 이 저장소를 다른 컴퓨터에 받으면 폴더가 없는 거예요.

그래서 관례적으로 .gitkeep이라는 빈 파일을 하나 넣어둬요. 파일이 하나 들어 있으면 폴더가 기록되니까요. 특별한 기능이 있는 이름이 아니고 “이 폴더를 유지하려고 넣은 파일”이라는 뜻으로 개발자들이 약속처럼 쓰는 이름이에요.

우리는 knowledge/wiki/papers/와 knowledge/wiki/concepts/가 처음엔 비어 있으니 여기에 넣어요. 논문이 들어오기 시작하면 굳이 지우지 않아도 돼요.

곁들여 — peerDependencies

터 잡기에 직접 쓰이진 않지만, 오늘 세부계획을 짜면서 이것 덕분에 하루를 아꼈으니 같이 익혀둬요.

peerDependencies는 “이 부품이 어떤 버전과 어울리는지” 제작자가 선언해둔 칸이에요. 검색창 부품(astro-pagefind)의 이 칸에 ^4가 적혀 있어서, 우리 사이트의 Astro 4를 올리지 않고 그대로 써도 된다는 걸 확인했어요.

초보가 제일 많이 하는 헛수고가 “새 기능 붙이려고 프레임워크부터 올리다 사이트를 깨는 것”이에요. 이 칸 한 줄을 보면 그걸 건너뛸 수 있어요. 부품을 붙일 때마다 “이거 내 버전에서 되나?”를 여기서 확인하는 습관을 들이면 좋아요.

개념 요약

한 줄로 꿰면

여섯 개가 따로 있는 게 아니에요. 스키마로 칸을 정하고 → 불변 원본과 지식을 두 층으로 나눠 담고 → Git에는 되살릴 수 있는 것만 남긴다. 이 한 줄이 지식체계의 터예요. 나머지 열한 단계는 전부 이 터 위에서 일어나요.

관련 글: AKM 개념 · PRD · 세부계획