기능 문서 작성·갱신 방법
제품 개발 기록으로 · 기존 문서 원장 · 검증·미확인 항목
책임과 문서 구조
문서 추가·수정과 최종 영상 제작은 사용자의 지정 PC에 등록된 금요일 오후 8시 Codex 예약 작업이 맡습니다. 이 페이지는 해당 문서 작업의 품질·작성 절차를 설명합니다. 일반 기능 개발을 수행하는 Claude·Codex·다른 에이전트에게 문서 수정, 변경 이력 작성, 촬영 또는 후속 문서 PR 생성을 요구하지 않습니다. CLAUDE.md와 이를 가리키는 AGENTS.md의 문서 갱신 의무 및 연결된 자동 적용 규칙을 제거했습니다.
- 마스터:
docs/ko/guide/product-development-record.md. 안정적인 기능 ID·기능명·상세 경로·주요 연결을 관리합니다. - 기능:
docs/ko/features/<feature-id>.md. 현재 전체 사용법·관련 기능·구현 근거·변경 이력을 관리합니다. 새 기능이면 새 파일을 만들고 마스터에 등록합니다. - 시각 자료: 기능 옆
assets/<feature-id>/<capture-date>/. 기존 안전한 원본이 저장돼 있으면 중복 복사하지 않고 원본을 연결합니다. - 변경 설명 원본:
docs/superpowers/explainers/. 원본 근거를 보존하고 관련 기능으로 연결합니다. - 사용자 가이드: HTML 원본
docs/ko/guides/fragments/수정 후 생성. Confluence 동기화 사양은 원본 파이프라인이 소유하므로 임의로 현재 사실로 덮어쓰지 않습니다. - 사용자 변경 이력:
docs/product-changes/<feature-id>/<change-id>.json에 한 번 기록하고 여러 가이드 절로 연결합니다. 변경 이력 관리에 따라 최근 2건과 전체 이력을 생성합니다.
예약된 문서 작업의 실제 순서
- 마스터에서 기능을 찾고 현재 사용 절차·관련 기능·미확인 항목을 읽습니다. 새 기능이면 역할·진입점 기준으로 ID를 정합니다. ID는 파일명이며 이름 변경 시 옛 마스터 진입 링크도 유지합니다.
- 실제 화면의 버튼·메뉴·탭에서 상태 로직, SDK, API, 입력 검증, 저장 엔티티까지 확인합니다. API만 존재하는 조작, 숨겨진 탭, 준비 중 버튼은 실제 제공 조작과 구분합니다.
- 모든 조작의 단계와 입력·결과·오류·취소·재시도·재진입을 작성합니다. 개발 기록끼리는 데이터가 들어오는 기능과 결과가 보이는 기능을 양쪽 링크로 연결합니다. 사용자용 문서는 같은 사용자용 절차로 연결합니다.
- 적절한 테스트 환경에서 절차를 실행하고 기능 개발 기록에 변경 이유·근거·검증 범위를 남깁니다. 마스터와 관련 기능의 연결도 갱신합니다. 개발 중 캡처는 QA에 활용하고 고객용 최종 영상은 병합 후 동작을 기준으로 준비합니다.
- 예약 담당자가 병합된 기능 PR과 실제 변경을 대조하고 주간 문서 PR에 새 이력 원본을
unreleased로 추가합니다. 남은 사용법과 촬영 장면은pending과 구체적인 이유로 적습니다.followUp에는 실제 문서 담당자·원래 기능 PR·주간 문서 PR을 연결합니다. 기능 PR에 문서나 이력이 미리 작성돼 있어야 하는 조건은 없습니다. - 지정 PC의 예약 담당자가 갱신된 대상 브랜치에서 문서·영상 PR을 엽니다. 기존 초안이 있으면 병합된 기능 기준으로 브랜치를 정리합니다. 같은 변경 이력을 이어서 수정하고
trackingUrl을 문서 PR 주소로 바꿉니다. HTML 원본의 전체 사용법을 다듬고, 개요와 같은 번호·강조 형식으로 해당 조작을 촬영합니다. - 지정 PC의 예약 담당자가 문서·영상 작업을 주간 초안 PR로 정리하고 영상·썸네일과 ZIP은 PC에 보관합니다. PR에는 문서 변경만 포함하고 미디어의 최종 주소가 확인되기 전까지 연결 작업을 대기로 남깁니다. 완료 보고에는 PR 링크와 영상·썸네일·ZIP의 절대 경로를 기재합니다. 기능 PR과 문서 PR에는 서로의 링크를 남깁니다.
- 주간 문서 PR의 비교 기준으로
pnpm gen:docs-guides,pnpm test:docs-history,pnpm check:product-docs --base <검토-기준-커밋>과 문서 빌드를 실행합니다. 문서 PR에서 갱신·검토가 끝난 항목만updated또는 근거 있는unchanged로 바꿉니다. 실제 제품 배포까지 확인한 후 고객 변경 이력을 공개합니다. 문서 PR 병합 후 추적 이슈를 닫고 완료 보고에 두 PR과 남은 검증을 적습니다.
예약 실행 지시는 이 PC의 Codex 예약 작업에만 저장합니다. 이 안내를 읽거나 저장소를 다른 컴퓨터에 복제하는 것만으로 같은 문서 작업을 시작하지 않습니다.
주제별 변경 이력 관리
사용법 본문에는 현재 조작을 온전히 유지하고, 주제 끝에는 사용자에게 달라진 점을 최대 2건만 보여줍니다. 이력 표의 표시 위치는 사용자 가이드의 해당 주제와 전체 이력 페이지로 한정합니다. 앱 소개는 기존 사용법 링크를 유지합니다. 오래된 항목은 전체 변경 이력에 계속 보관합니다. 같은 변경이 관리자와 직원 앱에 영향을 주면 이력 원본 하나에 두 절을 연결합니다. 이력 요약이 전체 사용법이나 중요한 제한사항을 대신하지 않습니다.
| 구분 | 담당과 진입 위치 |
|---|---|
| 읽는 사람 | 해당 업무를 사용하는 관리자·직원·고객사 교육 담당자 |
| 읽는 위치 | 사용자 가이드의 해당 주제 끝 또는 사이드바의 「전체 변경 이력」 |
| 작성 책임 | 지정 PC의 주간 문서 예약 작업 담당 |
| 작성 원본 | docs/product-changes/<feature-id>/<change-id>.json. 개발 설명은 관련 기능 문서, 현재 사용법은 해당 가이드 HTML 원본 |
사용자는 본문과 번호별 영상으로 현재 작업을 따라 합니다. 주제 끝의 「변경 이력」 표에서 적용일·구분·달라진 점과 사용 방법을 읽습니다. 「전체 변경 이력」을 누르면 같은 변경으로 이동하고 더 오래된 내용도 읽을 수 있습니다. 전체 이력의 작업 이름을 누르면 해당 사용 절차로 돌아옵니다. 고객용 본문·검색·링크에 내부 검증 근거나 개발 파일을 넣지 않습니다. 공통 상단 메뉴는 유지합니다.
기록부터 공개까지
- 관련 기능 문서를 읽고 새 변경 ID를 정합니다. 기능 ID는 기능 문서의 파일명, 변경 ID는 한 번의 추가·수정 작업을 식별하는 값입니다. 이미 공개한 변경 ID를 새 개발 작업에 다시 사용하지 않습니다.
status를unreleased,appliedOn과releaseEvidence를null로 두고 시작합니다.title은 업무 이름,summary는 달라진 조작과 사용 위치를 쉬운 한국어로 씁니다. 구분은 추가(added)·변경(changed)·수정(fixed)·종료(removed) 중 고릅니다.guides에 영향을 받는 모든 가이드의page와 명시적 ASCIIanchor를 등록합니다. 조직 설정은admin의s11-1, 직원 홈은employee-app의s3를 함께 연결할 수 있습니다. 한 가이드에서 여러 주제가 바뀌면 각각 연결합니다. 생성 Markdown에 이력을 직접 붙이지 않습니다.- 예약 담당자가 병합된 기능의 개발 기록과 연결을 문서·영상 PR에서 작성합니다. 같은 PR에서 HTML 원본의 진입 경로·입력·처리·결과·예외를 현재 동작에 맞추고
documentation에 갱신 여부와 이유를 적습니다. 기능 개발 문서에는 변경 이유, 관련 화면·API·저장 데이터, 검증 범위를 직접 보완합니다.codePaths에는 관련 제품 파일의 정확한 경로,evidence에는 소스·실행 확인 근거를 적습니다. - 해당 절의 영상을 대조합니다. 버튼·순서·입력·결과가 달라졌으면 해당 영상을 개요와 같은 번호·강조 형식으로 다시 촬영하고 JSON·포스터·번호별 설명을 갱신합니다.
video.tutorials에는 기능 영상 ID를 적습니다. 기존 영상을 유지할 수 있으면 대조한 실제 조작과 유지 이유를 씁니다. 미촬영 장면을 「변경 없음」으로 처리하지 않습니다. - 가이드를 생성하고 이력 테스트·변경 파일 검사·문서 빌드를 실행합니다. 실제 화면에서 주제 끝 배치, 최신 2건, 전체 이력의 오래된 항목, 사용법으로 돌아오는 링크를 확인합니다. 기능 자체의 권한·처리·저장 결과는 별도 실행 검증으로 남깁니다.
- 실제 적용을 확인한 후
released로 바꾸고 적용일과 배포 실행·현장 확인 근거를 적습니다. 작성일이나 커밋 날짜로 적용일을 추정하지 않습니다. 문서·영상 확인이 대기 중이면 공개할 수 없습니다. 원본 변경 후 다시 생성·검증하고 정상 문서 배포 절차로 반영합니다.
| 입력 | 허용 상태와 처리 |
|---|---|
status | unreleased는 적용 또는 문서·영상 확인이 끝나지 않아 고객 이력을 준비 중인 상태, released는 확인된 공개 이력, internal은 사용자 영향이 없는 내부 변경입니다. 공개 이력만 문서에 표시합니다. |
documentation.status·video.status | updated는 갱신 완료, unchanged는 기존 설명·영상의 일치를 검토 완료, pending은 확인 대기입니다. 모두 구체적인 reason을 적습니다. 영상 갱신에는 실제 기능 영상 ID가 필요합니다. |
appliedOn·releaseEvidence | 공개 시 실제 적용일 YYYY-MM-DD와 배포 확인 근거가 필수입니다. 잘못된 날짜·미래 날짜·근거 없는 공개는 거부합니다. 적용 전·내부 기록에는 비워 둡니다. |
followUp | owner는 담당 GitHub 사용자, featurePr은 원래 기능 PR, trackingUrl은 같은 저장소의 별도 후속 이슈 또는 문서 PR입니다. 문서·영상 검토를 모두 완료할 때는 실제 문서 PR 주소가 필요합니다. 공개 화면에는 나오지 않습니다. |
guides | 지원하는 가이드의 절 주소를 적습니다. 후속 작업이 연결된 문서 작성 대기 상태에서는 추가할 절 주소를 미리 적을 수 있지만, 작성 완료 시에는 그 절이 실제로 있어야 합니다. 공개 이력에 비공개 팀 관리자·재고 가이드 주소를 연결하면 실패합니다. |
internal | 가이드 연결을 비우고 noUserImpactReason을 적습니다. 순수 서식·기계적 이름 변경만으로 고객 공지를 만들거나 기능 설명을 다시 쓰지는 않습니다. 유지보수에 영향이 있으면 개발 기록 갱신 책임은 그대로입니다. |
공개된 항목은 삭제하거나 적용 전 상태로 되돌리지 않습니다. 기능 원복·종료도 새 이력을 추가하고 현재 사용법에 대체 경로를 씁니다. 중요한 조건은 최근 2건에서 해당 이력이 빠져도 본문에 남깁니다. 같은 날짜의 항목은 변경 ID 순서로 정렬하며 시간 단위의 배포 순서를 뜻하지 않습니다. 이력이 없는 주제에는 빈 표를 넣지 않습니다.
생성·검사의 연결과 범위
scripts/guide-sources.mjs는 HTML 원본과 생성 페이지의 대응표입니다. docs-product-changes.mjs가 이력 원본을 검증하고, gen-docs-guides.mjs가 기존 제목·영상·본문 뒤에 이력을 넣은 다음 전체 페이지를 생성합니다. 원본 폴더는 VitePress 빌드에서 제외하며 고객용 제목·설명·적용일·구분·사용법 링크만 출력합니다. 현재 지원 범위는 HTML에서 생성하는 가이드입니다. 수동 관리 문서에 이력이 필요하면 대응표와 생성 지원을 추가해야 합니다. 독립 HTML 배포 파이프라인에는 이 표를 추가하지 않았습니다.
가이드 생성은 기능 문서·절 주소·영상 ID·배치·공개 조건을 검사합니다. pnpm check:product-docs는 제품 소스와 같은 변경의 이력·기능 문서·사용법 원본을 대조하고, 공개 이력 삭제·재사용과 담당·후속 연결 없는 문서·영상 대기를 잡습니다. 추적 중인 대기는 기능 PR에서 허용하며, 문서 PR에서 대기를 갱신 완료로 바꾸면 제품 코드 변경 없이도 가이드 원본 수정 여부를 확인합니다. 후속 기록과 원래 기능 PR 연결은 삭제할 수 없습니다. 테스트 파일과 제품의 설명용 Markdown은 소스 검사에서 제외합니다. 기본 비교 기준은 HEAD이므로 커밋 전 작업을 검사할 수 있고, 이미 커밋된 PR은 --base에 실제 검토 기준을 지정합니다.
검사는 문장의 충분성·영상의 실제 일치·배포 근거의 진위를 판정하지 않습니다. 후속 URL의 형식과 저장소·번호 관계는 검사하지만 GitHub에 실제로 존재하는지, 담당자가 누구인지, PR이 병합됐는지는 담당자가 확인합니다. updated 선언과 유효한 영상 연결도 실제 재촬영을 증명하지 않으므로 완성 영상을 직접 확인합니다. 제품별 회귀 검증과 담당자의 기록 책임을 대신하지 않으며 CI나 커밋 훅에 자동 연결한 명령도 아닙니다. 원본 작성 예시는 저장소 docs/product-changes/README.md를 따릅니다.
첫 기록 organization-access/employee-home-layout.json은 코드와 기존 사용법을 대조해 등록했습니다. 고객 적용일과 해당 설정의 번호별 영상은 확인되지 않아 적용 확인 전·영상 확인 대기로 보관합니다. 기존 조직 기본정보 영상으로 해당 설정 촬영을 완료했다고 간주하지 않습니다. 조직 설정의 남은 확인과 이번 검증을 확인합니다.
화면과 영상으로 설명하기
이미지는 실제 위치를 찾게 하고, 영상은 동작 과정을 이해하게 합니다. 본문 설명과 시각 자료가 같은 절차를 가리키도록 작성합니다.
| 상황 | 적합한 자료 | 표시할 내용 |
|---|---|---|
| 메뉴·버튼 찾기, 필드 입력 | 실제 화면 캡처와 필요 시 부분 확대 | 본문의 1·2·3번에 대응하는 번호, 눌러야 하는 위치를 가리키는 화살표·테두리, 입력 예시 |
| 여러 화면·팝업을 거치는 작업 | 단계별 캡처 묶음 또는 짧은 영상 | 시작 화면, 각 클릭 위치, 중간 화면, 완료 결과. 다른 앱으로 넘어가는 지점도 포함 |
| 드래그·스크롤·hover·리사이즈·제스처 | 짧은 화면 녹화와 핵심 장면 | 포인터·터치 위치, 이동 방향, 놓는 위치, 달라진 결과. 단계 자막 또는 시간별 설명 |
| 저장·요청 후 결과 확인 | 조작 전후 캡처 또는 영상 | 누른 버튼뿐 아니라 성공·실패 안내와 결과가 반영된 화면. 저장 확인은 필요한 경우 재진입까지 포함 |
| 로딩·성능 비교 | 같은 조건의 전후 영상과 측정 자료 | 시작·종료 기준, 실제 대기 시간, 측정 환경. 재생 속도 변경이나 편집한 구간은 명시 |
예를 들어 알림 절차의 설명은 「1. 종 아이콘을 누릅니다」「2. 휴가 알림 행을 누릅니다」「3. 결재의 휴가 탭과 대상 목록을 확인합니다」로 이어집니다. 대응 캡처에도 같은 번호를 놓고 각각 종 아이콘·알림 행·결과 탭을 가리킵니다. 화면에 2번을 표시했는데 본문에서는 다른 조작을 설명하면 수정 대상입니다.
화살표가 버튼 이름을 가리지 않게 하고, 너무 잘라내어 어느 앱·화면인지 알 수 없게 만들지 않습니다. 영상에는 클릭·터치 위치와 결과 확인 장면을 포함하며, 영상 재생 없이도 따라 할 수 있도록 단계별 글과 대표 장면을 함께 둡니다. 의미가 색깔이나 소리에만 의존하지 않도록 캡션·대체 텍스트를 제공합니다.
본문·제목·이미지 캡션·영상 설명은 조작과 결과를 중심으로 작성하고 문서 작성·촬영 시점을 붙이지 않습니다. 촬영 날짜와 버전은 원본 메타데이터나 연결된 근거에서 관리합니다. 사용법에 필요한 앱·경로·역할·화면 크기·실행 환경, 입력 예시 날짜, 실제 화면 차이와 미검증 조작은 명확하게 남깁니다. 예시 데이터로 촬영하거나 필요한 개인정보·토큰을 가린 뒤 보관하고, 가림·화살표 외에 실제 UI와 결과를 바꾸지 않습니다. 시안·생성 이미지나 단순 화면 자료를 실제 실행 결과로 표시하지 않습니다.
자료는 문서 옆의 docs/ko/features/assets/<feature-id>/<capture-date>/처럼 관련 기능을 찾을 수 있는 위치 또는 프로젝트의 지속적으로 접근 가능한 저장소에 둡니다. 완성 문서에는 임시 캡처 경로를 남기지 않습니다. 문서 페이지에서 이미지의 글자·화살표를 읽을 수 있는지, 영상이 재생되는지, 캡션과 단계가 일치하는지 확인합니다.
화면·동작이 바뀌면 본문과 해당 이미지·영상을 함께 검토합니다. 촬영 환경이나 권한이 없어 확보하지 못한 경우에는 빠진 장면과 이유를 기재합니다. 기능에 필요한 설명을 충분히 전달한다면 이미지와 영상을 무조건 둘 다 만들 필요는 없습니다.
사용자와 개발자의 문서 탐색 분리
사용자는 개발 기록을 열지 않아도 업무를 끝까지 따라 할 수 있어야 합니다. 한국어 홈·핵심 기능·사용자 가이드·온보딩·영상 목록의 본문과 영상의 「자세히 따라 하기」는 사용자용 문서로 연결하며, 이 페이지들의 검색도 사용자 문서 범위로 제한합니다. 공통 상단 메뉴에는 개발 가이드·시스템 운영 가이드·디자인 시스템·정책·사양서를 함께 표시해 개발자가 어느 페이지에서든 해당 영역으로 이동할 수 있게 합니다. 구현 설명·검증 원장·소스 파일이 절차를 대신하지 않도록 하고, 필요한 설명이 없으면 사용자용 절차를 작성합니다. 개발 기록에서는 그 사용자 절차를 연결하고 기술 근거와 유지보수 이력을 별도로 관리합니다.
| 이용 위치 | 실제 사용 방법과 결과 |
|---|---|
| 한국어 홈·핵심 기능·사용자 가이드 | 상단의 핵심 기능들 또는 사용자 가이드를 선택합니다. 앱 소개와 담당자별 절차를 이동하며 읽습니다. 내부 임포터·시스템 관리자 문서는 이 목록에 노출하지 않습니다. |
| 사용자 문서 검색 | 검색을 열어 업무 이름을 입력합니다. 해당 앱 소개와 사용자 가이드의 절 제목을 선택하면 그 절차로 이동합니다. 결과가 없으면 업무 이름을 바꾸거나 앱 목록에서 찾습니다. 개발 기록은 검색 결과에서 제외합니다. |
| 영상의 자세히 따라 하기 | 번호와 함께 표시된 링크를 누르면 같은 작업의 사용자 절차를 엽니다. 팀 관리자·재고 관리·모듈 매니저는 앱 소개 안에 해당 사용 절차를 두며, 영상 없이도 시작 조건·처리·결과·주의사항을 읽을 수 있습니다. |
| 공통 상단 메뉴의 개발 가이드 | 어느 페이지에서든 개발 가이드를 누르면 개발 문서 목록으로 이동합니다. 여기서 제품 개발 기록과 FE 성능 자료를 찾습니다. 운영·디자인·정책·사양서도 해당 상단 메뉴로 접근합니다. 개발 페이지에서는 전체 문서 검색을 사용하며, 사용자 페이지로 돌아오면 사용자 문서 검색으로 전환됩니다. |
CustomerDocsLayout.vue가 VitePress의 기본 레이아웃에 경로별 설정을 제공합니다. customer-docs.ts는 원본 Markdown 경로와 검색 결과 주소를 같은 기준으로 분류하고, 공통 상단 메뉴를 보존한 채 사용자 페이지의 로컬 검색 결과만 필터링합니다. 원본 설정을 변경하지 않아 개발 페이지에서는 전체 검색을 사용합니다. 번역된 사용자 문서가 없는 언어로 이동하는 메뉴도 사용자 페이지에서는 표시하지 않습니다. 직접 URL을 차단하거나 권한을 도입한 변경은 아닙니다.
가이드 HTML 원본과 공통 영상 정의 app-video-tutorials.ts의 목적지를 함께 갱신했습니다. 팀 관리자 휴가 승인, 재고 수량 조정, 모듈 계산기 상세 조회에 고객이 읽는 절차를 보완했습니다. 급여의 집계 중복 확인, 모듈 테스트의 조직 전체 급여 영향, 재고 수량의 중복 반영 주의처럼 업무 결과에 영향을 주는 조건은 그대로 설명합니다. 녹화 파일·번호·재생 시각은 변경하지 않았습니다.
유지보수 시 새 문서의 독자와 메뉴·검색 노출을 함께 확인합니다. 생성 HTML에서 공통 상단 메뉴의 모든 목적지가 유지되는지 확인하고, 사용자 본문·영상 링크가 내부 문서로 연결되지 않는지도 따로 검사합니다. 사용자 검색과 개발 검색은 같은 브라우저에서 각각 검사합니다. 설치된 VitePress 1.6.4의 기본 테마 구현과 공식 테마 확장, 로컬 검색 설정을 대조했습니다. 검사 결과는 사용자 문서 탐색 검증에 기록합니다.
핵심 기능·사용자 가이드·온보딩에 함께 싣기
동작 번호가 있는 안내는 고객이 기능을 처음 만나는 위치에도 함께 둡니다. 핵심 기능 소개에서는 무엇을 하는지, 사용자 가이드에서는 어떻게 따라 하는지, 온보딩에서는 담당자가 어디까지 직접 해 봤는지를 연결합니다. 같은 영상·번호별 설명을 공통으로 관리해 화면이 바뀌면 한 번에 갱신합니다.
현재 급여 시트 영상은 docs/.vitepress/theme/components/SheetVideoGuide.vue가 원본 자산·포스터·네 단계의 시간과 글 설명을 관리합니다. 핵심 기능 소개, HR 소개, HR 사용자 가이드, 고객사 온보딩, FE 기록이 같은 컴포넌트를 사용합니다. 사용자 가이드 첫 화면에서도 HR 영상으로 바로 이동합니다.
- 처음 재생은 영상의 재생 버튼을 사용합니다. 번호 버튼을 누르면 해당 시점부터 재생하며 현재 구간이 표시됩니다. 화면 밖에 있는 영상은 보이는 위치로 이동하고, 움직임 줄이기 설정이면 즉시 이동합니다. 일시정지·전체화면은 영상 기본 조작을 사용합니다.
- 첫 재생 전 번호를 누르는 경우에도 메타데이터가 준비되면 선택한 시점으로 이동합니다. 재생이 제한되면 재생 버튼 안내를, 파일을 읽지 못하면 포스터·글 절차를 표시합니다.
- 고객용 설명에는 누를 위치·입력·결과와 가이드 링크를 둡니다. 문서 날짜나 촬영 시점을 반복하지 않고, 사용에 영향을 주는 화면 차이와 빠진 조작을 구체적으로 설명합니다. 촬영 리비전은 원본 메타데이터에서, 검증 공백은 기능 문서에서 관리합니다.
- 영상이 없는 기능은 실제 사용을 촬영한 뒤 번호·결과를 대조해 추가합니다. 현재 영상 목록에는 기존 급여 시트와 8개 앱의 대표 작업이 연결되어 있습니다. 모든 조작을 영상으로 확보한 상태는 아니므로 누락된 작업은 기능별 검증 범위에 남깁니다.
생성되는 HR 가이드는 fragments/guide-hr.html의 <!-- guide-video: payroll-sheet --> 표식을 scripts/gen-docs-guides.mjs가 플레이어로 변환합니다. 표식은 VitePress 문서용이며 독립 HTML 배포 파이프라인은 이를 렌더하지 않습니다. 기존 s1·s3-3 같은 절 링크를 유지하도록 새 영상 위치는 별도 sheet-video ID를 사용합니다. 영상·단계 자막을 수정할 때는 번호별 탐색, 무음 따라 하기, 오류 대체 표시, 기존 절 링크를 다시 확인합니다.
구현 참고: VitePress의 Vue 컴포넌트 사용, 미디어 재생 시점, 재생 요청 결과 처리.
개요 영상과 같은 촬영 형식
새 녹화는 핵심 기능 개요의 hereby-sheet-story.webm 형식을 따릅니다. 하단 검은 반투명 자막, 주황색 사각 번호, 굵은 제목과 보조 설명, 클릭 대상을 밝게 남기는 테두리·주변 어둡게 하기, 작은 실제 내용의 확대를 공통으로 사용합니다. 자막이 입력란·버튼·결과를 덮으면 모양은 유지하고 위치만 옮깁니다.
scripts/docs-capture-overlay.mjs는 촬영 브라우저에만 설치하는 공통 표식입니다. 실제 앱의 요소를 전달해 강조하고, 확대는 그 요소의 현재 보이는 텍스트를 읽습니다. 앱 번들·API 응답·실제 저장 결과는 바꾸지 않습니다. 직원 앱의 body 확대 배율이 표식 좌표에 중복 적용되지 않도록 표식은 documentElement에 붙이며, 화면 스크롤·전환 중에는 대상 위치를 다시 읽습니다. 촬영 시간표는 녹화 파일의 번호·자막과 다시 대조합니다. WebM 종료 시 길이·탐색 정보가 없으면 재인코딩 없이 컨테이너 정보만 완성하고, 속도 변경·구간 삭제 여부를 촬영 기록에 남깁니다.
재생 동작은 GuideVideo.vue, 기존 급여의 네 단계는 SheetVideoGuide.vue, 앱별 단계·시간·자산 경로는 docs/media/app-tutorials.json에서 생성한 app-video-tutorials.ts로 제공합니다. AppVideoGuide.vue는 앱 ID로 같은 정의를 가져옵니다. 새 8개 영상·포스터·촬영 출처는 docs/public/tutorials/2026-09-11/에 한 벌만 두며 페이지별로 복제하지 않습니다. withBase로 버전별 배포 경로를 처리하고, 자동 재생 없이 preload="none"을 유지합니다.
앱별 사용자 가이드 원본에는 <!-- guide-video: admin -->처럼 앱 ID 표식을 넣고 별도 app-video ID를 씁니다. h2/h3를 새로 넣어 기존 sN 절 번호를 밀지 않습니다. 팀 관리자·재고의 독립 가이드는 현재 사이트에서 제외되어 있으므로 공개된 앱 소개·기능 문서로 연결합니다. 모듈 매니저는 기능 문서가 상세 사용법입니다. 독립 HTML 빌드는 VitePress 플레이어를 렌더하지 않습니다.
다음 기록에 담을 내용
기록을 읽은 사람이 추측 없이 기능을 사용할 수 있고, 유지보수자가 변경 영향을 추적할 수 있을 만큼 작성합니다. 짧은 요약·파일 목록·PR 링크만으로 아래 내용을 대신하지 않습니다. 범위 안에서 실제 제공되는 조작을 모두 설명하며, 제공하지 않는 조작은 그 사실을 적습니다. 확인하지 못한 부분은 빈칸이나 추측 대신 미확인 범위와 이유를 남깁니다.
| 항목 | 남길 내용 |
|---|---|
| 식별·목적 | 안정적인 기능 ID, 기능이 해결하는 업무, 대상 앱·기기·사용자, 포함·제외 범위, 확인 날짜와 코드 리비전 |
| 사용 조건 | 역할·권한과 조직·팀·본인 범위, 필요한 사전 설정·선행 데이터·관련 기능 |
| 진입 경로 | 메뉴·탭·버튼의 실제 이름과 이동 순서. 직접 URL·알림·임베드 등 다른 진입 및 기기·역할별 차이 |
| 제공 조작 목록 | 조회·검색·필터·생성·수정·저장·신청·승인·반려·취소·삭제·재시도·출력·설정 중 실제 제공되는 모든 조작. 없는 조작도 구분 |
| 입력 항목 | 실제 필드명, 필수·선택, 초기값, 형식·단위·범위, 검증 메시지, 다른 필드와의 의존 관계, 개인정보 없는 구체적 예시 |
| 단계별 사용 방법 | 각 조작의 시작 조건, 누를 버튼·입력값, 실행 순서, 화면 결과, 저장되는 결과, 다음 단계. 기존 단계도 생략하지 않음 |
| 화면·동작 자료 | 실제 캡처의 단계 번호·화살표·확대와 본문을 대응. 필요한 흐름의 녹화·대표 장면·시간별 설명, 촬영 조건·버전·자료 위치, 미확보 경로와 이유 |
| 예외와 복구 | 로딩·빈 목록·권한 없음·잘못된 입력·네트워크 실패·중복 실행·취소·재시도·새로고침·재진입의 실제 동작과 복구 방법 |
| 다른 기능과의 관계 | 데이터·이벤트를 제공하는 기능, 결과가 반영되는 화면·보고서·알림·연동, 같이 변경해야 하는 조건. 기능명을 나열하지 않고 각 연결의 역할 설명 |
| 구현과 이유 | 실제 화면·상태·공용 컴포넌트·SDK·API·저장소까지의 경로, 정본 파일, 변경되는 데이터, 선택한 방식과 이유 |
| 변경 이력 | 변경 날짜, 전후 동작, 수정 이유, PR·커밋·설명 문서. 제거·대체도 기록 |
| 유지보수 | 같이 바뀌어야 하는 앱·패키지, 보존할 조건, 알려진 한계, 회귀 확인 시나리오 |
| FE 성능 해당 시 | 영향을 받는 사용 동작 전체와 연결된 기능 사용 문서, 재현·측정 순서, 지표 정의, 화면·데이터량, 장비·브라우저·네트워크·CPU·캐시 조건, 반복 횟수, 전후 수치와 원시 측정 근거 |
| 검증·작성 범위 | 조작 목록과 사용 절차를 대조한 범위. 코드만 확인한 설명·과거 검증·직접 실행한 결과·배포 상태를 구분하고 미확인·실패·미작성 항목을 구체적으로 기재 |
| 사용자 문서 영향 | 새로 설명할 기능, 달라진 조작·문구·화면, 교체할 스크린샷, 반영 대상 원본, 반영 여부와 근거 |
개발자가 변경하는 기능의 사용 흐름 전체를 보완합니다. 기능마다 docs/ko/features/<feature-id>.md를 사용하고 마스터의 ID·진입 링크를 유지합니다. 상세 문서가 현재 사용 방법과 연관 관계를 빠짐없이 담는지 확인합니다. 필요한 설명을 길이 때문에 생략하지 않으며, 조작 목록 중 설명·근거가 빠진 부분이 있으면 문서 작성 완료로 보고하지 않습니다.
이번 정리의 변경 이력
한 페이지에 섞여 있던 알림·FE 성능·작성 기준을 별도 문서로 분리하고 기능별 파일을 마스터에서 연결하도록 변경했습니다. 기존 사양·기획·과거 측정·현재 사용법을 원장으로 구분했습니다. 전체 검사 결과와 실행 범위는 검증 원장에 기록합니다.
동작 번호가 있는 급여 시트 영상을 고객이 보는 핵심 기능·HR 가이드·온보딩에도 배치했습니다. 번호 선택, 현재 구간 표시, 같은 번호의 글 설명과 상세 절 링크를 하나의 플레이어로 공유합니다. 재생 직후 일시정지에서 발생하는 AbortError는 정상 중단으로 처리해 불필요한 재생 안내가 남지 않게 했습니다. 영상 원본을 새 촬영으로 바꾸거나 급여 저장 검증을 추가한 변경은 아닙니다.
8개 앱 영상을 개요와 같은 형식으로 촬영하고 공통 재생기·단계 정의·사용자 가이드 원본 표식을 연결했습니다. 담당자별 교육 진입점과 실제 촬영 범위는 영상 목록, 검사는 원장에 기록합니다.
각 사용자 가이드 항목에 기능 영상 연결
앱별 대표 영상만 페이지 맨 위에 넣는 것으로 세부 사용법을 충족하지 않습니다. 게시 중인 가이드 6편의 88개 세부 항목을 기능별 영상 원장에 등록하고 각 항목의 진입·입력·처리·결과를 촬영합니다. 한 절의 일부 조작만 담았으면 범위를 밝히고 나머지를 미촬영으로 남깁니다.
원본 fragments/guide-*.html의 해당 제목 뒤에 <!-- guide-section-video: 영상-ID -->를 둡니다. 생성기는 이를 SectionVideoGuide로 바꾸며 기존 제목 수와 sN/sN-M 주소를 유지합니다. 공통 재생 동작은 GuideVideo.vue가 담당합니다. 영상 경로·챕터 시간·글 설명·촬영 정보의 원본은 public/tutorials/2026-09-11/sections/<영상-ID>.json이며, scripts/docs-section-videos.mjs가 읽어 section-video-tutorials.ts를 생성합니다. 생성된 레지스트리를 직접 수정하지 않습니다. gen:docs-guides는 누락/빈 미디어 파일, 범위를 벗어난 챕터 시간, 알 수 없는 영상 ID, 가이드 절과 연결 위치 불일치를 검사하고 실패 시 생성을 중단합니다. 이 동작은 scripts/docs-section-videos.test.mjs의 자동 테스트로 확인합니다. 영상·포스터는 같은 디렉터리에 한 벌만 둡니다.
새 영상도 자동 재생 없이 필요할 때 재생하며 번호 버튼으로 해당 장면을 다시 봅니다. 실패 시 포스터와 같은 번호의 글로 절차를 읽습니다. 실제 자막 프레임으로 챕터 시간을 확인하고, 촬영 전 남아 있던 모달을 초기화하며 클릭 대상이 다른 창에 가려지지 않았는지 검사합니다. 관리자 내부 iframe의 대상 강조는 바깥 화면 좌표로 변환합니다.
앱 대표 영상과 별도로 기능 영상 90편을 사용자 가이드의 88개 세부 항목에 연결했습니다. 촬영 JSON의 also는 같은 영상을 다른 절에도 배치할 때 사용하며, 각 절의 HTML 표식과 일치해야 합니다. 같은 페이지의 두 절에 재사용하더라도 표식은 각 절에 한 번씩 필요합니다. 같은 영상 파일을 다시 복제하지 않습니다.
촬영 중 도크를 여닫을 때 화면 오른쪽이 잘리면 브라우저 창의 실제 크기와 에뮬레이션 크기를 맞추고 재촬영합니다. 스크린샷이 정상이어도 녹화 프레임이 같다고 가정하지 않습니다. 완성 영상에서 번호 자막과 클릭·입력 대상이 함께 보이는지 확인합니다.
사용 설명과 촬영 메타데이터 분리
기능 문서·앱 소개·사용자 가이드·이미지 캡션·영상 설명에서 문서 작성 및 촬영 시점 안내를 걷어내고 조작 위치·입력·결과를 중심으로 정리했습니다. 가이드 HTML 원본과 공통 영상 생성기를 함께 수정해 재생성해도 같은 문구를 유지합니다. 원본 경로·촬영 JSON·동작 번호와 연결 주소는 보존합니다. 신청일·산정월 같은 업무 예시, 화면 차이, 미검증 조작은 그대로 구분합니다. 작성 규칙과 CLAUDE.md에도 같은 기준을 반영했습니다. 검사는 검증 원장에서 확인합니다.
사용자 가이드의 문장과 용어
사용자 가이드는 실제 업무 담당자가 읽고 따라 하는 문서입니다. 본문·목차·이미지 캡션·영상 아래의 번호별 설명을 버튼·동작·결과 중심으로 씁니다. 화면에 표시된 버튼·메뉴·입력란 이름은 그대로 인용하고, 이름 자체가 기술 용어이면 바로 옆에서 뜻을 설명합니다.
| 설명하려는 내용 | 사용자 가이드의 표현 |
|---|---|
| 급여 스냅샷 | 직원별 해당 월의 확정된 급여 내역 |
| 임시 스냅샷 | 이 기기에 보관한 임시 저장본 |
| 수당·공제 레코드 | 수당·공제 내역 |
| 서버 저장·재조회 | 저장한 뒤 화면을 다시 열어 결과 확인 |
| 원천 데이터·바인딩 | 해당 업무의 기초 자료와 연결된 항목 |
| 파싱 | 파일 내용 읽기 |
| 시트 수명주기 | 시트의 작업 단계 |
쉬운 표현으로 바꾸면서 실제 저장 시점, 취소·재시도 방법, 권한, 다른 기기의 조회 가능 여부를 생략하지 않습니다. 예를 들어 파일 내용 읽기와 근무표 저장을 구분하고, 확정과 입금·명세서 공개도 각각 설명합니다. API·엔티티·스키마 등의 구현 근거는 연결된 기능 개발 기록에서 관리합니다.
Codex가 가이드 원본과 온보딩·영상 목록, 영상 아래에 표시되는 제목·번호별 설명을 함께 정리했습니다. 녹화 파일·화면 속 제품 문구·동작 번호·재생 시각은 변경하지 않았습니다. 가이드는 원본에서 다시 생성하며 검증 결과는 검증 원장에 기록합니다.
관련 설명은 기능 이름으로 연결하기
다른 설명으로 안내할 때는 절 번호나 문서의 위아래 위치만 적지 않습니다. 독자가 하려는 일의 이름을 링크로 쓰고 해당 절차로 바로 연결합니다. 예를 들어 신고 버튼 안내에는 불편·기능 신고하기, 수식 수정 사유 안내에는 셀 메모 확인 방법을 연결합니다. 여러 작업을 가리킬 때는 급여 반영과 확정처럼 각각 이름과 링크를 제공합니다.
기존 제목과 주소는 유지합니다. 같은 항목 안의 특정 조작으로 이동해야 하면 그 조작에 별도 ASCII 주소를 붙입니다. 화면·영상과 맞춘 동작 번호는 그대로 두며, 링크가 존재하는지뿐 아니라 연결된 내용이 문장의 의미와 일치하는지도 확인합니다.
Codex가 관리자·HR·간호 가이드의 참조 문구와 조직 권한·연차사용촉진 기능 문서의 관련 링크를 정리했습니다. 급여대장 설명을 잘못 가리키던 수식 수정 사유의 참조는 셀 메모 설명으로 바로잡았습니다. 가이드 HTML 원본을 수정해 재생성하며 검증 원장에 확인 범위를 기록합니다.
사용 대상과 시작 위치를 표로 안내하기
각 업무의 사용 대상과 시작 위치는 한 문장에 이어 쓰지 않고 두 열의 표로 구분합니다. 원본에 시작 조건·다른 진입 방법·적용 범위가 있으면 각각 별도 행으로 씁니다. 담당자나 조건이 확인되지 않은 항목은 임의로 채우지 않습니다.
| 항목 | 안내 |
|---|---|
| 사용 대상 | 팀 관리 권한이 있는 담당자 |
| 시작 위치 | 인사 관리 > 팀 관리 |
이 표는 업무를 시작할 때 필요한 안내입니다. 입력·저장·취소·결과 확인의 번호별 절차는 이어지는 본문과 영상에 유지합니다. 기존 가이드 표의 형식을 사용하고 행과 열에 제목을 지정해 읽는 순서를 구분합니다.
Codex가 관리자·직원·HR·간호·총무·경영·재고·팀 관리자 가이드 원본 8개의 안내 89곳을 표로 바꾸었습니다. 제목·기존 링크·영상 위치는 유지하며 원본에서 다시 생성합니다. 확인 범위는 검증 원장에 기록합니다.
주간 문서·영상 작업과 Git 제외
사용자 요청에 따라 Codex가 미디어 업로드·검증용 YAML, 임시 S3 전달·등록 명령과 전용 AWS 설정 예제를 제거했습니다. 사용자의 지정 PC에만 등록한 매주 금요일 Codex 예약 작업이 병합된 기능 변경과 미완료 항목을 확인하고, 실제 사용법과 번호 영상을 갱신해 Draft 문서 PR을 준비합니다. 영상·썸네일·촬영 작업 파일·ZIP은 PC의 .docs-media/weekly/에 보관하며 Git과 PR에 포함하지 않습니다.
주간 작업·파일 전달 절차에 역할, 촬영 형식, 초안 PR 구성, 보관 폴더, ZIP과 파일 대응표, 실패·재시도와 최종 주소 연결을 기재했습니다. 완료 보고에는 초안 PR과 갱신 문서, 영상·썸네일 폴더, ZIP의 절대 경로·크기 및 미완료 항목을 포함합니다. 실제 일정은 Codex 예약 작업에서 관리하며 저장소의 YAML로 실행하지 않습니다.
기존 CDN 주소와 촬영 설명은 보존합니다. 새 영상이 아직 업로드되지 않았으면 기존 영상과 챕터를 함께 유지하고 PR에 연결 대기를 명시합니다. 최종 주소를 추측하거나 새 촬영 시각을 기존 영상에 연결하지 않습니다. 인프라가 업로드한 주소가 확인되면 해당 촬영본·썸네일·사용법·재생 목록을 함께 갱신합니다. 자동 업로드·자동 머지는 수행하지 않습니다. 사용자 가이드의 재생 UI와 번호 이동 형식은 유지합니다. 검증 범위를 따릅니다.
기능 PR과 문서·영상 PR 분리
기능 PR은 제품 구현·검토를 진행하고, 지정 PC의 주간 문서 PR은 병합된 기능을 기준으로 개발 기록·사용자 가이드·최종 촬영을 정리합니다. 일반 기능 개발 에이전트에게 문서 작성이나 후속 PR 생성 의무를 부여하지 않습니다. 이력 원본의 followUp이 담당자·기능 PR·후속 작업을 연결합니다. 문서 작업을 놓치지 않도록 추적 기록을 보존하고, 작성 완료 선언에는 실제 문서 PR 연결과 사용법 원본 변경을 검사합니다.
제품이 이미 배포됐어도 문서·영상 준비가 끝나지 않았으면 이력은 unreleased로 보관하고 확인한 배포 근거를 evidence에 남깁니다. 사용자가 바뀐 기능을 곧바로 써야 한다면 문서 반영 시점과 고객 공개 시점을 함께 조정합니다. pending을 숨기는 것은 새 기능이나 오래된 사용법을 자동으로 숨기는 기능이 아닙니다. 촬영·후속 PR 생성·이슈 완료는 에이전트의 작업이며 Actions가 자동 수행하지 않습니다. 실행 순서와 검증 범위를 확인합니다.
수동 업로드한 전체 영상·썸네일 연결
Codex가 인프라에서 제공한 https://works-static.dev.hereby.me/docs/에 기존 파일명을 붙여 영상 99편과 썸네일 99개를 연결했습니다. 전체 397,572,380바이트를 원본과 SHA-256·크기·MIME으로 대조했고, 99편 모두 실제 구간 응답도 일치했습니다. 앱 개요 8개와 기능별 90개는 촬영 JSON에 영상·이미지 URL과 external 확인 근거를 함께 기록하며, 별도 급여 시트 영상은 기존 컴포넌트의 두 주소만 변경합니다.
실제 사용 위치는 앱별 소개, 사용자 가이드 영상 목록, 급여 시트 따라 하기입니다. 고객은 기존 재생 버튼과 번호를 그대로 사용하고, 같은 영상 ID를 쓰는 문서들은 공통 재생 목록을 통해 함께 바뀝니다. 기존 촬영의 번호·시각·설명·연결 위치를 보존했으며 사용자 기능을 다시 실행하거나 재촬영하지 않았습니다.
전체 연결 중 팀 관리자·재고관리·모듈 매니저의 기존 ko/apps 사용법 링크가 촬영 검사에서 거부되는 누락을 확인했습니다. validateCapture가 고객 앱 소개 경로를 허용하도록 보완하고, 내부 importer·system-admin 및 외부·경로 이탈 주소를 계속 거부하는 회귀 검사를 추가했습니다. 링크의 실제 대상이나 사용자 설명은 바꾸지 않았습니다.
파일 연결·교체·복구는 수동 업로드 연결 절차, 확인 범위는 검증 원장을 따릅니다. Codex가 이번 문서 PR에서 추가했던 영상·썸네일 98쌍을 로컬 보관 폴더로 옮기고 Git에서 제외했습니다. 촬영 JSON과 생성 목록은 CDN 주소를 유지하며, 기존 파일 재추가를 허용하던 목록도 비워 재유입을 차단합니다. 랜딩 데모가 사용하는 기존 급여 시트 한 쌍은 보존하고, 문서의 해당 재생기만 CDN 주소를 사용합니다. 고객 문서 배포·AWS 자동 등록 실행·Git 이력 재작성은 수행하지 않았습니다. 제외 범위와 복구를 함께 확인합니다.