AI가 없던 시대에는 불가능했던 방법론. 워터폴의 규율과 애자일의 속도를 동시에.
Hyper-Waterfall은 AI 페어 프로그래머와 함께 소프트웨어를 만들 때 인간의 통제권, 추적 가능성, 엔지니어링 규율을 잃지 않도록 해주는 작업 프레임워크입니다.
본 방법론의 핵심 철학은 edwardkim/rhwp · hyper_waterfall.md에 가장 완성된 형태로 정리되어 있습니다. 본 저장소는 그 방법론을 다른 저장소에 손쉽게 적용할 수 있게 모듈화한 프레임워크입니다.
방법론을 먼저 이해하려면 아래 핵심 구조부터, 우리 저장소의 차별점만 보려면 이 저장소가 한 일로 점프하세요.
Part 1. 최초의 Hyper-Waterfall (rhwp)
Part 2. 이 저장소의 Hyper-Waterfall (postmelee/hyper-waterfall)
- 이 저장소가 한 일
- 왜 이 저장소를 써야 하는가
- 새 저장소에 빠르게 적용하기
- 도입 후 작업 흐름
- 적용 후 대상 저장소 구조
- 살아있는 예시 — 직접 따라가보기
- 설계 원칙
- 프롬프트 가이드 준수
거시 (프로젝트 수준) — 워터폴의 규율:
계획 ──→ 설계 ──→ 구현 ──→ 검증 ──→ 배포
│ │ │ │ │
▼ ▼ ▼ ▼ ▼
문서화 문서화 문서화 문서화 문서화
미시 (타스크 수준, 수 시간) — 애자일의 속도:
구현 → 테스트 → 피드백 → 수정 → 테스트 → ... (빠른 반복)
│ │ │ │ │
AI 자동화 사람 판단 AI 자동화
- 거시적 방향: 워터폴의 규율로 통제한다 — 계획서, 승인, 단계별 보고, 최종 검증.
- 미시적 실행: 애자일의 빠른 반복으로 수행한다 — AI와 즉각적인 피드백 루프를 돌린다 (전체 사이클이 몇 시간 안에 완료).
이 과정에서 모든 작업이 문서화되고, 모든 결정이 기록됩니다. → 이것이 Hyper-Waterfall을 가능하게 합니다.
사람은 절대 생각을 멈추지 않는다.
AI가 아무리 뛰어나도 방향을 결정하고 품질을 판단하는 것은 사람입니다. AI의 출력을 읽지 않고 수락하는 순간 Hyper-Waterfall은 바이브 코딩으로 전락합니다. 이 원칙을 운영 차원에서 풀어내면 다음 세 가지가 됩니다.
단계 전환, 계획 변경, 소스 수정에는 작업지시자의 명시 승인이 필요합니다. AI는 결정의 도구이지 결정자가 아닙니다. 게이트를 한 번이라도 건너뛰기 시작하면 방법론이 빠르게 무너집니다.
작업의 의도·범위·승인 기준을 매번 프롬프트에 처음부터 설명하지 않도록, 의도와 계획을 mydocs/에 박아둡니다. 모델은 같은 저장소를 읽으며 같은 컨텍스트 위에서 작업합니다. 맥락이 흩어진 상태로 작업을 시작하면 AI는 추측으로 빈 자리를 메우게 됩니다.
단계 보고서·최종 보고서·PR 본문에 의도·결정·검증 근거를 증류해 기록합니다. 채팅 컨텍스트는 사라지지만 저장소의 markdown은 남고, 새 세션·새 기여자가 합류해도 같은 출발점에서 시작할 수 있습니다.
사람은 생각하는 역할에 집중한다:
- 방향 설정: "다음에 뭘 해야 하는가?"
- 우선순위: "무엇이 더 중요한가?"
- 품질 판단: "이것이 충분히 좋은가?"
- 아키텍처 결정: "이 구조가 올바른가?"
- 도메인 지식: "한컴은 이 경우 어떻게 동작하는가?"
- 피드백: "이 부분이 잘못되었다, 왜냐하면..."
AI는 실행하는 역할에 집중한다:
- 분석: 코드베이스 탐색, 원인 추적
- 계획: 구현 계획서 작성
- 구현: 코드 작성, 테스트 생성
- 문서: 보고서, 기술 문서, 커밋 메시지
- 디버깅: 로그 분석, 수정안 제시
- 반복: 피드백 반영, 재시도
바이브 코딩 —
AI 출력을 읽지 않고 수락하고, AI에게 아키텍처 결정을 맡기고, 이해하지 못하는 코드를 배포하는 것— 은 함정입니다. 겉보기에는 동작하지만, 이해하지 못했기 때문에 문제가 생겨도 진단할 수 없는 코드가 만들어집니다.이 프로젝트는 정반대의 접근을 취합니다. 사람 작업지시자가 방향, 품질, 아키텍처 결정의 완전한 소유권을 유지하고, AI는 혼자서는 불가능한 속도와 규모로 구현을 수행합니다. 핵심 차이: 사람은 절대 생각을 멈추지 않습니다.
| 바이브 코딩 | Hyper-Waterfall | |
|---|---|---|
| 사람의 역할 | AI 출력 수락 | 지시, 검토, 결정 |
| 계획 | 없음 — "그냥 만들어" | 수행계획서 → 승인 → 구현계획서 → Stage 단위 실행 |
| 품질 관문 | 동작하길 바람 | 단계마다 검증 + 승인 게이트 + Open PR 리뷰 |
| 디버깅 | AI에게 AI 버그 수정 요청 | 사람이 진단, AI가 구현 |
| 아키텍처 | 우연히 형성 | 작업지시자가 의도적으로 설계 |
| 문서 | 없음 | mydocs/(계획서·단계 보고서·최종 보고서) + Issue/PR 본문 |
| 재현 가능성 | 불가능 | 전 과정 타임라인 추적 가능 |
| 결과물 | 취약, 유지보수 어려움 | 추적 가능, 인수인계 가능, 어디서든 재개 가능 |
거시적 워터폴과 미시적 애자일은 오랫동안 trade-off였습니다. 규율을 챙기면 느려졌고, 속도를 챙기면 규율이 빠졌습니다. AI 페어 프로그래머가 등장하면서 이 trade-off가 처음으로 깨졌습니다.
워터폴이 무거워진 큰 이유 중 하나는 사람이 모든 문서·계획·검증을 짊어졌기 때문입니다. AI가 이 초안을 빠르게 만들어주면서 워터폴이 잃어버린 속도와 애자일이 잃어버린 규율을 동시에 살릴 수 있게 되었습니다. 같은 규율, 100배 빠른 속도 — 이것이 AI 없이는 닿을 수 없던 지점입니다.
결정·근거·검증 결과가 모두 mydocs/와 PR/Issue에 남습니다. 한 명에게 몰린 컨텍스트가 사라져도 다음 사람·다음 AI 세션이 같은 출발점에서 시작합니다. 애자일의 약점인 bus-factor 문제가 구조적으로 해소됩니다.
사람이 방향·우선순위·아키텍처·품질을 끝까지 책임지고, AI는 탐색·구현·테스트·문서·반복을 맡습니다. 한 사람의 집중력으로는 닿을 수 없는 작업량이 한 사이클 안에 들어옵니다. AI는 배율기입니다 — 좋은 프로세스 위에 올리면 비범한 결과물이 됩니다.
rhwp의 메인테이너는 사무실, 집, 이동 중 — 3곳에서 각각 다른 클로드 세션으로 작업한다. 매번 새 세션은 이전의 기억이 없다.
하지만 문서가 있으면:
| "지금 뭘 해야 하지?" | → orders/20260409.md |
|---|---|
| "어디까지 했지?" | → working/task_m100_86_stage1.md |
| "어떻게 하기로 했지?" | → plans/task_m100_86_impl.md |
| "왜 이 방식으로 하지?" | → feedback/ + tech/ |
| "이 함정은 뭐지?" | → troubleshootings/ |
작업지시자가 컨텍스트 전달에 소비하는 시간이 거의 0이다. 이것이 3곳을 이동하며 연속 작업이 가능한 이유이고, 컨트리뷰터가 합류했을 때도 동일하게 작동하는 이유이다.
이 저장소는 rhwp에서 처음 도입된 '하이퍼-워터폴' 방법론을 참고하여 다음과 같이 확장했습니다.
원본 방법론(rhwp)은 그 저장소의 문서·관습과 강하게 결합되어 있어, 다른 프로젝트에 그대로 가져다 쓰기 어려웠습니다. 본 저장소는 운영 규칙·매뉴얼·SKILL을 templates/로 분리하고 진입 절차를 docs/agent-entrypoint.md로 정형화했습니다. 결과적으로 AI 코딩 도구에 한 줄 프롬프트만 보내면 어떤 저장소에든 적용됩니다. AI가 진입 절차를 따라 REPO_SLUG·BASE_BRANCH 같은 placeholder까지 자동으로 치환합니다. 본 저장소 자체가 자기 자신에 적용한 dogfooding 첫 사례입니다 (Issue #1, PR #2).
작업 문서 포맷이 OpenAI와 Anthropic의 공식 프롬프팅 가이드 핵심을 자연스럽게 만족하도록 설계했습니다.
AI가 문서를 작성하고 다시 참조 및 레퍼런스로 사용하는 재귀적 과정에서 응답 품질 저하를 최소화할 수 있습니다.
- 명확성(Clarity): 작업 목표가 명확하게 정의됨
- 일관성(Consistency): 모든 작업 문서가 동일한 구조를 가짐
- 단계적 접근(Step-by-step thinking): 작업을 작은 단계로 분할하여 진행
- 맥락 제공(Context): 작업에 필요한 모든 정보가 문서에 포함됨
- 출력 포맷 제약(Output format): 작업 결과물이 특정 포맷으로 출력됨
상세 매핑은 아래 프롬프트 가이드 준수 섹션에서 펼쳐 확인할 수 있습니다.
rhwp는 CLAUDE.md 한 파일에 운영 규칙·문서 구조·폴더 정책·명명 규칙·PR 처리를 모두 인라인했고, AGENTS.md가 없어 Claude Code 전용으로 동작했습니다. 본 저장소는 두 축으로 분리·확장했습니다.
(1) Multi-agent 호환: AGENTS.md를 단일 진실 원천으로 두고 CLAUDE.md는 @AGENTS.md 한 줄로 참조합니다. SKILL은 .agents/skills(Codex) + .claude/skills(Claude Code) 심볼릭 링크로 같은 본문이 양쪽 도구에서 인식됩니다. 새로 추가되는 SKILL 인식 도구도 같은 패턴으로 확장됩니다.
(2) 운영 규칙·SKILL·매뉴얼 분리: AGENTS.md에는 매 턴 시스템 프롬프트로 적재될 정책·제약·인덱스만 두고, 절차 상세는 mydocs/manual/의 5개 매뉴얼(문서 구조, 타스크 진행, Git, PR, 충돌 규칙)과 mydocs/skills/의 7개 SKILL로 분리했습니다.
효과:
- 토큰 효율: 매 턴 시스템 프롬프트로 적재되는 분량을 축소. 매뉴얼·SKILL 본문은 호출 시점에만 컨텍스트로 들어옵니다.
- 컨텍스트 효율: 모델은 필요한 시점에 필요한 절차만 읽습니다. 무관한 절차로 컨텍스트가 오염되지 않습니다.
- 의도 전달 명확성: 단계별 SKILL이 절차의 어느 시점에 호출되는지 명시되어, AI가 추론으로 절차를 재구성하지 않습니다.
- 모델 간 이식성: SKILL은 표준 형식이라 다른 SKILL 인식 도구로 옮기기 쉽습니다.
AI는 두 가지 구조적 약점을 가집니다.
- 세션이 길어지거나 도구가 바뀌면 맥락을 잃습니다.
- 방향이 틀렸는데도 자신 있게 계속 실행할 수 있습니다.
본 저장소는 이 약점을 작업 제약으로 바꾸고, 다음 세 축에서 사용자가 즉시 체감할 수 있는 이점을 만들어냅니다.
- 작업의 의도, 계획, 단계별 검증 결과, 의사결정 근거가 모두
mydocs/안의 markdown 파일로 쌓입니다. 단순 기록이 아니라 다음 작업의 input — 모델이 새 task를 시작할 때 같은 저장소에 있는 과거 계획서·보고서·결정 기록을 읽고 그 위에서 작업합니다. 잘 쓴 문서가 곧 좋은 프롬프트가 되고, 잘 쓴 프롬프트가 곧 다음 좋은 문서를 만드는 선순환이 일어납니다. - 작업을 이어갈 때도 채팅 히스토리에 의존하지 않고 저장소 산출물만으로 맥락을 복원할 수 있습니다. 새 기여자나 새 AI 세션이 합류해도 같은 출발점에서 시작할 수 있습니다.
이는 옵시디언 vault를 LLM에 연결해 개인 지식 저장소를 컨텍스트로 쓰는 흐름과 같은 구조입니다. 차이는 vault의 성격에 있습니다. 옵시디언이 일반 지식·아이디어를 모은다면,
mydocs/는 작업 이력에 특화된 vault로서 의도·계획·검증·산출물·트러블슈팅을 작업 단위로 자동 누적합니다. 절차가 강제하기 때문에 누락이 없고 일관됩니다.
- 작업은
이슈 → 브랜치 → 수행계획서 → 구현계획서 → Stage 단위 구현·검증·보고 → 최종 보고서 → Open PR순서를 따르며, 각 게이트에서 작업지시자 승인을 받습니다. - 큰 구현이 끝난 뒤에 "방향이 틀렸음"을 깨닫는 대신, 수행계획서·구현계획서·각 Stage 경계에서 일찍 잡히므로 매몰 비용이 작습니다.
- 단계 검증이 실패하면 그 단계 안에서 회복하고, scope가 바뀌면 계획서를 갱신해 재승인을 받습니다.
- 작업지시자는 방향, 우선순위, 아키텍처, 품질 결정의 책임을 끝까지 가지고, AI는 탐색·초안 작성·구현·테스트·보고서 작성·PR 본문 작성 같은 고반복 작업을 맡습니다. 모든 단계 전환은 작업지시자의 명시 승인이 필요합니다.
- 본 저장소는 이 분담을 운영 차원에서 자동화합니다. task 관리 규칙을 SKILL로 분리해 AI가 단계별로 무엇을 해야 하는지·어떤 산출물을 남겨야 하는지·언제 멈추고 사람에게 넘겨야 하는지를 자연스럽게 준수합니다.
- 작업 문서 포맷 자체가 OpenAI·Anthropic 공식 프롬프팅 가이드 핵심을 자연스럽게 만족합니다. 사용자가 프롬프트 엔지니어링을 따로 공부하지 않아도, AI는 일관된 형식·명확한 맥락·단계별 사고·정해진 출력 형식 안에서 작업합니다.
이 세 축은 OpenAI와 Anthropic의 공식 프롬프팅 가이드의 핵심을 개발 프로세스 차원에서 구현한 결과이기도 합니다. 항목별 매핑은 아래 프롬프트 가이드 준수 섹션에서 펼쳐 확인할 수 있습니다.
AI 코딩 도구에 다음 한 줄을 보내주세요.
https://github.com/postmelee/hyper-waterfall 의 하이퍼-워터폴 방법론을 이 저장소에 적용해줘.
AI는 docs/agent-entrypoint.md부터 읽어 적용 절차를 따릅니다. 소스 변경 전 반드시 작업지시자 승인을 받게 되어 있습니다.
도입 후에는 AI가 알아서 Hyper-Waterfall 방식을 지키며 작업을 진행합니다. 처음 시작하는 사용자는 AI에게 "이거 구현해줘"와 같은 자연어 명령을 내리기만 하면 됩니다.
Hyper-Waterfall은 타스크 단위로 작업을 진행합니다.
모든 타스크는 아래 절차를 엄격하게 따릅니다.
1. GitHub Issue 등록
2. 오늘할일(orders/) 기록
3. 타스크 브랜치 생성 (local/task{번호})
4. 수행계획서 작성 → [작업지시자 승인]
5. 구현계획서 작성 → [작업지시자 승인]
6. 단계별 구현
7. 단계별 완료보고서 → [작업지시자 승인]
8. (다음 단계 반복)
9. 최종 결과보고서 → [작업지시자 승인]
10. 오늘할일 상태 갱신
각
[승인]지점이 품질 게이트입니다. 코드 리뷰만으로는 잡을 수 없는 방향성 오류를 문서 리뷰에서 잡는다.
각 단계 전환에는 작업지시자의 명시 승인이 필요합니다.
1. 타스크 등록 → `task-register`
└─ 작업지시자: GitHub Issue 생성, 범위 정의
2. 수행 계획서 → `task-start`
└─ AI: 계획서 작성 (최소 3단계, 최대 6단계)
└─ 작업지시자: 검토 → 승인 또는 수정 요청
3. 단계별 구현 → `task-stage-report`(단계 수만큼 반복)
└─ AI: 코드 작성 + 테스트
└─ AI: 단계 완료 보고서 작성
└─ 작업지시자: 검증 → 승인 또는 피드백
4. 피드백 반영 → (수동)
└─ 작업지시자: 피드백 문서 작성 (mydocs/feedback/), AI가 반영. scope가 바뀌면 계획서를 갱신해 재승인
└─ AI: 피드백 반영, 수정
5. 최종 보고 + Open PR → `task-final-report`
└─ AI: 최종 결과 보고서 작성, Open PR 생성
└─ 작업지시자: 검증 → 승인 또는 피드백
6. PR 리뷰 + merge + 정리 → `pr-merge-cleanup`
└─ 작업지시자: PR 검토 → 승인 또는 피드백
└─ AI: 리뷰·merge 후 이슈 close, 브랜치/오늘할일 정리
todo는 위 흐름 어느 단계에서든 오늘할일 보드를 갱신할 때 호출합니다. external-pr-review는 외부 기여자 PR 검토용 별도 흐름입니다.
매 타스크가 만들어내는 산출물:
mydocs/
├── orders/yyyymmdd.md ← 오늘 할일 (타스크 목록 + 상태)
├── plans/task_{N}.md ← 수행 계획서
├── plans/task_{N}_impl.md ← 구현 계획서
├── working/task_{N}_step{M}.md ← 단계별 완료 보고서
├── working/task_{N}_final.md ← 최종 결과 보고서
└── feedback/ ← 코드 리뷰 피드백
| SKILL | 사용하는 시점 | 주요 산출물 |
|---|---|---|
task-register |
신규 작업이라 GitHub Issue를 먼저 만들어야 할 때 | 범위·라벨·마일스톤·담당자가 채워진 GitHub Issue |
task-start |
승인된 이슈 작업을 시작할 때 | local/task{N} 브랜치, 오늘할일 행, 수행계획서 템플릿 |
task-stage-report |
한 Stage 구현이 끝나고 다음 단계로 넘어가기 직전 | 단계 보고서, 단계 묶음 커밋, 단계 검증 결과 |
task-final-report |
모든 Stage가 끝나고 PR을 게시하기 직전 | 최종 보고서, 오늘할일 완료 처리, Open PR |
pr-merge-cleanup |
PR이 실제로 merge된 직후 | 이슈 close, publish/task{N} 원격 삭제, 로컬 브랜치/worktree 정리 |
external-pr-review |
외부 기여자 PR을 검토할 때 | mydocs/pr/ 검토 문서, 검증 결과, 권고(merge/수정/닫기) |
todo |
오늘할일 보드를 새로 만들거나 갱신할 때 | mydocs/orders/yyyymmdd.md 표 형식 갱신 |
진실 원천은 templates/mydocs/skills/이고 적용 저장소에서는 .agents/skills와 .claude/skills 심볼릭 링크가 같은 본문을 가리킵니다.
templates/를 복사하고 placeholder를 치환한 뒤 사용자 저장소에 만들어지는 모습입니다.
your-repo/
├── AGENTS.md 운영 규칙 단일 진실 원천
├── CLAUDE.md Claude Code용 (AGENTS.md 참조)
├── .github/
│ └── pull_request_template.md
├── .agents/
│ └── skills -> ../mydocs/skills Codex 인식 경로 (심볼릭 링크)
├── .claude/
│ └── skills -> ../mydocs/skills Claude Code 인식 경로 (심볼릭 링크)
└── mydocs/
├── manual/ 매뉴얼 (문서 구조, 타스크 진행, Git, PR, 충돌 규칙)
├── skills/ SKILL 진실 원천 (Codex/Claude Code 공용)
├── orders/ 오늘할일 (yyyymmdd.md)
├── plans/ 수행/구현 계획서
│ └── archives/
├── working/ 단계별 완료 보고서
├── report/ 최종 결과 보고서
├── feedback/ 피드백·리뷰 의견
├── tech/ 기술 조사
├── troubleshootings/ 트러블슈팅
└── pr/ 외부 PR 검토 기록
└── archives/
이 저장소 자체가 하이퍼-워터폴을 자기 자신에게 적용한 첫 사례입니다. 적용 여부를 검토하기 전에 실제 운영이 어떻게 돌아가는지 보고 싶다면 다음 순서로 둘러보세요.
- 이슈
#1하이퍼-워터폴 자기 적용 (dogfooding) — 라벨 3개, 마일스톤 M010, linked PR이 자동 표시되는 깔끔한 구조 (상태 알림 댓글 없음) - Pull Request
#2— Open PR 본문 형식: 요약 4 bullet (대상 타스크/왜/무엇/리뷰 포인트), Stage 5개 timeline 이중 링크(단계 보고서 + commit URL), 영향 영역 표, 작업 문서, 검증 명령 - 수행계획서
mydocs/plans/task_m010_1.md— 목적·배경·범위·설계 방향·예상 변경 파일·잠정 단계·검증 계획·리스크 - 구현계획서 5단계
mydocs/plans/task_m010_1_impl.md— 단계별 산출물·검증 명령·커밋 메시지를 사전에 확정 - 단계 보고서 5개
mydocs/working/— 각 Stage 종료 시 산출물·검증 결과·잔여 위험·다음 단계 영향 - 최종 보고서
mydocs/report/task_m010_1_report.md— 5단계 종합, 변경 전·후 정량 비교, 수용 기준 검증 - 오늘할일
mydocs/orders/— 일일 보드 형식 (마일스톤별 표 + 완료 시각) - commit log
git log(main) —Task #1: 수행 계획서 작성부터pr-merge-cleanup까지 12개 task 커밋이 시간 순서로 보존
이 첫 task는 scope 확장 두 번을 거치며 5단계로 진행됐습니다. 즉 README에 적힌 절차가 실제 어떻게 돌아가는지 — 승인 게이트, 단계 보고, scope 변경 처리, PR 본문 재작성, merge 후 정리까지 — 모두 살아있는 산출물로 따라갈 수 있습니다.
- 의미 있는 소스 변경에는 인간 승인 게이트가 필요합니다.
- 이슈 진행 추적은 GitHub의 linked PR 자동 cross-reference와 라벨/마일스톤에 위임하고, 댓글은 토론·블로커·결정 기록 용도로만 둡니다.
- 최신 상태는 이슈 metadata, 현재 branch 또는 PR,
mydocs/에서 찾을 수 있어야 합니다. - 이 프레임워크는 다양한 프로젝트 유형에서 동작해야 합니다. 특정 언어, 빌드, 배포, 제품 규칙은 core가 아니라 대상 저장소의 템플릿과 설정에 둡니다.
- 프로세스에는 엄격하고, 도구에는 유연해야 합니다.
Hyper-Waterfall은 새로운 마법이 아니라, 워터폴의 규율과 애자일의 속도를 AI라는 배율기 위에서 동시에 살리는 운영 방식입니다. 좋은 프로세스 위에서 AI는 비범한 결과물을 만들어냅니다.
Hyper-Waterfall은 OpenAI와 Anthropic의 공식 프롬프팅 가이드의 핵심을 개발 프로세스 차원에서 구현합니다. "프롬프트를 잘 쓰는 법"이 아니라 프롬프트가 잘 써질 수밖에 없는 저장소 구조를 만드는 접근입니다.
OpenAI GPT-5.5 프롬프팅 가이드 매핑 · 출처: OpenAI prompt guidance
-
결과물을 먼저 정한다. Hyper-Waterfall은 작업 시작부터 Issue, 수행계획서, 구현계획서, Stage 보고서, 최종 보고서, PR이라는 산출물을 명확히 둡니다. AI에게 "잘 해줘"라고 맡기는 게 아니라, 무엇을 남겨야 하는지 먼저 고정합니다.
-
좋은 답변의 기준을 적는다. 각 Stage는 구현뿐 아니라 검증 기준과 리뷰 포인트를 함께 남깁니다. 그래서 AI의 결과물은 감으로 평가되지 않고, 문서화된 기준 위에서 판단됩니다.
-
제약 조건을 짧게 건다. Hyper-Waterfall은 "승인 없이 다음 단계 진행 금지", "소스 수정 전 승인", "Issue 기준 추적"처럼 AI가 넘지 말아야 할 경계를 명시합니다. 자유도를 없애는 게 아니라, 폭주하지 않게 레일을 까는 방식입니다.
-
필요한 근거 수준을 말한다. 구현 결과는 Stage 보고서, 검증 로그, PR 본문으로 증류됩니다. 단순히 코드가 바뀐 것이 아니라, 왜 바뀌었고 어떻게 확인했는지가 저장소에 남습니다.
-
출력 형식을 정한다.
mydocs/는 계획서, 작업 보고서, 최종 보고서, 피드백, 기술 조사 문서를 정해진 위치와 형식으로 저장합니다. AI의 답변이 흩어지는 대신, 다음 작업자가 다시 읽을 수 있는 구조가 됩니다. -
언제 멈출지도 알려준다. Hyper-Waterfall은 Stage 경계마다 멈추고 사람의 승인을 기다립니다. AI가 끝까지 달리는 것이 아니라, 사람이 방향을 확인할 수 있는 정지선을 둡니다.
Anthropic Claude Opus 4.7 프롬프팅 가이드 매핑 · 출처: Claude prompting best practices
-
명확하고 직접적인 지시. 작업의 의도를 Issue, 수행계획서, 구현계획서로 단계마다 명시화합니다. 모호한 의도를 모델에 던지는 대신, 무엇을 만들지·왜 만드는지·어디까지 만들지를 게이트 전에 고정합니다.
-
워크플로우와 목표 맥락 제공. 작업이 어떤 흐름의 일부인지, 어떤 결과물의 어디에 들어가는지를 매번 프롬프트에 적게 하지 않습니다.
mydocs/, Issue, PR 본문에 그 맥락이 박혀 있어 모델이 자연스럽게 같은 컨텍스트를 읽습니다. -
순차적 단계 제시. Stage 단위 진행과 단계마다의 승인 게이트가 Anthropic이 권장하는 "지시를 순차적 단계로 쪼개기"를 그대로 구현합니다.
-
출력 형식 통제. 계획서·단계 보고서·최종 보고서·PR 본문은 모두 정해진 위치와 템플릿이 있습니다. 모델이 "어디에 무엇을 적을지"를 매 작업마다 발명하지 않게 합니다.
-
장기 작업과 외부 기억. Opus 4.7이 강한 long-horizon agentic work와 memory task에
mydocs/가 그대로 대응합니다. 채팅 컨텍스트가 사라져도 파일시스템에 작업 기억이 증류되어 남습니다. -
Literal 지시 따름과 정합. Opus 4.7은 명시된 범위에 더 정확히 묶이는 경향이 있습니다. Hyper-Waterfall은 "소스 수정 전 승인", "승인 없이 다음 Stage 진행 금지", "Issue 기준 추적" 같은 경계를 애초에 문서화하므로 literal한 모델일수록 잘 작동합니다.
단, Hyper-Waterfall은 "최대 자율성"보다 "인간 통제권과 추적 가능성"을 우선합니다. Opus 4.7 가이드가 권장하는 "interactive coding에서 첫 턴에 의도와 제약을 명확히 주고 반복 상호작용을 줄이라"는 권고와 같은 layer가 아니라, 한 단계 위 — task 전체 관점의 게이트 — 에서 작동합니다. XML 태그 구조화는 직접 채택하지 않으며,
mydocs/폴더 구조와 파일명 규칙이 같은 역할을 수행합니다.
한 줄 요약: Hyper-Waterfall은 Claude Opus 4.7 프롬프팅 가이드의 핵심을 단순한 프롬프트 문장이 아니라, GitHub-native 개발 프로세스로 끌어내린 하네스입니다.
MIT. 자세한 내용은 LICENSE를 참고하세요.