c0sogi/write-korean-meeting-minutes-hwpx

한국어 회의록 HWPX 작성

음성·영상 또는 전사본을 근거로 공식 한국어 회의록을 작성하고, 유효한 .hwpx 파일로 제공한다. 전사본이 없으면 먼저 meetdown으로 Markdown 전사본을 만든다. 현재 범위는 HWPX 생성까지이며 PDF 변환은 수행하지 않는다.

실행 환경

• 파일시스템과 셸 실행 권한을 사용한다.
• Python 명령과 패키지 실행에는 uv와 uvx를 사용한다. 음성 전사 도구 meetdown==0.2.1은 Python 3.12 이상을 요구한다.
• 음성 전사에는 네트워크 연결과 CLOVA Speech, OpenAI 또는 Gemini 중 하나의 인증정보가 필요하다.
• HWPX 작성은 번들 템플릿과 Python 표준 라이브러리 기반 스크립트를 사용한다.

반드시 지킬 원칙

• 회의 일시, 장소, 참석자, 화자 실명, 담당자, 기한, 결정, 수치, 고유명사를 추정하지 않는다.
• meetdown의 Created at은 전사본 생성 시각이며 회의 일시가 아니다.
• A, B, [[SPEAKER_1]] 같은 표시는 실명이 아니므로 사용자에게 받은 화자 매핑이 있을 때만 이름으로 바꾼다.
• 제안, 우려, 결정, 후속 조치, 미결 사항을 구분한다.
• 여러 번 나온 아이디어를 자동으로 결정 사항으로 올리지 않는다.
• 초기 의견과 회의 말미의 명시적 합의가 다르면 마지막 합의나 지시를 우선한다.
• “여기”, “이 그림”, “이쪽”처럼 화면을 가리키는 발언은 참고 자료가 없으면 구체화하지 않는다.
• API 키를 명령 인자, 로그, Markdown, JSON, HWPX 또는 최종 답변에 노출하지 않는다.
• 문서 제목과 절·소절 제목은 굵게 표시한다.
• 중요한 결정·결론·후속 조치의 짧은 구절만 파란색 #2F5597과 굵기로 강조한다. 본문 대부분을 파란색으로 만들지 않는다.

포함된 자료

상황에 맞는 자료만 읽는다.

• references/meetdown-guide.md: 전사본이 없거나 meetdown 실행이 실패했을 때 읽는다.
• references/minutes-writing.md: 전사 내용을 회의록으로 재구성하기 전에 읽는다.
• references/hwpx-template.md: HWPX 템플릿을 작성·교체·수정할 때 읽는다.
• references/installation.md: 설치 위치나 운영자 설정을 안내할 때 읽는다.
• references/evaluation.md: 스킬 수정 후 회귀 테스트를 설계할 때 읽는다.
• assets/minutes.schema.json: minutes.json 구조의 기준이다.
• assets/example-minutes.json: 문안이 아니라 데이터 구조의 예시로만 사용한다.
• assets/example-audit.json: 근거 장부 형식의 예시다.
• assets/meeting-minutes-template.hwpx: 기본 회의록 양식이다.

사용할 스크립트

모든 경로는 스킬 루트를 기준으로 한다.

• scripts/transcribe.py: meetdown을 비대화형으로 실행하고 비밀값을 보호한다.
• scripts/inspect_transcript.py: meetdown Markdown의 구조와 위험 요소를 검사한다.
• scripts/validate_minutes.py: HWPX 작성 전 minutes.json을 검증한다.
• scripts/render_hwpx.py: 구조화된 내용을 HWPX 템플릿에 반영한다.
• scripts/validate_hwpx.py: ZIP·XML·필수 문구·굵기·파란색 강조를 검사한다.
• scripts/validate_skill.py: Agent Skills 핵심 규칙을 검사한다.
• scripts/self_test.py: 네트워크 없이 전체 로컬 절차를 점검한다.

작업 순서

진행 상태:

• 1. 입력 파일과 기준 자료를 분류한다.
• 2. 전사본이 없으면 meetdown으로 전사한다.
• 3. 전사 구조와 품질을 검사한다.
• 4. 근거 장부를 작성한다.
• 5. minutes.json을 작성하고 검증한다.
• 6. HWPX를 생성한다.
• 7. HWPX를 검증하고 오류를 수정한다.
• 8. 산출물과 확인 필요 사항을 보고한다.

1. 입력 자료 분류

다음 우선순위를 적용한다.

1. 사용자가 확정한 회의 메타데이터, 화자 매핑, 용어 표기, 수정사항
2. 실제 회의에서 사용한 안건지, 발표자료, RFP, 참석자 명단 등 참고 자료
3. 타임스탬프와 화자가 있는 유효한 전사본
4. 타임스탬프 없는 전체 전사문
5. 형식이 명시된 경우에만 파일명의 날짜 힌트

입력별 처리:

• 유효한 전사 Markdown이 있으면 그대로 사용하고 같은 녹음을 다시 전사하지 않는다.
• 음성·영상만 있으면 회의록 작성 전에 전사한다.
• 전사본과 녹음이 모두 있으면 전사본을 우선한다. 전사본이 비었거나 깨졌거나 다른 회의 내용일 때만 다시 전사한다.
• 여러 녹음은 각각 전사한다. 같은 회의의 연속 녹음임이 확인될 때만 파일 순서를 보존해 합친다.
• 녹음과 전사본이 없으면 회의 메모가 충분한 경우에만 검토본을 작성한다. 근거가 부족하면 회의 내용을 만들어내지 않는다.

2. 필요할 때 전사

전사 전 references/meetdown-guide.md를 읽는다.

한국어 회의와 CLOVA Speech의 기본 실행:

uv run scripts/transcribe.py "<녹음파일>" \
  -o "<전사본.md>" \
  --provider clova \
  --language ko-KR

긴 파일의 단일 업로드가 실패하거나 제공자 제한이 명확할 때만 다음 옵션으로 재시도한다.

--chunk-duration 10m

기본 압축은 smallest를 사용한다. 압축 때문에 전사 품질이 떨어진 근거가 있을 때만 lossless로 재시도한다. 여러 사람이 참여한 회의에서는 특별한 이유가 없으면 화자 분리를 유지한다.

전사 후 반드시 검사한다.

uv run scripts/inspect_transcript.py "<전사본.md>" \
  -o "<전사본.inspect.json>"

빈 파일, HTML 오류 페이지, 사용할 수 있는 전체 전사와 타임스탬프 구간이 모두 없는 파일로는 회의록을 작성하지 않는다.

3. 메타데이터 정리

확인된 경우 다음 값을 기록한다.

• 안건
• 일시
• 책임기관
• 장소
• 참석인원
• 주요안건
• 화자 매핑
• 인명·기관명·과제명·제품명·기술 용어의 확정 표기

중요도가 낮은 메타데이터가 없더라도 작업을 중단하지 않는다. 검토본을 만들고 해당 셀에 확인 필요를 적으며 quality.missing_metadata에 기록한다. 완전한 최종본이 반드시 필요한데 결과가 크게 달라지는 정보만 추가로 확인한다.

4. 근거 장부 작성

최종 문안을 쓰기 전에 minutes.audit.json을 만든다. 중요 내용마다 다음 형식을 사용한다.

{
  "type": "fact | proposal | concern | decision | action | open_question",
  "statement": "정규화한 짧은 내용",
  "source": "전사본 또는 참고 자료 파일명",
  "speaker": "A 또는 확인된 실명",
  "start": "00:42:02",
  "end": "00:42:10",
  "confidence": "high | medium | low"
}

분류 기준:

• fact: 회의에서 확인되거나 설명된 사실
• proposal: 제안, 아이디어, 선택지
• concern: 반론, 위험, 제약
• decision: 명시적인 동의, 선택, 확정, 승인, 지시
• action: 수행하기로 한 구체적 업무
• open_question: 결론이 나지 않은 사항

후속 조치에는 과업이 반드시 있어야 한다. 담당자와 기한은 근거가 있을 때만 채운다.

5. 회의록 데이터 작성

references/minutes-writing.md와 assets/minutes.schema.json을 따른다. assets/example-minutes.json은 구조만 참고하고 내용은 복사하지 않는다.

필수 문서 구조:

• 회 의 록
• 상단 메타데이터 표
• 회 의 내 용
  • 회의 요지
  • 2. 주요 논의
  • 2.1 이후 주제별 논의, 보통 3~7개
• 회 의 결 과
  • [요약]
  • [후속 조치]
  • 필요할 때만 [확인 필요 사항]

문체는 간결하고 중립적인 한국어 업무 문체로 작성한다. 기본 종결은 -함, -하기로 함, -논의됨, -필요함, -판단됨을 사용한다. 추임새, 말더듬, 반복, 무관한 잡담은 제거하되 결정의 근거가 되는 반론·기술적 제약·비용·일정은 남긴다.

파란색으로 표시할 구절은 emphasis 배열에 본문과 완전히 동일한 짧은 문자열로 넣는다. 중요한 항목은 important: true로 표시한다.

검증:

uv run scripts/validate_minutes.py "<minutes.json>"

오류는 모두 수정한다. 누락 메타데이터, 본문에 없는 강조 구절, 과도한 강조 비율, 너무 긴 문단 경고도 검토한다.

6. HWPX 생성

사용자가 호환되는 양식을 제공하지 않았다면 기본 템플릿을 사용한다.

uv run scripts/render_hwpx.py \
  --template assets/meeting-minutes-template.hwpx \
  --data "<minutes.json>" \
  --output "<최종회의록.hwpx>"

렌더러는 표 구조와 기존 문단 스타일을 유지하고, 제목·소제목을 굵게 하며, 지정된 핵심 구절을 #2F5597과 굵기로 표시한다. 내용이 길어져도 글자 크기를 과도하게 줄이지 말고 다음 페이지로 자연스럽게 이어지게 한다.

사용자가 상당히 다른 HWPX 양식을 제공하면 무작정 실행하지 않는다. references/hwpx-template.md에 따라 표 셀 주소와 본문 문단 구조를 먼저 확인하고 렌더러를 조정한다.

7. HWPX 검증

uv run scripts/validate_hwpx.py "<최종회의록.hwpx>" \
  --expect-data "<minutes.json>"

검증 실패 시 JSON 또는 템플릿을 수정하고 다시 생성한다. 다음 상태의 파일은 전달하지 않는다.

• mimetype가 첫 ZIP 항목이 아니거나 압축되어 있음
• 필수 XML이 누락되거나 파싱되지 않음
• 기대 문구가 누락됨
• 문서 제목 또는 절 제목이 굵지 않음
• 강조를 요청했지만 파란색 굵은 스타일이 없음
• 미완성 플레이스홀더가 남아 있음

한컴오피스를 사용할 수 있으면 파일을 직접 열어 표 테두리, 글꼴 대체, 페이지 흐름, 잘린 문장, 마지막 문단을 확인한다. 실제로 열어보지 않았다면 시각 검수를 완료했다고 말하지 않는다.

8. 산출물과 보고

상황에 따라 다음을 만든다.

• 전사가 필요했던 경우 transcript.md
• transcript.inspect.json
• minutes.json
• minutes.audit.json
• 미확정 항목이 있으면 minutes.review.md
• 최종 .hwpx

최종 보고 형식:

완료
- HWPX: <경로>
- 전사본: <경로 또는 기존 전사본 사용>
- 검증: 통과 | 경고 있음
- 확인 필요: 없음 | 핵심 항목 요약

실패 처리

• 인증정보가 없으면 필요한 환경변수 이름만 안내하고 비밀값을 채팅에 입력하도록 요구하지 않는다.
• 용량·시간 제한이면 --chunk-duration 10m으로 재시도한다.
• 전사 신뢰도가 낮으면 고유명사와 숫자를 임의로 고치지 않고 검토 항목에 남긴다.
• HWPX 렌더링이 실패하면 원인을 보고하고 손상 파일을 결과물로 제공하지 않는다.
• PDF를 요구받으면 현재 스킬 범위 밖임을 밝히고 별도 변환 환경이 필요하다고 안내한다.

자체 점검

스킬 설치 후 또는 스크립트·템플릿을 수정한 뒤 실행한다.

uv run scripts/self_test.py

이 검사는 음성인식 API를 호출하지 않고 전사본 파싱, JSON 검증, HWPX 생성과 구조 검증을 수행한다.