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

> Clean Markdown view of GeekNews topic #27383. Use the original source for factual precision when an external source URL is present.

## Metadata

- GeekNews HTML: [https://news.hada.io/topic?id=27383](https://news.hada.io/topic?id=27383)
- GeekNews Markdown: [https://news.hada.io/topic/27383.md](https://news.hada.io/topic/27383.md)
- Type: GN+
- Author: [neo](https://news.hada.io/@neo)
- Published: 2026-03-11T03:33:22+09:00
- Updated: 2026-03-11T03:33:22+09:00
- Original source: [silly.business](https://silly.business/blog/we-should-revisit-literate-programming-in-the-agent-era/)
- Points: 14
- Comments: 2

## Summary

문학적 프로그래밍은 코드와 설명을 하나의 서술로 엮어 읽히게 하는 개념이지만, 두 서술을 병행 관리해야 하는 부담으로 확산되지 못했습니다. 이제 **AI 코딩 에이전트**가 이 병렬 유지의 노동을 대신하며, Org Mode 기반 런북을 통해 설명·코드·실행 결과를 자동으로 동기화하는 흐름이 열리고 있습니다. 코드 작성보다 읽기 중심으로 이동하는 개발 문화 속에서, 에이전트가 유지하는 **서술형 코드베이스**의 실용성이 새로운 논의의 중심에 서고 있습니다.

## Topic Body

- 코드와 자연어 설명을 하나의 서술로 엮는 **문학적 프로그래밍(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의 구체적 구현이 아니라 **아이디어 자체**  
  
### 핵심 질문  
  
- "에이전트를 통해, 서술처럼 읽을 수 있는 대규모 코드베이스를 갖추고 **코드 변경과 설명이 동기화되는 상태를 지칠 줄 모르는 기계가 유지**하는 것이 실용적이 될 수 있는가?"

## Comments



### Comment 52786

- Author: neo
- Created: 2026-03-11T03:33:22+09:00
- Points: 2

###### [Hacker News 의견들](https://news.ycombinator.com/item?id=47300747) 
- 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"](https://arxiv.org))

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

- 나는 **가벼운 문학적 프로그래밍**과 **관례 중심 언어**의 조합이 에이전트 시대에 잘 맞는다고 봄  
  Go처럼 빠른 컴파일과 명확한 스타일 가이드가 있는 언어가 좋음  
  에이전트가 코드를 작성할 때 [Google Go Style Guide](https://google.github.io/styleguide/go/)를 참고하게 하면 꽤 좋은 결과가 나옴  
  - Go는 **스타일 가이드와 패턴**이 강한 언어라 LLM에게 잘 맞음  
    (참고: [Rob Pike 관련 일화](https://news.ycombinator.com/item?id=16143918))

- LLM은 언어 모델이므로 **명확한 글쓰기**에 투자할 가치가 큼  
  꼭 문학적 프로그래밍까지는 아니더라도, **좋은 이름, docstring, 타입 시그니처, “왜”를 설명하는 주석**이 중요함  
  결국 핵심은 인간과 LLM 모두를 위한 **커뮤니케이션 패턴**을 만드는 것임
  - 필요한 건 docstring과 문학적 프로그래밍의 **중간 지점**임  
    파일·디렉터리·프로젝트 단위의 상위 구조를 설명하는 문서가 특히 중요함  
    다만 이런 개념은 여러 파일에 걸쳐 있어, 어디에 써야 할지와 **문서-코드 동기화**가 늘 문제임
  - **Notebook** 자체가 문학적 프로그래밍의 한 형태라고 생각함

- 지난 10년간 거의 모든 코드를 **문학적 프로그래밍 방식**으로 작성해왔음  
  nbdev를 만들어 노트북 기반으로 코드, 문서, 테스트를 함께 관리함  
  최근엔 LLM을 통합한 **Solveit**이라는 툴을 만들어 회사 전반에서 사용 중임  
  ([Solveit 링크](https://solve.it.com/))  
  문학적 프로그래밍은 프로그래밍 외의 업무에도 유용함
  - 다만 Solveit은 이름이 흔해서 검색이 어렵고, 소개 영상이 너무 김  
    **짧은 데모나 스크린샷**을 추가하면 좋겠음

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

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

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

### Comment 52805

- Author: xguru
- Created: 2026-03-11T09:52:16+09:00
- Points: 1

[위키백과 - 문학적 프로그래밍](https://ko.wikipedia.org/wiki/%EB%AC%B8%ED%95%99%EC%A0%81_%ED%94%84%EB%A1%9C%EA%B7%B8%EB%9E%98%EB%B0%8D)  
> 문학적 프로그래밍(literate programming)은 프로그래밍 방법론의 한 가지로, 프로그래밍을 할 때 컴퓨터로 컴파일 가능한 코드를 만드는 것보다 사람이 이해하기 쉬운 코드를 만드는 것에 중점을 두는 방법이다. 다시 말해, 사람이 보고 이해할 수 있도록 문서를 만들듯이 프로그래밍을 하는 것이 목적이다. '마치 문학작품을 읽는 것처럼 프로그래밍을 읽을 수 있도록 만드는 것'이 목표이므로 '문학적 프로그래밍'이라는 이름을 지었다.