에이전트 시대에 문학적 프로그래밍을 다시 검토해야 한다

• 코드와 자연어 설명을 하나의 서술로 엮는 문학적 프로그래밍(Literate Programming) 은 코드와 설명 두 가지를 병행 유지해야 하는 부담 때문에 널리 쓰이지 못했으나, AI 코딩 에이전트가 이 핵심 노동을 제거할 수 있음
• Emacs Org Mode의 org-babel을 통해 다중 언어 문학적 프로그래밍이 가능하지만, 대규모 프로젝트에서는 소스 코드 추출(tangling) 과정의 번거로움이 한계
• 에이전트에게 Org 파일 기반 런북(runbook) 작성을 지시하면, 설명으로 의도를 풀어쓰고 코드 블록을 대화형으로 실행하며 결과를 문서에 저장하는 워크플로우가 가능
• 에이전트가 설명·코드 간 동기화와 tangling을 자동 처리하므로, 코드 변경 시 설명을 다시 쓰는 수고가 사라지며, LLM이 가장 잘하는 번역·요약 능력을 활용
• 엔지니어의 역할이 코드 작성에서 코드 읽기 중심으로 전환되는 흐름에서, 에이전트가 유지하는 서술형 코드베이스의 실용성이 핵심 질문으로 부상

---

문학적 프로그래밍의 개념과 한계

• 문학적 프로그래밍(Literate Programming) 은 코드와 자연어 설명을 섞어, 사전 지식 없는 독자도 코드베이스를 하나의 서술로 읽고 작동 방식을 이해할 수 있도록 하는 아이디어
• 매력적인 개념이지만, 실제로는 코드 자체와 설명이라는 두 개의 병렬 서술을 유지해야 하는 부담이 발생하며, 이것이 채택을 제한한 근본 원인
• 실무에서 가장 흔한 형태는 데이터 과학 커뮤니티의 Jupyter 노트북으로, 설명과 계산, 결과가 웹 브라우저에서 함께 표시

Emacs Org Mode와 문학적 프로그래밍

• Emacs Org Mode는 org-babel 패키지를 통해 다중 언어 문학적 프로그래밍을 지원하며, 임의의 언어를 실행하고 결과를 문서에 캡처 가능
  • 다만 이 방식은 소수의 열성 사용자에게만 남아 있는 니치 패턴
• 대규모 소프트웨어 프로젝트에서 Org 파일을 소스의 진본(source of truth)으로 사용하면, 소스 코드가 사실상 컴파일된 출력물이 되며, 매 편집 후 코드를 추출("tangle")해서 목적지에 배치해야 함
  • 자동화 가능하지만, 사용자나 에이전트가 실제 소스를 편집한 후 다음 tangle 시 덮어쓰기되는 문제가 발생하기 쉬움

에이전트 이전의 활용 패턴

• 개인 설정 관리(bookkeeping personal configuration)에 문학적 프로그래밍을 사용하는 데 충분한 성과가 있어 LLM 등장 이전에도 이 아이디어를 포기하지 않았음
• 수동 테스트와 노트 작성에 Org Mode를 활용하는 패턴: 명령줄 대신 에디터에서 명령을 작성·실행하고, 각 단계가 올바를 때까지 편집한 뒤 결과를 제자리에 저장
  • "노트 작성과 테스트 실행을 결합하면, 테스트 완료 시 노트가 무료로 생성됨"

에이전트와 함께하는 새로운 워크플로우

• Claude, Kimi 등 코딩 에이전트들은 Org Mode 문법을 잘 이해하며, Org는 관대한 마크업 언어라 LLM이 매우 잘 다룸
  • Org Mode의 방대한 문법이 인간에게는 단점이지만, 언어 모델에게는 문제가 되지 않음
• 기능 테스트 시 에이전트에게 Org 런북 작성을 요청하면:
  • 설명이 각 단계의 의도에 대한 모델의 성찰을 담음
  • 코드 블록은 검토 후 하나씩 또는 전체를 스크립트처럼 대화형 실행 가능
  • 결과가 코드 아래에 Jupyter 노트북처럼 저장
• 설명을 편집하고 모델에게 코드 업데이트를 요청하거나, 코드를 편집하고 모델이 설명에 의미를 반영하거나, 에이전트가 양쪽을 동시에 변경 가능
  • 병렬 서술 유지 문제가 사라짐

에이전트가 제거하는 핵심 노동

• 에이전트에게 tangling 처리를 맡기면 코드 추출 문제도 해소
• AGENTS.md 파일로 에이전트에게 Org Mode 파일을 소스의 진본으로 취급하고, 항상 설명을 작성하며, 실행 전에 tangle하도록 지시 가능
  • 에이전트는 이 모든 작업에 능숙하며, 코드 수정 후 설명을 다시 쓰는 것에 결코 지치지 않음
• 문학적 프로그래밍이 널리 쓰이지 않는 근본적 추가 노동을 에이전트가 제거하며, 이는 LLM이 가장 잘하는 번역과 요약 능력을 활용하는 것

기대되는 이점

• 코드베이스를 다양한 포맷으로 내보내기(export) 하여 편하게 읽을 수 있음
  • 엔지니어의 주요 역할이 작성에서 읽기로 전환되고 있다면 특히 중요
• 데이터로 뒷받침되지는 않지만, 각 코드 블록의 의도를 설명하는 서술이 코드와 함께 컨텍스트에 나타나므로 생성되는 코드의 품질도 향상될 가능성 추정
• 현재까지 대규모·본격적 코드베이스에서는 시도하지 못했으며, 테스트와 수동 프로세스 문서화 워크플로우에서 활용 중

Org Mode의 한계와 대안

• Org 포맷이 Emacs와 밀접하게 통합되어 있어 제약 요인이며, Org가 Emacs 밖으로 나와야 한다는 오래된 소신
• Markdown을 대안으로 추천하고 싶으나, Markdown에는 메타데이터 포함 기능이 부족
  • Org Mode의 Properties 개념은 문서를 Emacs Lisp로 프로그래밍적으로 조작 가능하게 하며, 이제 LLM이 해당 문서 전용 맞춤 기능을 file variables 섹션에 Emacs Lisp로 작성해줌
  • Markdown에는 코드 블록의 실행 세부 사항(실행 위치, 원격 머신 등)을 지정하는 Org Mode의 header arguments 같은 기능이 없음
• 흥분을 주는 것은 Emacs의 구체적 구현이 아니라 아이디어 자체

핵심 질문

• "에이전트를 통해, 서술처럼 읽을 수 있는 대규모 코드베이스를 갖추고 코드 변경과 설명이 동기화되는 상태를 지칠 줄 모르는 기계가 유지하는 것이 실용적이 될 수 있는가?"

[xguru]

위키백과 - 문학적 프로그래밍

문학적 프로그래밍(literate programming)은 프로그래밍 방법론의 한 가지로, 프로그래밍을 할 때 컴퓨터로 컴파일 가능한 코드를 만드는 것보다 사람이 이해하기 쉬운 코드를 만드는 것에 중점을 두는 방법이다. 다시 말해, 사람이 보고 이해할 수 있도록 문서를 만들듯이 프로그래밍을 하는 것이 목적이다. '마치 문학작품을 읽는 것처럼 프로그래밍을 읽을 수 있도록 만드는 것'이 목표이므로 '문학적 프로그래밍'이라는 이름을 지었다.

[GN⁺]

Hacker News 의견들

• LLM이 자신의 주석을 직접 남기게 하는 방식이 가장 간단하다고 생각함
  이렇게 하면 LLM이 이후 코드를 다시 읽을 때 자기 주석을 참고하게 되어, 일종의 즉시형 장기 기억(just-in-time memory) 역할을 함
  <summary>에는 요약을, <remarks>에는 이유와 맥락을, <params>에는 제약사항을 적도록 하고, 인라인 주석은 최소화함
  이렇게 하면 PR 리뷰 시 LLM의 사고 과정을 <remarks>에서 직접 확인할 수 있어, 의도와 다르게 이해한 부분을 쉽게 파악할 수 있음

  • 내 경험상 LLM이 추가한 주석은 너무 장황하고 유치함
    결국 자기 컨텍스트를 쓸데없는 정보로 오염시켜 이해력이 더 떨어짐
    아직은 인간 수준의 문해력(literacy) 과는 거리가 멂
  • 인간이 보기엔 LLM 주석이 시끄럽고 불필요한 정보로 느껴질 때가 많음
    하지만 LLM이 다시 같은 코드를 읽을 때 걸리는 부분이 바로 이런 주석이라, 오히려 가치 있는 정보일 수도 있음
  • 인간은 코드를 작성한 이유를 기억하지만, LLM은 컨텍스트 윈도우가 제한적이라 그런 정보가 금방 사라짐
    그래서 이런 주석이 그 기억을 보존하는 역할을 함
  • 이런 걸 보니 에이전트가 작성한 주석에는 서명을 남겨서 구분할 수 있게 해야겠다는 생각이 듦

• 자연어는 모호함 때문에 프로그래밍 언어가 생겼다고 생각함
  그래서 코드 주석도 결국 모호해지고, 실행되지 않으니 금방 낡음
  LLM은 코드 번역엔 강하지만, 자연어 프롬프트를 코드로 바꾸는 건 여전히 어렵다고 느낌
  좋은 코드는 의도를 명확히 표현해야 하며, 주석이 많다는 건 코드 품질이 낮다는 신호일 수도 있음

  • 좋은 코드만으로 충분하다면 문서를 읽지 않고 소스 코드만 보면 될 것임
    하지만 좋은 소프트웨어는 좋은 문서화도 포함해야 함
    문학적 프로그래밍은 구현 세부보다는 설명 중심의 글쓰기임
  • 법률 문체가 생긴 이유처럼, 프롬프트도 구체적일수록 효과적임
    코드로는 ‘어떻게’를 좁게 정의하지만, 자연어는 ‘무엇을’ 중심으로 표현할 수 있어 LLM이 더 나은 방법을 제안할 여지가 있음
  • 코드와 문서는 상호 오류 정정 코드처럼 함께 작동해야 함
    중복된 정보가 있어야 오류를 탐지하고 수정할 수 있음
  • 프로그래밍 언어도 완전히 명확하지는 않음
    다만 해석의 자유도를 좁히는 규칙을 둘 뿐임
    때로는 은유나 모호함이 더 적절한 표현일 때도 있음
  • 나는 LLM에게 문학적 프로그래밍을 시키진 않지만, 트레이드오프를 설명하게 함
    예시 코드와 문서를 템플릿으로 주면 환각(hallucination) 이 줄어듦

• 문학적 프로그래밍 스타일의 주석이 인간의 코드 이해를 돕는다는 연구가 있음
  Google 연구진이 LLM이 이런 주석을 갱신할 수 있는지, 또 그게 인간 이해에 도움이 되는지 실험했음
  결론은 의도를 설명하는 블록 수준 주석이 가장 효과적이라는 것임
  (참고: 2024 arXiv 논문 "Natural Language Outlines for Code")

• 최근 흥미로운 현상은, 예전엔 인간을 위해 README나 아키텍처 문서를 쓰는 걸 귀찮아했는데
  이제 LLM을 위해 쓴다고 하면 사람들이 훨씬 적극적으로 한다는 점임

  • 인간은 문서를 거의 안 읽고, 필요할 때만 질문함
    하지만 LLM은 매 작업마다 문서를 참고하므로, 문서화의 동기가 훨씬 강해짐
  • 예전엔 ‘엔지니어링 위생’이라며 무시되던 습관들이 이제 에이전트에게 큰 이득을 줌
    커밋 메시지, ADR 같은 기록은 인간은 안 보지만 LLM은 다 읽음
    결국 이런 습관이 인간 신입에게도 도움이 되는 셈임
  • 예전에 들은 말이 있음
    컴퓨터와 대화하는 법을 배우느라 인간과 대화하는 법을 놓친 사람들이 졸업 후 더 뒤처졌다는 이야기임
  • 문서는 코드보다 더 빨리 부패함
    코드가 동작하는 데 문서의 정확성은 필요 없기 때문임
    그래서 종종 문서보다 코드를 직접 보는 게 낫다고 느낌
  • 아마도 이런 습관은 관리자 입장에서 더 자연스러웠을지도 모름

• 나는 가벼운 문학적 프로그래밍과 관례 중심 언어의 조합이 에이전트 시대에 잘 맞는다고 봄
  Go처럼 빠른 컴파일과 명확한 스타일 가이드가 있는 언어가 좋음
  에이전트가 코드를 작성할 때 Google Go Style Guide를 참고하게 하면 꽤 좋은 결과가 나옴

  • Go는 스타일 가이드와 패턴이 강한 언어라 LLM에게 잘 맞음
    (참고: Rob Pike 관련 일화)

• LLM은 언어 모델이므로 명확한 글쓰기에 투자할 가치가 큼
  꼭 문학적 프로그래밍까지는 아니더라도, 좋은 이름, docstring, 타입 시그니처, “왜”를 설명하는 주석이 중요함
  결국 핵심은 인간과 LLM 모두를 위한 커뮤니케이션 패턴을 만드는 것임

  • 필요한 건 docstring과 문학적 프로그래밍의 중간 지점임
    파일·디렉터리·프로젝트 단위의 상위 구조를 설명하는 문서가 특히 중요함
    다만 이런 개념은 여러 파일에 걸쳐 있어, 어디에 써야 할지와 문서-코드 동기화가 늘 문제임
  • Notebook 자체가 문학적 프로그래밍의 한 형태라고 생각함

• 지난 10년간 거의 모든 코드를 문학적 프로그래밍 방식으로 작성해왔음
  nbdev를 만들어 노트북 기반으로 코드, 문서, 테스트를 함께 관리함
  최근엔 LLM을 통합한 Solveit이라는 툴을 만들어 회사 전반에서 사용 중임
  (Solveit 링크)
  문학적 프로그래밍은 프로그래밍 외의 업무에도 유용함

  • 다만 Solveit은 이름이 흔해서 검색이 어렵고, 소개 영상이 너무 김
    짧은 데모나 스크린샷을 추가하면 좋겠음

• LLM을 이용해 주석과 코드의 불일치를 자동으로 탐지하는 아이디어가 흥미로움
  문서는 시간이 지나면 반드시 코드와 어긋나는데, 이를 자동으로 감지할 수 있다면 큰 가치가 있음
  이런 걸로 스타트업을 만들 수도 있을 듯함

  • 이미 2023년 이후 이 분야 스타트업이 10개 이상 생겼음 (작성자는 테크니컬 라이터)
  • 예전에 생각했던 아이디어인데, 모든 디렉터리·모듈·클래스·함수에 DocString/JSDoc을 강제하는 시스템임
    변경은 문서 PR로 시작하고, 개발자가 코드로 반영함
    리뷰 시 문서와 코드가 나란히 표시되어 검증하도록 함
    문서 간 링크로 맥락 탐색도 가능하게 설계함
  • 이미 Promptless.ai 같은 유사 스타트업이 존재함
  • CI에 AI를 연결해 주기적으로 문서-코드 불일치나 아키텍처 드리프트를 감지할 수도 있음
    예: GitHub gh-aw, Continue.dev
  • 하지만 “그냥 AI에게 코드가 뭘 하는지 물어보면 되지 않나?”라는 의문도 있음

• 테스트 코드와 프로덕션 코드의 쌍 구조는 회계의 복식부기처럼 유용함
  테스트가 코드의 의도를 설명해주고, 코드가 테스트의 의미를 보완함
  리뷰 시 한쪽이 헷갈리면 다른 쪽을 보면 됨
  단점은 코드량이 늘어난다는 점이지만, 가독성 향상이 그만큼의 가치가 있음

• 나도 최근 의도 기반 코딩에 대해 글을 썼는데, 이 논의와 맞닿아 있음
  (블로그 링크)
  코드베이스를 다양한 형식으로 읽기 편하게 변환할 수 있다는 점이 중요함
  앞으로 비전공자들도 코드에 더 가까워질 것이고, 자연어의 포함이 그들의 생산성과 학습에 큰 도움이 될 것임