AI가 만든 코드를 사람이 이해하는 방법, Cluedoc으로 정리하는 기능 중심 문서화

AI 코딩 에이전트가 코드를 작성하는 시대가 되면서 개발 속도는 눈에 띄게 빨라졌습니다. 하지만 그만큼 새로운 문제가 생겼습니다.
코드는 빠르게 늘어나는데, 정작 사람은 그 코드를 따라가며 이해하기가 점점 어려워지고 있다는 점입니다. README는 금방 낡고, 수동으로 관리하는 문서는 코드 변경 속도를 따라가지 못합니다.

이 글에서는 이러한 문제를 해결하기 위해 등장한 Cluedoc이 무엇인지, 어떤 방식으로 코드베이스를 문서화하며, 기존 문서화 도구와 무엇이 다른지 정리합니다. 특히 AI 에이전트 중심 개발 환경에서 왜 Cluedoc이 의미를 가지는지를 중심으로 설명합니다.

반응형

---

AI 에이전트 시대, 문제는 ‘작성’이 아니라 ‘이해’

과거에는 사람이 직접 코드를 작성했기 때문에, 코드의 의도와 구조를 어느 정도 머릿속에 담고 있었습니다.
하지만 지금은 상황이 달라졌습니다.

• 코드는 에이전트가 작성한다
• 하루 사이에 코드가 여러 번 바뀐다
• 내가 직접 작성하지 않은 코드가 대부분이다

이 환경에서 가장 부족해진 자원은 코드를 쓰는 시간이 아니라 코드를 이해하는 시간입니다.
“이 시스템이 지금 무엇을 하는지”, “이 변경이 안전한지”를 빠르게 파악하는 것이 점점 더 어려워지고 있습니다.

Cluedoc은 바로 이 지점에서 출발합니다.

---

Cluedoc이 해결하려는 핵심 문제

Cluedoc의 목표는 단순히 문서를 자동으로 만들어주는 것이 아닙니다.
핵심은 코드가 빠르게 변해도 사람이 시스템을 이해할 수 있는 상태를 유지하는 것입니다.

이를 위해 Cluedoc은 다음과 같은 전제를 둡니다.

• 소프트웨어 시스템은 코드 묶음이 아니라 기능(feature)의 집합이다
• 하나의 기능은 하나의 문서로 설명되어야 한다
• 문서는 코드 변경과 함께 자동으로 유지되어야 한다

이 전제를 기반으로 Cluedoc은 코드베이스를 사람이 읽을 수 있는 “기능 중심 지식 구조”로 변환합니다.

---

기능 단위 문서화: One Paper per Feature

Cluedoc에서 문서의 최소 단위는 파일이나 함수가 아니라 기능(feature)입니다.
각 기능은 하나의 문서로 작성되며, 이 문서는 논문 형식을 따릅니다.

• 하나의 기능 = 하나의 문서
• 기능이 커지면 하위 기능으로 분리
• 문서는 기능의 계층 구조를 그대로 반영

이 구조는 코드 디렉터리와 무관합니다.
모노레포든 단일 패키지든 상관없이, 문서는 오직 “무슨 기능을 하는가”를 기준으로 나뉩니다.

결과적으로 문서 전체는 Capability Tree, 즉 기능 트리 구조를 이룹니다.

---

코드 변경을 따라 움직이는 문서 구조

Cluedoc은 한 번에 전체 문서를 생성하지 않습니다.
대신 코드 변경을 기준으로 점진적으로 문서를 갱신합니다.

• 변경된 코드가 어디에서 호출되는지를 따라가 상위 기능을 갱신하고
• 변경된 코드가 무엇을 호출하는지를 따라가 하위 협력 기능을 갱신합니다

이 방식으로 문서는 위아래 방향으로 함께 업데이트됩니다.
시간이 지날수록 기능 트리는 점점 더 촘촘해지고 정확해집니다.

또한 기능이 사라지거나 이동하면, 문서 역시 생성·분리·이름 변경·삭제가 자동으로 반영됩니다.

---

코드 없는 문서, 하지만 코드에 의해 고정된다

Cluedoc 문서의 중요한 특징 중 하나는 문서 본문에 코드가 등장하지 않는다는 점입니다.

• 코드 스니펫 없음
• 함수명, 파일 경로 없음
• 사람 중심의 개념과 용어로 설명

그 대신 문서 상단 메타데이터에만 해당 기능의 코드 출처가 기록됩니다.
이 방식 덕분에 코드가 리팩터링되거나 위치가 바뀌어도 문서의 핵심 설명은 거의 바뀌지 않습니다.

문서는 항상 사람의 언어로 추상화된 설명을 유지하고, 코드와의 연결은 구조적으로만 관리됩니다.

---

모든 문서는 같은 구조를 가진다

Cluedoc의 모든 문서는 동일한 형식을 따릅니다.

1. 시각적 다이어그램(히어로 비주얼)
2. Abstract: 기능의 요약과 목적
3. Introduction: 해결하려는 문제
4. Related Work: 연결된 다른 기능 문서
5. Description: 작동 방식 설명(시각 자료 중심)
6. Conclusion: 핵심 정리와 다음 읽을 문서 안내

특히 Related Work 섹션을 통해 문서들은 서로 인용 관계로 연결됩니다.
이로 인해 문서 전체는 단순한 나열이 아니라 탐색 가능한 지식 그래프가 됩니다.

---

기존 문서화 도구와의 차이점

기존 도구들은 주로 다음과 같은 방식이었습니다.

• 함수, 클래스, API 기준의 레퍼런스 문서
• 코드 주석을 기반으로 한 자동 생성
• 외부 위키나 별도 서버에서 관리

Cluedoc은 이와 다릅니다.

• 심볼이 아닌 기능 단위 설명
• 코드 변경 흐름에 따라 자동 갱신
• 저장소 내부에 Markdown으로 함께 버전 관리
• 에이전트가 코드를 수정하는 과정 안에서 문서도 함께 수정

즉, 문서가 코드 바깥에 있는 부속물이 아니라 개발 과정의 일부로 들어옵니다.

---

Cluedoc을 사용하면 달라지는 점

Cluedoc을 도입하면 개발 경험은 다음과 같이 바뀝니다.

• 코드를 처음 보는 사람도 시스템 구조를 빠르게 파악할 수 있다
• 변경 사항이 전체 기능 구조에 어떤 영향을 주는지 바로 알 수 있다
• 코드 리뷰와 인수인계의 부담이 줄어든다
• AI 에이전트가 만든 코드도 사람이 다시 ‘소유’할 수 있다

특히 에이전트 중심 개발 환경에서는, Cluedoc이 사실상 사람과 코드 사이의 통역 역할을 하게 됩니다.

---

728x90

AI 에이전트는 앞으로 더 많은 코드를, 더 빠르게 만들어낼 것입니다.
이 환경에서 경쟁력은 “얼마나 빨리 작성하느냐”가 아니라
“얼마나 잘 이해하고 통제하느냐”에 달려 있습니다.

Cluedoc은 문서를 단순한 설명서가 아닌,
코드베이스를 이해하기 위한 지속적인 지식 구조로 바꿉니다.

코드를 논문처럼 읽을 수 있게 만드는 것.
이것이 Cluedoc이 제안하는 새로운 문서화 방식입니다.

300x250

https://keunwoopark.github.io/cluedoc/

Cluedoc: document your codebase as interlinked visual papers