c0sogi/meeting-minutes

韓国語議事録 HWPX 作成

音声・映像または文字起こしデータに基づいて公式な韓国語議事録を作成し、有効な .hwpx ファイルとして提供します。文字起こしデータがない場合は、最初に meetdown で Markdown 文字起こしデータを作成します。現在の範囲は HWPX 生成までであり、PDF 変換は行いません。

実行環境

• ファイルシステムとシェル実行権限を使用します。
• Python コマンドとパッケージの実行には uv と uvx を使用します。音声文字起こしツール meetdown==0.2.1 は Python 3.12 以上を必要とします。
• 音声文字起こしにはネットワーク接続と、CLOVA Speech、OpenAI、または Gemini のいずれかの認証情報が必要です。
• 認証情報は環境変数で提供します。Claude Code プラグインとしてインストールした場合はプラグイン設定に入力することもでき、両方がある場合はプラグイン設定値を優先します。
• 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

使用可能なツールに transcribe_meeting がある場合は、上記コマンドの代わりにこのツールを呼び出します。プラグイン設定に入力した認証情報はこのツールにのみ渡されます。input_path と output_path は絶対パスで指定し、以下のオプションは同じ意味のパラメータ（chunk_duration など）で渡します。

長いファイルの単一アップロードが失敗した場合、またはプロバイダーの制限が明確な場合のみ、以下のオプションで再試行します。

--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 が欠落またはパースできない
• 期待されるフレーズが欠落
• 文書タイトルまたは節タイトルが太字でない
• 強調が要求されたが青色太字スタイルがない
• 未完成のプレースホルダーが残っている

検証はファイルの ZIP・XML・内容・書式設定の検査で完了します。Hancom Office の実行、Computer Use、スクリーンショットによる画面確認は行いません。

8. 成果物と報告

状況に応じて以下を作成します。

• 文字起こしが必要だった場合 transcript.md
• transcript.inspect.json
• minutes.json
• minutes.audit.json
• 未確定項目がある場合 minutes.review.md
• 最終 .hwpx

最終報告形式:

完了
- HWPX: <パス>
- 文字起こし: <パスまたは既存文字起こしを使用>
- 検証: 合格 | 警告あり
- 確認事項: なし | 核心項目の要約

エラー処理

• 認証情報がない場合は、必要な環境変数名を案内し、Claude Code では /plugin の hwpx プラグイン設定に入力できることも併せて案内します。秘密値をチャットに入力するよう要求しません。
• 容量・時間制限の場合は --chunk-duration 10m で再試行します。
• 文字起こしの信頼度が低い場合は、固有名詞や数値を恣意的に修正せず、確認項目に残します。
• HWPX レンダリングが失敗した場合は、原因を報告し、破損ファイルを成果物として提供しません。
• PDF を要求された場合は、現在のスキル範囲外であることを伝え、別途変換環境が必要であると案内します。

自己チェック

スキルインストール後、またはスクリプト・テンプレートを修正した後に実行します。

uv run scripts/self_test.py

この検査は音声認識 API を呼び出さず、文字起こしデータのパース、JSON 検証、HWPX 生成と構造検証を実行します。