아프니까 개발자다 아프니까 개발자다

코드를 읽어 위키 문서를 LLM이 통째로 써 주는 시스템을 굴리다 보면, 어느 날 반드시 이 순간이 온다. 자동 생성된 architecture.md를 읽다가 틀린 한 줄, 혹은 어색한 표현, "여기는 이렇게 서술됐으면" 싶은 문장을 발견한다. 손이 자연스럽게 그 파일로 간다. 고치고 저장한다. 그리고 언젠가 그 코드가 바뀌어 페이지가 다시 쓰이는 순간, 그 수정은 흔적도 없이 사라진다.이게 직관에 반하는 첫 사실이다. 문서를 더 정확하게 만들려고 한 손질이, 시스템 입장에선 그냥 덮어쓸 대상이었다. 이유는 단순하다 — 이 위키의 생성물은 원본 코드가 바뀔 때마다 코드에서 다시 쓰인다. (매일 밤 자동 파이프라인이 돌긴 하지만, 전체를 다시 쓰는 게 아니다. 그사이 git HEAD가 움직인 — 즉 코드가 ..

코드 위키 AI 도구들이 GitHub repo를 받아서 위키를 자동 생성할 때, 거의 공통으로 다음 8개 섹션을 만든다.Overview · Structure · Architecture · API · Subsystems · Operations · Testing · Glossary.처음 보면 그냥 목차처럼 보이지만, 사실 이 8섹션은 "코드를 처음 보는 사람이 어디서부터 봐야 하는가"라는 질문에 대한 누적된 답이다. 위키나 docs 폴더가 흔히 자유 형식인데, 이 셋업은 읽는 사람의 경로를 미리 설계해 둔 것이다. 그리고 이 구조는 사람뿐 아니라 AI 에이전트가 코드를 이해하는 데도 결정적인 도움이 된다. 이 글은 8섹션을 하나씩 풀어 — 무엇이고 왜 거기 있고 어떤 효과가 있는지 — 설명한다.왜 굳이 8개..