rhwp에 최근 3개월 간 기여하며 AI를 활용한 contributing workflow에 Hyper-Waterfall을 적극적으로 활용한 경험을 공유합니다.

[postmelee]

rhwp가 가능한 이유: 하이퍼 워터폴을 통한 문서 증류

하이퍼 워터폴의 장점 중 하나인 문서 증류의 실제 예시를 소개합니다.

제가 3개월간 rhwp에 contributing, collaborator로 활동하며, 공개 활동 기준 163 commits, 79 PRs, 76 issues, 16 PR reviews 수행 (렌더링 정확도, 웹 편집기 UX, 브라우저 확장, CI 개선, 회귀 검증에 기여) 과정에서 얻은 교훈을 공유합니다.

결과적으로 Codex for open source 선정으로 ChatGPT $200 for 6 months을 OpenAI로 부터 지원받게 된 제 몇 달간의 배경에 대한 이야기이기도 합니다.

2026.07.13 기준, 현재까지 rhwp 프로젝트의 이슈는 2,246개, PR은 2,251개 입니다.

rhwp는 하이퍼 워터폴 방법론을 프로젝트 전반에 적용하여 개발 중입니다. 그리고 이 방법론 덕분에, 이슈 및 PR 개수가 곧 프로젝트의 자산입니다.

하이퍼워터폴: 거시적 워터폴 + 미시적 애자일

Hyper-Waterfall: AI 시대의 소프트웨어 개발 방법론

거시적으로 워터폴

공통 공유 지식은 장기 기억 폴더 (mydocs/manual, mydocs/tech 등) 에 기록합니다.

특정 작업 중 발견한 중요한 단서나 회귀 가능 취약지점, 앞으로 장기적으로 다른 작업에서도 중요하게 참조해야하는 정보를 공통 문서로 생성합니다.

이러한 mydocs/manual 등에 저장되는 공통 지식 문서들로 프로젝트를 ‘**거시적으로 워터폴’**하게 통제합니다.

미시적으로 애자일

애자일한 한 작업 내에서는 수행 계획서 - 구현 계획서 - 단계별 보고서 - 최종 보고서 가 작업의 산출물입니다.

편의점 아르바이트와 하이퍼 워터폴

저는 지금 편의점 아르바이트를 하며 글을 작성하고 있습니다.

편의점 근무자는 항상 지켜야할 큰 틀과 규칙, 매뉴얼이 있습니다 - 거시적 워터폴

하지만 실제 업무시간에는 예측 불가한 변수: 진상 손님, 이상한 요구, 재고 상태 등이 있습니다.

이러한 상황에는 빠른 피드백과 반복적인 조정, 상황에 따른 유연한 대처가 필요합니다 - 미시적 워터폴

항상 수직적 워터폴 지침을 강하게 적용하는 것은 때로는 방해됩니다. 참고하며 현재 상황에 맞게 해석할 필요가 있습니다. 동시에 공통적인 큰 틀에서의 지켜야할 규약은 분명히 필요합니다.

rhwp의 하이퍼워터폴

하이퍼워터폴은 이슈 번호를 기반으로 문서명을 생성해 작업 맥락 및 의사 결정 사항 등을 증류해 기록합니다.

한 이슈(작업)에서 구현계획서 - 수행계획서 - Stage 계획서 (3~6) - 최종 보고서 가 문서로 남으며, 최소로 계산해도 6 * 2222 = 13,332 개 이상의 문서가 있습니다.

이것은 단순한 문서가 아닙니다.

여태껏 수많은 contributor와 maintainer이 사용한 토큰의 정수, 고민 내용, 의사 결성 사항, 성공 / 및 실패한 작업에서의 값진 교훈들이 영구적으로 남아있는 것입니다.

그리고 이것은 앞으로 새로 참여할 어느 기여자, 앞으로 시작할 어느 작업에서도 문서 증류를 통해 값진 자산으로 활용가능합니다.

또한 하이퍼워터폴 문서도 PR에 포함되어 github repository에 저장되므로 어느 환경에서나 조회할 수 있고, 활용가능합니다. (아래의 인용문 내용에서 언급된 문서는 로컬을 가르키지만, 결국 rhwp github repository의 같은 경로로 누구나 조회할 수 있습니다.)

실제 사례 소개

최근 작업에서 발견한 구체적인 예시를 소개드립니다.

"또한 로컬의 mydocs/plans/archives/task_44_architecture.md가 repaginate_from()과 stable-page 재사용을 이미 설계했지만, 이는 로컬 Task 44 문서입니다. GitHub #44는 셀 세로 정렬 이슈이므로 새 이슈에서 #44라고 참조하면 안 됩니다."

이 작업은 #2214 이슈 (#2214) 의 세션입니다.

Codex가 현재 작업 (#2214) 에서 발견한 한계점을 후속 이슈로 분리해 진행을 추천했습니다.

그 후, 중복 이슈가 있는지 확인하는 과정에서 로컬의 mydocs/plans/archives/task_44_architecture.md 문서를 통해 #44 이슈의 작업 맥락, 즉 해당 작업 당시 세션의 모든 핵심 맥락을 읽고 파악했습니다.

이는 단순히 "지침 문서를 통해 맥락을 전달한다" 등의 이미 널리 활용되는 AI 활용 문서화 방식과는 다릅니다.

#44 는 2026년 4월 3일에 완료된 이슈입니다.

심지어 mydocs/plans/archives/task_44_architecture.md 는 작성일이 2026월 2월 12일 입니다.

제가 기여자로 참여하기도, rhwp라는 프로젝트를 알게되기도 전에 이미 완료된 작업입니다.

그럼에도 @edwardkim(Maintainer) 님이 2026년 2월 12일에 고민한 흔적, 작업을 설계하신 방향, 해결 방법으로 결정한 사항등을 2026년 7월 12일에 마치 제 옆에 계셔서 같이 작업하는 것 처럼 생생히 알 수 있습니다.

2026년 2월 12일에 타이핑한 프롬프트들, 길고 긴 세션과 태운 토큰들, 고민한 시간들은 hyper-waterfall을 통해 증류되고 프로젝트의 영구 핵심 자산으로 남았습니다.

이것이 중요한 점은 앞으로의 가능성입니다.

rhwp는 아직 3개월 밖에 되지 않은 프로젝트입니다.

그럼에도 3.3k stars, 616 forks, 80k+ 누적 clones 등을 기록하였고, v0.7.18 릴리즈, npm weekly downloads 5k+ 및 38명의 기여자 참여로 폭발적으로 성장하고 있습니다.

앞으로 더욱 많은 기여자의 도전과 수많은 작업 시도가 있을 것이고, 성공과 실패와 상관없이 그 교훈들은 하이퍼워터폴 방법론에 의해 프로젝트의 영구 자산으로 문서화되어 남을 것 입니다.

---

하이퍼 워터폴은 rhwp의 메인테이너, @edwardkim 님이 최초로 제안하셨습니다.

Hyper-Waterfall: AI 시대의 소프트웨어 개발 방법론

rhwp는 하이퍼워터폴을 직접 적용해 "닫힌 포맷의 벽을 깨고, 모든 사람, 모든 AI, 모든 플랫폼에서 한글 문서를 자유롭게 읽고 쓸 수 있게 합니다."라는 엄청난 프로젝트를 가능하게 했습니다.

rhwp 그 자체가 증명된 훌륭한 실제 적용 사례이며, 운영관점에서도 장기적인 효용성을 입증했습니다.

하이퍼워터폴의 장점은 여기서 끝나지 않습니다.

문서가 외부화되어있다는 것은 어떤 기여자, 어떤 세션, 어떤 에이전트, 어떤 모델, 어떠한 환경에서도  같은 맥락을 이어서 작업할 수 있다는 것입니다.

뿐만 아니라, 작업 문서 포맷 자체가 OpenAI · Anthropic 공식 프롬프팅 가이드 핵심을 자연스럽게 만족합니다.

이것은 AI의 출력 (문서)를 다시 AI의 입력으로 활용하는 하이퍼워터폴의 자연스러운 재귀적인 과정에서 사용자가 프롬프트를 깊게 고민하지 않아도, 훌륭한 목적을 달성할 수 있습니다.

rhwp와 같은 방식으로 프로젝트를 개발하고 싶다면?

제가 rhwp collaborator로 활동하며, 최근 몇달간 폭발적으로 기여하는 과정에서 학습한 하이퍼워터폴을, rhwp에서 뜯어내어 모두가 사용가능하게, 모두가 자신의 프로젝트에 적용하게 만들었습니다.

https://github.com/postmelee/hyper-waterfall

이 외에도 제가 분리한 하이퍼워터폴에서는 기존 rhwp에 종속되어있던 하이퍼워터폴을 다른 저장소에도 쉽게 적용 가능하도록 몇가지 개선을 추가했습니다.

• 기존 rhwp에 특화된 도메인 특징적 내용을 제거하고, 적용 저장소에 맞게 설정하도록 분리
• 선명한 맥락과 토큰 효율성을 위해 지침문서 분산화 및 프롬프트 간소화
• 하이퍼워터폴 작업 관련 git 자동화 skill 추가 (pr-merge-cleanup / 이슈 및 pr 완료 처리 관리)

하이퍼워터폴이 어울리는 프로젝트는?

작업 분야, 도메인 특성, 프로젝트 성향에 따라 어울리는 도구가 있다고 생각합니다.

모든 상황에서 최고인 도구 - 지니의 요술램프 - 는 절대 없다고 생각합니다. 하이퍼워터폴 역시 그렇습니다. 각자 장단점이 있고 상황에 따라 가장 좋은 도구, 필요한 도구가 있다는 것은 분명합니다.

지금 하이퍼워터폴을 여러분의 프로젝트에 적용해보세요.

당장은 다른 비슷한 도구에 비해 엄청난 개선점을 느낄 수 없을 수도 있습니다.

하지만, 여러분의 프로젝트가 장기적으로 진행될, 큰 목적을 해결하려는 프로젝트라면, 그래서 오랜 시간의 고생길이 예정된다고 생각하신다면,
앞으로 긴 여정에 하이퍼워터폴이 복리의 마법처럼 분명히 프로젝트에 큰 기여를 할 것입니다.

AI 시대의 새로운 개발 방법론 - Hyperwatefall

하이퍼워터폴은 하네스, 루프 엔지니어링, 자동화 에이전트가 아닙니다.

이것은 방법론에 가깝습니다.

실제로 하이퍼워터폴을 저장소에 적용하면 추가되는 것은 지침문서 밖에 없습니다.

AI가 방법론을 적용해 생각할 수 있게 돕는 지침서 모음입니다.

https://github.com/postmelee/hyper-waterfall 은 단순히 그 지침서 설정을 도와주는 프로젝트일 뿐입니다.

---

긴 글 읽어주셔서 감사합니다! 질문이나 추가로 궁금한 점 모두 환영합니다!

비슷한 다른 프로젝트 소개도 환영합니다. 반영할 점 분석과 개선에 도움이 됩니다.