에이전트 시대에 리터러시 프로그래밍을 재검토해야 한다

Source: Hacker News

Literate Programming, Org Mode, and Coding Agents

Literate programming은 코드가 prose와 뒤섞여 있어, 정보를 모르는 독자도 코드 베이스를 서사처럼 읽고 그것이 어떻게 작동하고 무엇을 하는지 이해할 수 있어야 한다는 아이디어입니다.

이 아이디어에 오래전부터 매료되었고 몇 가지 경우¹²에서 활용해 보았지만, 실제로는 literate programming이 코드 자체와 prose라는 두 개의 병렬 서사를 유지해야 하는 번거로운 작업으로 변하는 것을 발견했습니다. 이 때문에 채택이 제한되었습니다.

역사적으로 literate programming은 데이터‑사이언스 커뮤니티에서 Jupyter notebooks 형태로 가장 흔히 사용되었습니다. 여기서는 설명이 계산 및 결과와 함께 웹 브라우저에 나타납니다.

이 블로그를 자주 읽는 독자라면 Emacs Org Mode가 org‑babel 패키지를 통해 다중 언어 literate programming을 지원하고, 실행 결과를 문서에 다시 캡처할 수 있다는 점을 알고 있을 것입니다. 하지만 이는 저 같은 괴짜에게는 여전히 틈새 패턴에 불과했습니다.

저만큼 이 패턴에 열정적인 사람이라도, Org를 대규모 소프트웨어 프로젝트의 진실된 소스로 사용하려면 번거로움이 따릅니다. 소스 코드는 본질적으로 컴파일된 출력물이 되고, Org 파일을 편집할 때마다 코드를 다시 추출해 목적지에 배치해야 하기 때문입니다(Org 용어로는 tangling이라고 합니다). 물론 자동화할 수는 있지만, 실제 소스를 편집했는데 다음 tangle 과정에서 덮어써지는 상황에 쉽게 빠질 수 있습니다.

그럼에도 불구하고 저는 개인 설정을 관리하기 위해 literate programming을 활용하면서 충분한 성공을 거두었고, LLM이 등장하기 전부터도 이 아이디어를 완전히 포기하지 못했습니다.

A concrete workflow

예를 들어, 코딩 에이전트를 사용하기 전에는 Org Mode를 수동 테스트와 노트‑테이킹에 활용하는 패턴을 적용했습니다. 명령줄에서 작업하는 대신, 에디터에 명령을 더 많이 작성하고 그 자리에서 실행·수정하면서 각 단계가 올바르게 동작하도록 했으며, 작업이 끝나면 정확히 수행된 단계들을 설명하는 문서를 바로 얻을 수 있었습니다.

노트를 만들면서 테스트를 실행하면, 테스트가 완료될 때 노트가 자동으로 생성됩니다.

코딩 에이전트가 등장하면서 이 점은 더욱 매력적으로 변했습니다. Claude, Kimi 등은 Org Mode 구문을 훌륭히 이해합니다; 이 마크업 언어는 관대하고, 그들은 매우 능숙합니다. 모든 문서는 온라인에 존재하고 학습 데이터에도 포함됐을 가능성이 높으며, Org Mode의 큰 단점인 방대한 구문 역시 언어 모델에게는 전혀 문제가 되지 않습니다.

이제 기능을 테스트하고 싶을 때, clanker³에게 Org 형식의 런북을 작성해 달라고 요청합니다. 그런 다음 나는 이를 검토합니다—prose는 각 단계에 대한 모델의 의도 반영을 설명하고, 코드 블록은 검토가 끝난 뒤 하나씩 혹은 전체 파일을 스크립트처럼 실행할 수 있습니다. 결과는 코드 아래 문서에 저장되며, 이는 Jupyter notebook과 동일한 방식입니다.

나는 prose를 수정하고 모델에게 코드를 업데이트하도록 요청하거나, 코드를 수정하고 모델이 텍스트에 의미를 반영하도록 할 수 있습니다. 혹은 두 부분을 동시에 변경하도록 에이전트에 요청할 수도 있습니다. 이렇게 하면 병렬 시스템을 유지해야 하는 문제가 사라집니다.

에이전트는 tangling을 처리하도록 지시받았으므로, 추출 문제도 사라집니다. AGENTS.md 파일을 통해 Org 파일을 진실된 소스로 취급하고, 항상 prose로 설명한 뒤 실행 전에 tangle하도록 지시할 수 있습니다. 에이전트는 이러한 작업을 매우 잘 수행하며, 코드에 약간의 수정이 있더라도 prose를 다시 설명하는 데 전혀 지치지 않습니다.

Why agents make literate programming practical

Literate programming의 근본적인 추가 작업—즉, 널리 실천되지 않는 이유—은 에이전트에 의해 제거됩니다. 에이전트는 c

Source: …

capabilities the large language model is best at: translation and summarization.

As a benefit, the code base can now be exported into many formats for comfortable reading. This is especially important if the primary role of engineers is shifting from writing to reading.

I don’t have data to support this, but I also suspect that literate programming will improve the quality of generated code, because the prose explaining the intent of each code block will appear in context alongside the code itself.

I have not personally had the opportunity to try this pattern yet on a larger, more serious codebase. So far, I have only been using this workflow for testing and for documenting manual processes, but I am thrilled by its application there.

Org 모드 vs. 기타 마크업 언어

I also recognize that the Org format is a limiting factor, due to its tight integration with Emacs. However, I have long believed that Org should escape Emacs. I would promote something like Markdown instead, although Markdown lacks the ability to include rich metadata⁴.

But, as usual in my posts about Emacs, it’s not Emacs’s specific implementation of the idea that excites me – it’s Org’s implementation of literate programming. It is the idea itself that is exciting, not the tool.

에이전트를 사용하면, 코드가 기계에 의해 끊임없이 동기화되면서 서사처럼 읽을 수 있는 대규모 코드베이스를 실제로 구현할 수 있게 될까요?
저는 이것이 매력적인 질문이라고 생각합니다.

---

Footnotes

The lack of metadata in Markdown also means that there is nowhere to store information about code blocks that would be extracted from a literate document. Org Mode provides [header arguments](https://orgmode.org/manual/Using-Header-Arguments.html) that can be applied to source code blocks, providing instruction to the machine about execution details like where the code should be executed, which might even be a remote machine.

Footnotes

1. 내가 탐색한 사용 사례의 예시. ↩

2. 문학적 프로그래밍을 적용한 또 다른 별개의 시나리오. ↩

3. 나는 런북을 작성하는 LLM을 “클랭커”라고 부른다. ↩

4. Org Mode에는 properties와 같은 개념이 있어 Emacs Lisp로 문서를 프로그래밍 방식으로 조작할 수 있다. 과거에는 문서에 상상했던 인터랙티브 기능을 구현하려고 Lisp를 만지작거리곤 했지만, 실제로는 시간을 내기 어려웠다. 이제는 LLM이 file‑variables 섹션에 맞춤형 기능을 가진 Emacs Lisp 코드를 기꺼이 삽입해 주어, 그 인터랙티브 문서를 구현할 수 있다. ↩