주간 문서·영상 작업과 파일 전달
기능 마스터 · 문서와 영상 갱신 기준 · 검증 범위
매주 금요일에 변경된 기능의 문서를 추가·수정하고, 필요한 영상을 촬영해 초안 PR을 만듭니다. 영상·썸네일·ZIP은 사용자의 PC에 보관합니다. 미디어 업로드·검증용 GitHub Actions와 stage·dispatch·publish 명령은 제거했습니다. S3 업로드나 업로드용 PR 생성은 이 작업에 포함하지 않습니다.
기존에 인프라가 업로드한 영상 99편과 썸네일 99개의 CDN 연결은 유지합니다. 새 촬영본의 주소는 업로드가 확인된 후 별도로 반영합니다. 예약 실행은 Codex 데스크톱의 예약 작업으로 관리하며, 이 문서나 YAML에 일정을 적는 것만으로 실행되지는 않습니다.
담당과 진입점
| 항목 | 내용 |
|---|---|
| 주간 작업 담당 | 사용자의 지정 PC에서 이 작업에 등록된 예약을 실행하는 Codex. 다른 PC의 일반 개발 에이전트에게 맡기는 공통 작업이 아닙니다. |
| 실행 시점 | 매주 금요일 오후 8시(한국 시간, Asia/Seoul). 활성 상태와 실행 결과는 Codex 예약 작업에서 확인합니다. |
| 문서·코드 원본 | hereby-dhub의 최신 병합된 기능, 관련 기능 PR, 제품 개발 기록, 사용자 가이드 원본, 기능별 영상 원장 |
| 작업 위치 | 다른 개발 작업과 분리한 codex/ 브랜치와 작업 폴더 |
| 영상 보관 | 기본 체크아웃의 .docs-media/weekly/<실행일>/<회차>/media/. 임시 작업 폴더를 지워도 남는 PC의 고정 위치를 사용합니다. |
| 결과 확인 | 이 Codex 작업의 완료 보고와 GitHub의 Draft PR |
| 실행 조건 | PC와 Codex 앱이 실행 중이어야 하며, 저장소·GitHub와 촬영용 예제 조직에 접근할 수 있어야 합니다. |
준비와 일정 관리
사용자의 지정 PC에 이미 등록한 Codex 예약 작업에서 저장소, 실행 시각, 초안 PR 생성, 로컬 보관, ZIP 생성과 경로 보고를 관리합니다. 다른 PC에 같은 예약을 추가하거나 공통 에이전트 지침에 문서 갱신 의무를 넣지 않습니다. 로컬 파일이 필요한 예약 작업은 컴퓨터와 앱이 실행 중이어야 합니다. 예약 작업의 실행 조건을 따릅니다.
촬영에는 고객에게 공개해도 되는 예제 조직을 사용합니다. 영상·썸네일·촬영 JSON·전달 안내에 개인정보나 인증정보를 남기지 않습니다. 업로드용 AWS 자격 증명은 필요하지 않습니다. 기능 PR·문서 PR을 조회하고 문서 브랜치와 초안 PR을 생성할 GitHub 권한은 필요합니다.
매주 수행하는 작업
- 직전 성공한 작업 이후 병합된 기능 변경과 이전에 남긴 문서·영상 미완료 항목을 확인합니다. 첫 실행은 최근 7일과 기존 영상 원장의 미완료 항목을 확인합니다. 재실행 때 같은 주의 PR과 산출물을 찾아 중복 생성을 피하고, 실패한 항목은 다음 실행에 계속 포함합니다.
- 실제 코드와 사용할 수 있는 제품 환경을 확인합니다. 일반 기능 개발 담당자가 문서를 수정했거나 변경 이력을 남겼다고 가정하지 않고 병합된 변경에서 직접 찾습니다. 이미 다른 PR에서 처리한 변경은 다시 작성하지 않습니다. 기능 PR이 병합됐다는 이유로 고객에게 배포됐다고 표시하지 않습니다.
- 기능별 개발 기록과 마스터 링크, 사용자 가이드 원본을 함께 다듬습니다. 사용 대상·시작 위치·조건을 표로 정리하고, 입력·저장·취소·결과 확인·예외와 관련 화면까지 설명합니다. 개발 용어와 내부 운영 안내는 고객용 사용 절차에 섞지 않습니다.
- 변경된 사용 절차별로 영상을 촬영합니다. 기존 개요와 같은 무음 WebM, 어두운 반투명 자막, 주황색 사각 동작 번호, 대상 강조와 읽을 수 있는 확대를 사용합니다.
scripts/docs-capture-overlay.mjs를 재사용하고 번호와 실제 장면 시각을 대조합니다. 앱 개요 한 편으로 여러 기능의 촬영을 대신하지 않습니다. - 최종 영상과 같은 크기의 썸네일을 PC의 고정 보관 폴더에 저장합니다. 촬영 JSON은 같은 회차의
records/에 보관합니다. 파일명에는 기능 ID와 실행 회차를 넣어 이전 촬영본을 덮어쓰지 않습니다. - 해당 회차의 영상과 썸네일만 묶은
hereby-docs-media-<실행일>-<회차>.zip을 만듭니다. ZIP 목록과 무결성을 확인합니다.handoff.md에는 기능·관련 문서·영상 파일·썸네일 파일·동작 수·파일 크기·SHA-256·기존 URL·최종 URL 대기 여부를 표로 기록합니다. JSON과 안내 문서는 ZIP 바깥에 둡니다. - 문서 변경을 로컬에서 검토하고 관련 생성·빌드 검사를 수행합니다. PR 전체 파일 목록과 새 커밋을 확인해 영상·썸네일·ZIP·로컬 촬영 파일·인증정보가 하나도 포함되지 않게 합니다.
.gitignore만 확인하고 끝내지 않습니다. - 문서 추가·수정과 필요한 텍스트 메타데이터만 커밋하고 Draft PR을 생성합니다. 같은 회차의 초안 PR이 이미 있으면 갱신합니다. 기능 PR과 연결하고, 사용자 작업의 기본 담당자는
EthanKyleKim으로 지정합니다. 임의로 검토자를 지정하거나 PR을 준비 완료로 바꾸거나 머지하지 않습니다. - 영상이 아직 업로드되지 않았으면 기존 영상 URL·챕터 설명을 그대로 유지하고, 새 영상 연결이 남았음을 PR에 명시합니다. 새 기능은 존재하지 않는 CDN 주소나 로컬 절대 경로를 문서에 넣지 않습니다. 재생 목록이 요구하는 신규 영상 마커도 연결 준비 전에는 추가하지 않습니다. 새 촬영과 맞는 JSON은 로컬에서 보관하다가 최종 주소 확인 후 함께 반영합니다.
- 완료 보고에 초안 PR 링크, 갱신한 문서, 촬영한 기능, 영상·썸네일 폴더의 절대 경로, ZIP의 절대 경로·크기, 전달 안내 경로와 미완료 항목을 남깁니다. 로컬 작업 기록에는 검토한 마지막 커밋·기능 PR·완료 및 미완료 항목을 남깁니다. 촬영하지 못한 기능을 완료로 처리하지 않습니다.
저장 위치와 PR 구성
| 자료 | 저장·전달 방식 |
|---|---|
| 영상·썸네일 | PC의 .docs-media/weekly/<실행일>/<회차>/media/에 보관. Git·PR·GitHub 첨부파일에 올리지 않습니다. |
| 촬영 JSON | 같은 회차의 records/. 업로드 전 촬영 상태와 번호·시각을 보관합니다. |
| 전달 ZIP | 같은 회차 폴더의 hereby-docs-media-<실행일>-<회차>.zip. 영상·썸네일만 포함합니다. |
| 전달 안내 | 같은 회차의 handoff.md. 문서와 파일의 대응, 크기·해시·업로드 대기를 기록합니다. |
| 주간 작업 상태 | .docs-media/weekly/state.json. 완료 범위와 미완료 항목, PR 연결을 저장하며 Git에서 제외합니다. |
| 문서 PR | 사용자 가이드 원본·기능 문서·마스터 링크·변경 이력 등 텍스트 변경. 검증된 최종 주소가 있을 때만 재생 목록과 영상 설명을 함께 갱신합니다. |
주간 작업은 업로드까지 완료한 것으로 보고하지 않습니다. 이후 인프라에서 업로드한 공통 주소·경로 규칙·완료 여부를 받으면 최종 주소 연결에 따라 해당 문서 PR에서 영상·썸네일·번호별 설명을 함께 반영합니다. 고객 변경 이력은 제품 배포와 문서·영상 검토가 확인될 때까지 공개하지 않습니다.
실패·재시도·이전 영상 복구
촬영 환경이나 로그인이 준비되지 않았으면 가능한 문서 작업을 초안 PR로 남기고, 촬영하지 못한 정확한 기능·단계와 필요한 조건을 보고합니다. 재생 검사를 못 했으면 그 범위를 남깁니다. 빈 영상·추정한 결과·이전 영상을 새로 촬영했다고 보고하지 않습니다.
ZIP 생성이나 PR 생성이 실패해도 로컬 촬영본은 보존합니다. 같은 회차를 다시 실행해 빠진 단계부터 이어갑니다. 사용자가 파일을 전달하거나 업로드했을 수 있으므로 이전 ZIP·촬영본을 임의로 삭제하거나 덮어쓰지 않습니다. 변경이 없는 주에는 빈 PR·빈 ZIP을 만들지 않습니다.
최종 주소 연결 후 문제가 발견되면 정상 CDN 주소와 해당 촬영 설명·확인 근거를 함께 복원하고 재생 목록을 다시 생성합니다. 자동 머지·자동 롤백·S3 삭제는 수행하지 않습니다.
기존 영상 이전과 저장소 용량
이번 문서 PR에 추가했던 영상 98편·썸네일 98개, 총 387,703,579바이트를 원본과 CDN의 내용 일치 확인 후 Git에서 제외했습니다. 로컬 원본은 .docs-media/archive/cdn-migration-2026-09-15/ 안에 기존 상대 경로대로 보관합니다. manifest.json에는 각 원본 경로·CDN 주소·파일 해시가 있습니다. 이전 커밋의 파일까지 지우는 Git 이력 재작성은 하지 않았습니다.
docs/media/legacy-files.json은 빈 객체입니다. 로컬 pnpm check:docs-media로 촬영 파일의 Git 재유입을 확인할 수 있습니다. 기존 랜딩 데모가 사용하는 apps/landing/public/demo/hereby-sheet-story.webm과 썸네일은 기존 기능의 파일이므로 유지합니다. 기존 CDN 연결 99쌍의 파일과 기록은 주간 작업 전환으로 삭제하지 않습니다.
배포 환경별 영상·썸네일 주소
문서 배포 작업은 VITE_DOCS_STATIC_URL로 영상·썸네일을 제공할 도메인을 지정합니다. 공통 재생기가 앱 개요·항목별 가이드·급여 시트 영상과 재생 실패 시 보여 주는 이미지에 같은 설정을 적용합니다.
| 문서 환경 | 정적 파일 도메인 | 배포 설정 |
|---|---|---|
| dev | https://works-static.dev.hereby.me | dev-sites.yaml의 문서 작업 |
| stg | https://works-static.stg.hereby.me | stg-sites.yaml의 문서 작업 |
| prod | https://works-static.hereby.me | release-sites.yaml의 문서 작업 |
도메인 뒤의 /docs/파일명은 모든 환경에서 같습니다. 예를 들어 운영 문서의 문서 양식 영상은 https://works-static.hereby.me/docs/admin-document-template.webm을 사용합니다. 인프라는 각 환경의 같은 경로에 해당 영상과 썸네일을 준비해야 합니다. 주소 설정은 파일 업로드나 환경 간 복사를 수행하지 않습니다.
환경 변수가 없으면 로컬 개발 서버는 dev, 배포용 빌드는 prod를 사용합니다. 로컬에서 stg 빌드를 확인하려면 VITE_DOCS_STATIC_URL=https://works-static.stg.hereby.me pnpm --filter @hereby/docs build를 실행합니다. 빌드 시 결정된 주소는 재배포해야 바뀝니다. 이 변수는 Turbo의 빌드 캐시 구분에도 포함하므로 환경이 다른 결과를 재사용하지 않습니다. Vite 환경 변수, Turbo 환경 변수와 캐시의 동작을 따릅니다.
촬영 JSON의 external.assets.*.url과 verifiedAt은 파일을 실제로 확인했던 주소와 시각입니다. 이 근거를 다른 환경에서 검증한 것으로 바꾸지 않고 재생기의 요청 주소만 환경에 맞춥니다. 다른 외부 서비스의 영상과 로컬 /tutorials/ 경로는 변환하지 않습니다. 환경별 파일의 실제 응답과 재생 여부는 별도로 확인합니다.
직접 업로드한 영상 주소 연결
인프라 담당자가 업로드한 공통 주소는 https://works-static.dev.hereby.me/docs/입니다. 기존 파일명을 그대로 붙여 앱 개요 8편, 기능별 90편, 별도 급여 시트 1편의 영상·썸네일 총 198개를 연결합니다. 파일명은 서로 중복되지 않으며, 예를 들어 admin-document-template.webm은 문서 양식 영상에 대응합니다.
| 항목 | 처리 |
|---|---|
| 업로드 담당 | 인프라 담당자가 영상·썸네일을 기존 파일명으로 업로드하고 공통 주소·경로 규칙·완료 여부를 전달합니다. 촬영 JSON은 Git에서 관리하며 수동 업로드에 필수인 파일이 아닙니다. |
| 연결 담당 | Codex·Claude 또는 개발자가 기존 영상 ID·파일명·전체 파일 내용과 최종 URL의 일치를 확인합니다. |
| 앱 개요 원본 | docs/media/app-tutorials.json의 8개 항목에서 recording, poster, external을 함께 수정합니다. |
| 기능별 원본 | docs/public/tutorials/2026-09-11/sections/*.json의 90개 항목에서 같은 필드를 수정합니다. |
| 별도 급여 시트 | SheetVideoGuide.vue의 recording, poster 두 주소를 수정합니다. 이 영상은 기존 별도 컴포넌트를 유지하며, 확인 근거는 검증 원장에 보관합니다. |
| 확인할 파일 | 전체 응답의 HTTP 200, SHA-256·크기와 영상의 video/webm, 이미지의 image/jpeg를 대조합니다. 모든 영상은 실제 206 구간 바이트도 확인합니다. |
| 기록할 정보 | 98개 촬영 항목의 external.schemaVersion: 1, 설명 원본의 captureSha256, external.assets.recording과 external.assets.poster에 url, file, bytes, sha256, contentType, verifiedAt을 기록합니다. |
| 가이드 반영 | pnpm gen:docs-guides로 두 재생 목록을 생성합니다. 번호·시작 시각·사용법·연결 위치는 기존 촬영 내용대로 유지합니다. 생성 파일은 직접 편집하지 않습니다. |
이번 연결은 CDN 파일을 읽어 검증한 작업이며 AWS 버킷·권한이나 Actions를 설정한 작업이 아닙니다. 실제 사용자는 기존 앱 소개·사용자 가이드에서 같은 재생 버튼과 번호를 사용합니다. 전체 파일 대조와 문서·브라우저 확인 범위는 검증 원장에 기록합니다.
captureSha256는 주소와 등록 근거를 제외한 기존 촬영 설명을 capturePayload로 추출해 captureDigest로 계산합니다. verifiedAt은 실제 확인을 마친 UTC 시각이며, 파일 해시나 확인 시각을 추정해서 채우지 않습니다. 가이드 생성기는 HTTPS 주소·크기·해시 형식·설명 일치·로컬 표지 존재를 검사하고, 기존 자동 등록의 publication과 수동 확인의 external을 동시에 허용하지 않습니다. 화면에는 내부 확인 근거가 표시되지 않습니다.
연결 후 문서 빌드와 실제 브라우저 재생·각 번호 이동을 확인합니다. 잘못 연결했다면 JSON의 주소와 확인 정보를 함께 복원하고 재생 목록을 다시 생성합니다. 로컬 경로로 되돌려 시험할 때는 보관 폴더의 원본도 기존 위치로 복원해야 하며, 이 파일은 Git에 다시 추가하지 않습니다. PR에서 원복할 때는 정상 CDN 주소와 해당 확인 정보를 함께 복구하고, CDN 객체 자체가 잘못됐으면 원본을 새 주소에 업로드한 뒤 다시 대조합니다. 주소 연결 명령 자체는 S3 업로드나 Git 파일 제거를 수행하지 않으며, 이번 98쌍의 제외는 검증 후 별도 커밋으로 처리합니다.
수동 업로드 URL은 덮어쓰기 방지가 확인된 버전 주소가 아닙니다. 같은 경로의 파일이 나중에 바뀌는지 빌드가 실시간으로 감시하지 않으므로 내용 교체 시 새 주소에서 다시 대조합니다. 새 촬영본도 인프라가 전달한 최종 주소를 실제 파일과 대조한 후 같은 방식으로 연결합니다. 주간 예약 작업은 업로드를 수행하거나 최종 주소를 추측하지 않습니다.