AI 코딩의 휘발성 맥락을 프로젝트 기억으로 바꾸는 법 — rhwp Hyper-Waterfall 실전 해부

AI 코딩 도구가 매일 새 모델로 교체되고 컨텍스트 윈도우가 커지는데도, 실제 사내 코드베이스에서 LLM 협업이 기대만큼 성과를 내지 못하는 현상이 반복된다. GeekNews에 공유된 글은 이 실패의 원인을 모델 성능이 아닌 휘발성 맥락(volatile context)에서 찾고, rhwp가 제안하는 Hyper-Waterfall 방식의 외부화 절차를 실전 사례로 풀어낸다. 본문은 그 관점과 절차를 한국 개발팀이 바로 옮겨올 수 있도록 단계별로 번역한다.

AI 코딩이 기존 프로젝트에서 무너지는 이유: 휘발성 맥락 문제

흔히 LLM 코딩이 실패한다고 말할 때 우리는 모델의 추론 능력 부족을 떠올린다. 그러나 원문 작성자는 실제 협업 현장을 3개월간 지켜본 결과, 원인이 다른 곳에 있다고 진단한다. 핵심은 모델의 추론 능력이 아니라, 그 코드가 속한 프로젝트의 누적된 맥락이다.

바이브 코딩과 프로덕션 협업의 결정적 차이

바이브 코딩(vibe coding)은 짧은 데모나 신규 프로토타입에서는 매끄럽게 작동한다. 대화 세션 안에서 모델은 즉각적인 피드백을 받고 결과를 다듬는다. 반면, 6개월 이상 누적된 회사 코드베이스는 다르다. 도메인 규칙, 예외 처리 관행, 기존 API의 숨은 가정, 배포 파이프라인의 암묵지 등이 코드 곳곳에 스며 들어 있다. 이러한 맥락은 새 세션이 열릴 때마다 사실상 0에서 다시 주입받아야 하는 휘발성 정보다.

모델 성능 부족 신화에 대한 재해석

원문은 모델 자체의 한계보다 맥락 전달 실패가 더 큰 병목이라는 해석을 제시한다. 같은 모델이라도 충분한 배경 지식이 함께 주입되면식이 주어지면 만족스러운 결과를 내고, 부족하면 hallucination이 늘어난다. 즉 AI 코딩 협업의 품질은 모델이 아니라 외부화된 기억의 두께에 비례한다는 관점이 도출된다.

rhwp의 Hyper-Waterfall: 작업 기억을 프로젝트 기억으로 전환하는 흐름

rhwp는 AI 협업에서 누락되는 기억을 두 축으로 외부화한다. 하나는 프로젝트 전반에 걸친 장기 지식이고, 다른 하나는 개별 작업 단위의 상세 기록이다. 이 이원 구조가 Hyper-Waterfall이라는 이름의 절차로 묶인다.

거시 외부화: mydocs/manual과 mydocs/tech의 역할

거시 외부화는 코드베이스와 함께 살아 있는 지식 문서를 말한다. 원문에서 명시한 mydocs/manual은 제품 요구사항, 도메인 용어, 사용자 시나리오 같은 사람 중심 매뉴얼 영역이고, mydocs/tech는 아키텍처 결정 기록, 모듈 의존성, 빌드·배포 절차 같은 기술 중심 영역이다. 이 두 폴더는 모든 협업 세션이 열리기 전에 모델이 우선적으로 읽도록 가리키는 앵커 문서 역할을 한다.

미시 외부화: 계획서 → 단계별 보고서 → 최종 보고서의 순환 구조

미시 외부화는 단위 작업 단위로 만들어지는 산출물 묶음이다. 흐름은 다음과 같이 세 단계로 순환한다.

• 구현·수행 계획서: 작업의 목표, 가정, 변경 범위, 수용 기준을 사전에 적어 모델과 사람이 같은 그림을 공유한다.
• 단계별 보고서: 작업 도중의 시도, 실패, 부분 성공을 짧은 단위로 기록해 다음 세션이 이전 세션의 추론을 이어받을 수 있게 한다.
• 최종 보고서: 결과물, 검증 방법, 남은 리스크를 정리해 코드 변경과 함께 보존한다.

이 세 문서가 한 묶음으로 git 커밋과 함께 쌓이면, 휘발되던 세션 기억이 영구적인 프로젝트 기억으로 변환된다.

3개월 적용 사례로 본 효과와 마찰점

원문 작성자는 rhwp collaborator로 3개월간 기여하면서 이 절차가 실제 협업에 미친 영향을 정리했다. 다만 원문이 정성적 서술에 머물렀기 때문에 아래에 정리된 효과는 검증된 사실이 아닌, 3개월 적용 후 작성자가 체감한 경향으로 읽어야 한다.

AI 응답 일관성과 재현성이 개선된 지점

원문 작성자에 따르면, mydocs 폴더를 매 세션 시작 시 컨텍스트로 주입하자 모델이 기존 모듈의 명명 규칙과 예외 처리 스타일을 무시하는 빈도가 줄었다고 관찰된다. 단계별 보고서를 누적하면서는, 이전에 실패한 접근을 다시 시도하는 비효율이 감소한 것으로 보인다. 결과적으로 새 세션이 과거 세션의 결정 경로를 추적할 수 있게 되면서 일관성이 개선된 것으로 분석된다.

팀원 간 리뷰 비용과 신규 온보딩 변화

사람 협업 측면에서는 코드 리뷰 시 변경 의도를 묻는 왕복이 줄고, 최종 보고서가 PR 설명란을 대체하는 경향이 생긴다. 신규 합류자에게는 mydocs/manual과 mydocs/tech가 입문 가이드를 대체하는 효과를 주어, 첫 PR까지 걸리는 시간이 단축될 여지가 생긴다. 다만 보고서 작성 자체가 추가 비용이므로, 팀의 문서화 성숙도에 따라 체감 효과가 달라질 것으로 보인다.

도입 체크리스트: 저장소 구조와 문서 템플릿

관찰 결과를 패턴으로 추출해 일반 팀이 그대로 가져다 쓸 수 있는 형태로 정리하면 다음과 같다.

GitHub 저장소(github.com/edwardkim) 기반 디렉터리 설계

원문은 github.com/edwardkim 저장소를 통해 구체적인 폴더와 템플릿을 공개했다. 이를 참고한 표준 디렉터리 골격은 다음과 같다.

경로	담당 영역	갱신 주기	주 소비 주체
mydocs/manual	제품 요구사항, 도메인 용어, 사용자 시나리오	주 1회 또는 주요 릴리즈 시	AI 세션, PM, 신규 합류자
mydocs/tech	아키텍처 결정, 모듈 의존성, 빌드·배포 절차	주요 설계 변경 시	AI 세션, 백엔드 엔지니어
tasks/<작업ID>/plan.md	구현·수행 계획서	작업 시작 시	작업 담당자, 리뷰어
tasks/<작업ID>/reports/*.md	단계별 보고서	세션 단위	다음 세션 담당자
tasks/<작업ID>/final.md	최종 보고서	작업 종료 시	리뷰어, 코드베이스 사용자

이 구조에서 핵심은 tasks 디렉터리가 git 히스토리와 함께 자라난다는 점이다. 작업이 끝나도 보고서는 삭제되지 않고 남으며, 비슷한 변경이 필요할 때 재진입점이 된다.

기존 워크플로우와 병행하는 단계적 전환 전략

도입을 한꺼번에 전사적으로 적용하면 저항이 크다. 단계적 전환 전략은 다음 순서를 권장한다.

• 1단계: 거시 앵커 구축 — mydocs/manual, mydocs/tech 두 폴더를 기존 사내 위키에서 1차 백필하고 AI 세션 기본 컨텍스트로 지정한다.
• 2단계: 미시 산출물 파일럿 — 한 개 팀 또는 한 개 제품 영역에서 작업 단위 보고서를 4주간 시범 적용한다.
• 3단계: PR 템플릿 통합 — 최종 보고서를 PR 설명란과 연결하고, 리뷰 체크리스트에 보고서 첨부 여부를 추가한다.
• 4단계: 자동화 후보 식별 — 단계별 보고서 누락 알림, plan.md 템플릿 검사 같은 lint성 자동화 도입 여부를 검토한다.

한계와 향후 과제: 자동화 가능 범위와 인간 판단의 경계

rhwp의 외부화 절차는 강력하지만 만능은 아니다. 먼저, 보고서 작성이 습관화되지 않으면 형식만 남고 실질이 비는 역효과가 발생할 수 있다. 둘째, mydocs가 노후화되면 모델이 잘못된 앵커를 학습해 오히려 일관성이 깨질 수 있다. 셋째, 고객 정보나 보안 규칙이 섞인 문서는 컨텍스트 주입 시 별도의 마스킹 절차가 필요하다. 이러한 영역은 자동화보다 사람의 명시적 판단이 우선해야 하는 경계로 남는다.

향후 과제로는 보고서 누락 감지, plan.md와 코드 diff의 정합성 검사, 그리고 mydocs 변경 이력의 요약 자동 생성과 같은 자동화 후보가 거론된다. 다만 자동화 범위를 넓히는 속도보다 문서 문화가 안정화되는 속도를 우선해야 함이 3개월 적용의 교훈으로 보인다.

참고 자료: GeekNews 토픽, GitHub 저장소

#rhwp #HyperWaterfall #AI코딩 #프로젝트맥락 #mydocs #바이브코딩 #외부화 #단계별보고서 #github_edwardkim #GeekNews #AI협업방법론 #맥락기억 #코드베이스온보딩 #LLM워크플로우