자동화가 성공하니 위키가 안 읽혔다 — 학습위키 구조를 다시 짠 하루

한 줄 요약: 어제 봇이 위키에 글을 자동으로 쌓기 시작했는데, 하루 지나 들어와 보니 그 결과물이 기타라는 이름 아래 들어가 있었다. 만드는 데만 신경 쓰느라 “만들어진 게 어떻게 보이는지”를 안 본 것이다. 이름·순서·레이아웃·첫 화면·프로젝트 문서까지 하루 종일 정리했다.

이런 분께 도움이 돼요: 자동화는 성공했는데 결과물이 안 읽히는 분, 글이 쌓일수록 사이드바가 지저분해지는 분, 그리고 프로젝트 소개 문서가 몇 주 전 계획서에 멈춰 있는 분.

Before — 자동화가 성공해서 드러난 문제

어제(위키 자동 저장 만들기) 봇이 GitHub에 직접 커밋해서 AI 용어 사전·배터리 용어 사전·반도체 용어 사전 세 페이지를 만들기 시작했다. 성공이었다. 그런데 오늘 사이트에 들어와 보니 이렇게 보였다.

학습위키
├ [지도] 4주 로드맵
├ [지도] 4주 세부 실행계획
├ 기타          ← 여기에 용어 사전 3개
├ 1주차
├ 2주차
├ 3주차
└ 4주차

이 프로젝트의 핵심 결과물이 “기타”에 들어가 있었다. 이유는 단순했다 — 사이드바가 글을 주차 번호로 묶는데, 봇이 만든 용어 사전에는 주차가 없으니 0주차 = 기타로 떨어진 것이다. 코드는 정확히 시킨 대로 동작했고, 그 규칙이 만들어진 시점에는 용어 사전이라는 게 존재하지도 않았다.

문제는 이것만이 아니었다.

• 지도와 1~4주차가 평평하게 나열돼서 뭐가 큰 덩어리인지 안 보였다.
• 사이트 전체가 가운데 정렬이라 사이드바가 화면 한복판에 떠 있었다.
• 위키 첫 화면은 “왼쪽 목록에서 글을 고르세요”만 말할 뿐, 여기 뭐가 있는지를 설명하지 않았다.
• 프로젝트 페이지는 8월 초 계획서 그대로였다. 로컬 n8n, RSS 2개, 오후 6시 1회, 위키 저장 [ ] 미완료.

1. “기타”는 이름이 아니다

가장 먼저 고친 것. 기타 → 용어 사전.

사소해 보이지만, 이 이름 하나 때문에 매일 자동으로 자라는 자산이 잡동사니처럼 보이고 있었다. 같은 라벨이 사이드바·위키 첫 화면·전자책 세 군데에 흩어져 있어서 전부 맞췄다.

2. 두 덩어리로 나눴다 — 자동으로 자라는 것 vs 내가 쓰는 것

이름만 바꿔서는 부족했다. 목록을 다시 보다가 성격이 완전히 다른 두 가지가 한 줄로 섞여 있다는 걸 알았다.

그래서 사이드바를 두 덩어리로 갈랐다. 지도(로드맵)와 주차별 글은 전부 “나의 개발일지” 아래로 넣었다.

학습위키
├ ▾ 용어 사전            ← 봇이 채우는 쪽
│    AI / 배터리 / 반도체
└ ▾ 나의 개발일지         ← 내가 쓰는 쪽
     [지도] 4주 로드맵 · 4주 세부 실행계획
     ▾ 1주차  ▾ 2주차  ▾ 3주차  ▾ 4주차

처음엔 개발일지를 위에 뒀다가, 다시 보고 순서를 바꿨다. 매일 바뀌는 쪽(용어 사전)이 위에 있는 게 자주 들어오는 사람 기준으로 맞다고 봤다.

3. 접기/펴기는 자바스크립트 없이

주차가 늘어날수록 사이드바가 계속 길어진다. 접을 수 있어야 했는데, 자바스크립트를 새로 쓰고 싶지는 않았다. HTML에 이미 있는 <details>·<summary>로 해결된다.

<details class="group" open>
  <summary class="group-title">용어 사전</summary>
  ...목록...
</details>

open을 붙이면 기본이 펼침, 제목을 누르면 접힌다. 스크립트 0줄. 기본 삼각형 마커만 지우고 직접 화살표를 그렸다.

summary { cursor: pointer; list-style: none; }
summary::-webkit-details-marker { display: none; }
summary::before { content: '▸'; transition: transform 0.15s; }
details[open] > summary::before { transform: rotate(90deg); }

4. 사이드바를 왼쪽 끝으로 — 대신 본문 폭을 묶어야 한다

사이트 전체가 max-width: 1240px; margin: 0 auto라서, 넓은 화면에서는 사이드바가 화면 한가운데에 떠 있었다. 위키 페이지만 이 제한을 풀었다.

여기서 한 가지 함정이 있었다. 가운데 정렬만 풀면 본문이 화면 폭만큼 늘어난다. 1440px 모니터에서 한 줄이 1100px가 되면 눈이 줄을 놓친다. 그래서 그리드 칸 자체에 폭을 박고, 남는 공간은 오른쪽에 버렸다.

.wiki-grid {
  grid-template-columns: 240px minmax(0, 780px);
  justify-content: start;   /* ← 남는 폭을 오른쪽에 몰아준다 */
}

1440px에서 실제로 재본 결과:

5. 첫 화면에서 “여기 뭐가 있는지” 말해주기

위키 첫 화면이 12개 글이 모였어요 + 3개 글 카드 몇 개가 전부였다. 처음 온 사람에게는 아무 정보가 아니다. 두 덩어리를 각각 소개하는 카드로 바꿨다.

용어 사전 · 3개 매일 오후 6시, 봇이 뉴스에서 뽑아온 키워드를 설명과 실제 사례까지 붙여 여기에 자동으로 저장합니다. 제가 안 써도 계속 자라는 쪽이에요.

“제가 안 써도 계속 자라는 쪽” — 이 한 줄이 이 사이트에서 제일 하고 싶은 자랑인데, 그동안 아무 데도 안 적혀 있었다.

숫자 옆 칩(둥근 버튼)은 전부 링크로 만들었다. 예전 카드는 3개 글이라고 알려주기만 하고 눌리지 않았다.

6. 문서가 8월 초에 멈춰 있었다

제일 부끄러웠던 부분. 프로젝트 페이지가 7월 30일에 쓴 계획서 그대로였다. 그 사이 실제로는 이만큼 달라져 있었다.

여기서 하나 결정한 게 있다. 계획서를 지우고 새로 쓰지 않았다. 대신 원안(PRD)에서 바뀐 것이라는 표를 만들어 원안 / 지금 / 바꾼 이유를 나란히 남겼다. 오라클 클라우드가 카드 결제에서 막혀 GCP로 돌아선 것, 비즈니스포스트 RSS가 User-Agent 없으면 403을 뱉어서 포기한 것 — 이런 게 지워지면 “왜 이렇게 만들었나”에 답할 수 없게 된다. 결과물보다 판단 근거가 포트폴리오에서 더 오래 쓰인다고 생각한다.

같은 이유로 4주 회고는 손대지 않았다. 거기엔 위키 자동 저장이 ❌ 미완료라고 적혀 있지만, 8월 12일 시점에는 그게 사실이었다. 고치면 기록이 아니게 된다.

7. 제작인가 개선인가 — 애매하면 규칙으로 못 박기

정리하다 보니 판정이 애매한 글이 하나 나왔다. 위키 자동 저장을 완성한 8월 24일 글이다. GPters 챌린지는 8월 12일에 끝났으니 이건 “챌린지 이후”인데, 내용은 PRD에 있던 마지막 MVP 항목을 끝낸 것이다.

기준을 이렇게 잡았다.

챌린지 종료일이 아니라 구현 완료일을 기준으로 한다. 처음 만들어서 굴러가게 하기까지 = 제작 / 굴러가는 걸 고치고 더하기 = 개선

챌린지가 끝났어도 결국 구현을 마무리하는 것이 중요하지, 외부 일정에 맞춰 내 기록을 자르는 건 의미가 없다고 봤다. 그래서 8월 24일까지가 제작, 오늘부터가 개선이다.

이 판단은 오늘만 쓰고 버릴 게 아니라서 저장소의 AGENTS.md에 규칙으로 적어뒀다. 다음에 AI와 함께 글을 쓸 때 자동으로 이 기준을 따르게 된다.

이 글 자체가 겪은 문제

재미있는 게 하나 있다. 이 글에는 주차: 5가 붙어 있다. 챌린지는 4주로 끝났는데 5주차다.

주차를 안 붙이면 어떻게 될까? 오늘 아침에 고친 바로 그 문제 — 용어 사전으로 떨어진다. 사이드바가 “주차 없는 글 = 용어 사전”으로 묶기 때문이다. 구조를 고쳤더니 그 구조가 곧바로 다음 글의 형식을 강제한 셈이다.

배운 것

오늘 갱신한 프로젝트 문서는 반도체·배터리·AI 뉴스 키워드 요약봇에서 볼 수 있어요. 봇이 자동으로 채우는 쪽은 AI · 배터리 · 반도체 용어 사전입니다.