audio-notes

audio-notes — エージェント向け作業手順

これはClaude Codeが従う指示書です。プロジェクトの概要・背景・人間向けの使い方は README.md にあります。

このリポジトリには性質の異なる2種類の作業がある。「音声原稿（ノート）を作る」（下記セクション）と「リポジトリ自体のファイルを編集する」（コード・設定を変更するときの開発ルールセクション）は手順もルールも別物なので、混同しないこと。

「〇〇について調査してください」と頼まれたときの手順（音声原稿の作成・公開）

これがこのリポジトリでの標準タスクです。以下を順番に、断りなく最後まで実行してください（途中で確認を挟む必要はありません）。

1. 調査してMarkdown原稿を作ります topic-to-audio-script スキルの指示に従い、指定されたトピックを調査し、音声読み上げ用に最適化したMarkdown原稿を作成します。
   • ファイル名は英数字とハイフンのスラグにします（例: oku-no-hosomichi.md）。日本語のトピック名からローマ字化します。
   • notes/ ディレクトリの直下に保存します（リポジトリのルート直下には置きません）。ノートが増えるたびにリポジトリのルートが散らかるのを防ぐためです。
   • 既存のノートを読み直したり、リポジトリ内の他のファイルを調べ回ったりしません。 過去のノートは今回のタスクと無関係なので、コンテキストに含めません。
2. MarkdownをHTMLに変換します（スクリプトに任せる）

   python3 build_note.py <ファイル名>.md "<記事タイトル>"
   

   • <ファイル名>.md は notes/ ディレクトリの直下にあるものとして指定します（notes/ というプレフィックスは付けません）。スクリプトが自動的に notes/ 配下を読み書きします。
   • <記事タイトル> は原稿の内容にふさわしい短いタイトルを自分で決めて渡します。原稿本文と違い、タイトルにはアルファベットを使ってかまいません（例: Appshots(アップショッツ)とは何か）。タイトルは耳で聞くより目で見て識別するものなので、カタカナだけだと読みにくくなるためです。
   • pandoc が入っていなければ apt-get install -y pandoc（または環境に応じた方法）でインストールします。
   • HTMLは自分で組み立てず、必ずこのスクリプト経由で生成します。 note-template.html と build_note.py の中身は、iPhoneのEdgeで読み上げが確実に動くことを検証済みの形式なので、書き換えません。

3. コミットしてmainへ直接pushします 生成された notes/<ファイル名>.md と notes/<ファイル名>.html の両方を git add → git commit → git push で、ブランチを切らず、PRも作らずに main ブランチへ直接pushします。これは下記「コード・設定を変更するときの開発ルール」のPR必須ルールの対象外となる、この手順専用の例外運用です。

4. 公開URLを組み立てます push後、以下の形でGitHub Pagesに公開されます（反映まで数十秒〜1分ほどかかることがあります）。

   https://soh-arch.github.io/audio-notes/notes/<ファイル名>.html
   

5. SlackにURLを投稿します 投稿先チャンネルは環境変数 AUDIO_NOTES_SLACK_CHANNEL_ID の値に従います。この値はワークスペース固有の情報のため、公開リポジトリのどのファイルにもコミットせず、実行環境（セッション/CI）の環境変数として渡します。 このセッションで使えるSlack向けのツール・連携（Slack MCP、Incoming Webhookなど、環境にあるもの）を使って、そのチャンネルへ上記URLを短いメッセージと共に投稿します。例:「『<記事タイトル>』を公開しました: 」
   • AUDIO_NOTES_SLACK_CHANNEL_ID が設定されていない、または使えるSlack手段が見当たらない場合は、その旨と生成済みのURLを最終応答にはっきり書き、投稿だけは諦めます。
6. 最終応答の前に、Slack投稿を済ませたか自分でチェックします GitHub Pagesの反映待ち（手順4）に気を取られて、そのままSlack投稿（手順5）を忘れて完了報告してしまうことがあります。最終応答を返す前に、Slack投稿ツールを実際に呼び出し、その実行結果（投稿されたメッセージへのリンクなど）を得られているかを必ず確認します。確認できていなければ、応答を終える前に手順5を実行します。

変更してはいけないもの

• note-template.html（デザイン・DOM構造とも、Edgeの読み上げ動作を実機検証済みのため。本文がJavaScriptで後から差し込まれる形に戻すと読み上げが壊れる）
• build_note.py の変換方針そのもの（Markdown→HTML変換はpandoc経由のスクリプトに固定し、エージェントが毎回HTMLを手書きしない）

この2つを固定している理由（他の配信形式ではEdgeの読み上げが動かないこと）は、README.mdの「なぜこの構成なのか」に書いてある。変更を検討する前に必ずそちらを読むこと。

コード・設定を変更するときの開発ルール（リポジトリ自体のファイル編集）

これは上記の「音声原稿の作成・公開」手順（1〜6）とは別物のルールである。build_note.py や note-template.html、CLAUDE.md、.claude/ 配下のスキルなど、音声原稿そのものではなくリポジトリ自体のコードや設定を変更する場合にのみ、以下に従う。

• コミットメッセージは英語で、Conventional Commitsの形式で書く。
• PRのタイトル・説明も英語のみで書く。
• 既存のPRに追加のコミットを積む前に、そのPRがまだcloseされていないか確認する。
• 機能的にまとまった単位ごとに1つのPRを作る。
• 保護されたブランチ（mainなど）へは直接pushせず、PR経由でmergeする。ノート公開手順3で .md/.html をmainへ直接pushするのは、この規約の対象外の既存運用とする。
• 複雑な作業に着手する前は、簡単に計画を述べ、必要に応じてユーザーと方針をすり合わせる。
• ファイル名・フォルダ名はシンプルで簡潔な英語にする。
• コメント: 自己言及的なコメントやコメントアウトされたコードは、コードベースが明示的に必要とする場合や、時間経過後・他の作業完了後に見直すべき点を示す場合を除いて残さない。過剰な注釈は不要。セクション区切りやファイル冒頭のコメントは軽い構造化装飾として問題ない。行末コメントは、それがないとコードの意図が読み取れない場合の最小限にとどめる。