- 이슈: #1 하이퍼-워터폴 자기 적용 (dogfooding)
- 마일스톤: M010
- 브랜치:
local/task1→publish/task1 - 단계 수: 5 (Stage 4·5는 2026-05-02 scope 확장으로 추가)
- 참여 SKILL:
task-register→task-start→task-stage-report×5 →task-final-report(그리고 매 단계issue-checkpoint)
본 저장소(postmelee/hyper-waterfall)에 자기 자신이 정의한 하이퍼-워터폴 방법론을 적용해 dogfooding 사례를 만들고, 이어서 postmelee/alhangeul-macos#115의 PR 규칙 강화(Stage 4)와 본 저장소 자체 디자인 결정으로 PR 변경 내역 섹션 구조 개선(Stage 5)을 같은 task에 흡수했다. 이후 사용자가 이 저장소를 참고할 때 issue → branch → 계획서 → 단계 보고서 → 최종 보고서 → Open PR 흐름이 모두 살아있는 예시로 노출된다.
| 경로 | 역할 |
|---|---|
AGENTS.md |
코딩 에이전트 운영 규칙 (placeholder 4개 치환) |
CLAUDE.md |
Claude Code용 진입 (@AGENTS.md) |
.github/pull_request_template.md |
PR 본문 템플릿. Stage 1 시점에 옛 형식으로 생성된 뒤 Stage 4에서 새 형식으로 재작성 |
자체 폴더 7개: mydocs/{plans/archives, report, feedback, tech, troubleshootings, pr, pr/archives} (.gitkeep)
심볼릭 링크 4개:
| 링크 | 대상 |
|---|---|
.agents/skills |
../mydocs/skills |
.claude/skills |
../mydocs/skills |
mydocs/manual |
../templates/mydocs/manual |
mydocs/skills |
../templates/mydocs/skills |
README.md
- Stage 3: "저장소 구조" 섹션을 두 관점(적용 후 대상 저장소 / 본 저장소 자기 적용 후)으로 재작성
- Stage 4: "도입 후 작업 흐름" 표 5번, "핵심 SKILL" 표
task-final-report행에서 "draft PR" → "Open PR" 보정
templates 갱신 5개:
templates/.github/pull_request_template.md: 8개 섹션 새 구조 (요약 4 bullet, 변경 내역 Stage·commit 이중 링크 + 영역 표 + 작업 문서, 핵심 리뷰 포인트, 검증, 스크린샷 Before/After, 관련 이슈 맥락 의미, 후속 이슈 제안, 남은 리스크).Closes #폐지templates/mydocs/skills/task-final-report/SKILL.md: draft → Open PR 기본,--body-file우선templates/mydocs/manual/pr_process_guide.md: 섹션 구성 갱신, 대상 타스크 vs 관련 이슈 의미 분리templates/mydocs/manual/git_workflow_guide.md: Open PR 정의·명령templates/mydocs/manual/task_workflow_guide.md: 11번 항목 Open PR
자기 적용본 갱신 2개 (templates와 동기):
.github/pull_request_template.md: 새 본문으로 재생성 ({REPO_SLUG}→postmelee/hyper-waterfall치환)README.md: 위에 명시
AGENTS.md는 본문에 draft 표현 잔존 없음 확인 (변경 없음).
PR 변경 내역 섹션 본문을 Stage timeline만 두고, 표·작업 문서를 하위 목차로 분리해 가독성을 개선:
templates/.github/pull_request_template.md:### 영향 영역(옵션) +### 작업 문서하위 섹션 도입. 영향 영역은 영역 1~2개일 땐 통째 삭제 가능.github/pull_request_template.md(자기 적용본): 동일 구조templates/mydocs/manual/pr_process_guide.md: "섹션 구성"에 하위 섹션 트리 추가, "섹션별 작성 기준"을 변경 내역/영향 영역/작업 문서로 분할, "작성 예시"도 새 구조 반영
upstream 참조 없는 본 저장소 자체 디자인 결정으로, 대형 저장소(kubernetes/rust/llvm) 패턴(영역 정보는 라벨/commit prefix로 위임, 표는 본문에 거의 두지 않음)을 참고했다.
- 수행계획서:
mydocs/plans/task_m010_1.md(scope 확장 시 갱신) - 구현계획서:
mydocs/plans/task_m010_1_impl.md(Stage 4 추가) - 단계 보고서 5개:
mydocs/working/task_m010_1_stage{1,2,3,4,5}.md - 최종 보고서:
mydocs/report/task_m010_1_report.md(이 문서) - 오늘할일:
mydocs/orders/20260501.md,mydocs/orders/20260502.md
- 본 저장소를 클론한 코딩 에이전트는 자동으로
AGENTS.md+CLAUDE.md+.agents/skills+.claude/skills를 인식한다. mydocs/manual,mydocs/skills가templates/mydocs/로 가는 심볼릭 링크라 매뉴얼·SKILL 변경 시 한 곳만 고치면 된다.- README의 저장소 구조가 사용자 적용 결과를 명시해, 적용 의사 결정에 필요한 예측 가능성이 높아졌다.
- 새 PR 템플릿·매뉴얼·SKILL을 통해 본 저장소를 그대로 따라가도 PR #115 수준의 PR 운영(요약 4 bullet, Stage 이중 링크, Open PR 기본)을 할 수 있다.
- 외부 저장소에 본 프레임워크를 적용할 때의 진입 절차(
docs/agent-entrypoint.md)는 그대로 유효하다.
| 지표 | 적용 전 | 적용 후 |
|---|---|---|
루트 운영 파일 (AGENTS.md 등) |
0 | 3 |
루트 심볼릭 링크 (.agents, .claude) |
0 | 2 |
mydocs/ 자체 폴더 |
0 | 9 |
mydocs/ 심볼릭 링크 |
0 | 2 (manual, skills) |
| 첫 task 커밋 수 | — | 11 (수행계획 1 + 구현계획 1 + Stage 1·2·3 + 최종 보고 1 + scope 확장 1 + Stage 4 + 최종 보고 갱신 1 + scope 재확장 1 + Stage 5) |
| README "저장소 구조" 섹션 | 단일 트리 | 두 관점 (적용 후 대상 / 자기 적용 후) |
| PR 템플릿 섹션 | 6개 (요약/변경 내역/검증/문서/관련 이슈/남은 리스크) | 8개 최상위 + 변경 내역 안 2개 하위 목차 (### 영향 영역·### 작업 문서) |
| PR 기본 상태 | draft | Open |
| 이슈 종결 표기 | Closes # (PR 본문) |
대상 타스크: # (요약 첫 bullet) |
변경 내역 본문 |
자유 텍스트 + 영역 표 + 문서 링크 혼재 | Stage timeline만 (영역·문서는 하위 목차) |
| 수용 기준 | 결과 |
|---|---|
docs/agent-entrypoint.md의 "If The Target Repository Is Installed" 체크리스트 충족 |
OK — 6개 모두 존재 |
git status --short 빈 출력 |
OK — 통합 검증 시 빈 출력 |
mydocs/orders/20260502.md의 #1 행 완료 상태 + 시각 기록 |
OK — 본 보고와 함께 갱신 |
본 저장소 issue/branch/PR/mydocs/ 산출물이 살아있는 예시로 정렬 |
OK — 이슈 #1, 브랜치 local/task1, 단계 커밋 + 보고 커밋 정렬 |
| PR #115의 PR 규칙 강화가 본 저장소 templates와 자기 적용본에 동기화 | OK — Stage 4 검증 grep 모두 통과 |
PR 변경 내역 섹션이 Stage timeline + ### 영향 영역 + ### 작업 문서 구조로 분리 |
OK — Stage 5 검증 grep 모두 통과 |
- Stage 1:
git diff --checkOK, placeholder 잔존 검사 0건 - Stage 2: 4개 심볼릭 링크 정상 대상,
diff -qskills/manual 본문 일치 - Stage 3:
^## 저장소 구조1건,(적용 후 대상 저장소|자기 적용)7건,git diff --checkOK - Stage 4: templates 5개 파일에서
draft PR|--draft잔존 없음, templates·자기 적용본 PR 템플릿에서 8개 섹션 모두 존재, 자기 적용본에{REPO_SLUG}잔존 없음,README.md/AGENTS.md에서draft PR잔존 없음 - Stage 5: templates·자기 적용본 PR 템플릿에
### 영향 영역·### 작업 문서각 1건씩,pr_process_guide.md작성 예시에도 같은 두 하위 섹션 노출,git diff --checkOK
- Windows 호환: 본 저장소는 macOS/Linux 기여자 중심으로 설계됐다. Windows 환경 fork에서 심볼릭 링크가 일반 파일로 변환될 가능성. 발생 시 별도 task로 대응.
- 매뉴얼 placeholder 보존:
templates/mydocs/manual/*.md는{REPO_SLUG},{BASE_BRANCH}등 placeholder를 그대로 보존한다. 본 저장소 사용자가 매뉴얼을 직접 읽을 때 placeholder를 본문 그대로 읽게 된다. 이는 의도된 설계(진실 원천 보호 + dogfooding 일관성)이며 AGENTS.md 강제 규칙에 명시되어 있다. - AGENTS.md 검증 grep: 강제 규칙 본문이 placeholder 표기를 인용하면 검증 grep에 잡히는 약점이 있다. 일반화 표기(
예: {REPO_SLUG})로 우회했지만, 향후 검증 패턴을 강화한다면 이 인용 규칙을 매뉴얼에 명시하는 게 좋다. - Stage 이중 링크 자동화 부재: PR 본문의 Stage 보고서·commit URL은 PR 작성자가 직접 채워야 한다. PR #115의 잔여 리스크와 동일.
- PR #115 형식과의 일시적 차이: Stage 5에서 본 저장소가
변경 내역안에### 영향 영역·### 작업 문서하위 목차를 도입했지만 alhangeul-macos는 아직 평면 배치다. upstream 후속 동기화에서 정렬되거나, 의도된 차이로 유지될 수 있다.
- 본 저장소의 PR 본문/이슈 댓글에서 사용된 patterns(추적 댓글 형식, 체크포인트 댓글 형식)를
templates/mydocs/skills/issue-checkpoint/SKILL.md의 예시 본문으로 추가해 사용자에게 더 구체적인 예시 제공. - PR 본문 lint 또는 PR 본문 생성 보조 스크립트 도입 검토 (PR #115의 후속 제안과 동일 방향).
- 자기 적용 자체의 운영 경험을
templates/mydocs/manual/에 별도 매뉴얼로 추가할지 검토. 현재는 README와 본 보고서만으로 충분.
- 본 보고서로 task #1 마무리에 동의?
- 본 보고서 커밋 후 PR #2 본문을 새 템플릿 형식으로 재작성하고 (
gh pr edit --body-file), draft 상태는 그대로 유지.