Communitygithub.com

work-brochure

ユーザーに作業完了内容を視覚的なHTMLブローシャー(フローチャート、変更前後のスクリーンショット、決定事項、ファイルマップ、差分抜粋、検証結果)で提示し、チャットでの通常のテキスト要約に加えて提供します。

work-brochure とは?

このスキル「work-brochure」は、開発作業の完了時やPull Request作成時に、チャットのテキスト要約に加えて、視覚的なHTMLブローシャーを自動生成します。ブローシャーは自己完結型のHTMLページで、Mermaid図(フローチャート、シーケンス図、状態図など)、実際のアプリケーションのスクリーンショット(変更前後)、ファイルマップ、差分抜粋、決定テーブル、検証結果などを含み、コードベースの変更を直感的に理解できるように設計されています。Claude CodeやCursor、CodexなどのAIエージェントプラットフォームで動作し、特にPR作成後のフックで自動的に起動するよう設定できます。同梱の`gather.sh`スクリプトがgitの差分情報を収集し、テンプレートHTMLを元に一貫したスケッチブック風のデザインでページを構築します。生成されたブローシャーは`.claude/work-briefs/`に保存され、Gitの管理対象外となり、またプライベートアーティファクトとして永続化されます。

対応✓Claude Code~Codex CLI~Cursor
npx skills add https://github.com/lincolncrooks/work-brochure/tree/HEAD/skills/work-brochure

お気に入りのAIに質問する

このエージェントスキルを事前に読み込んだ状態で新しいチャットを開きます。

ドキュメント

ワークブローシャー

作業を終えた後、ユーザーは次の2つを求めています。

  1. チャットでの通常の要約 - これまで通り、何が変わったか、現在の状態、未完了の事項を記述します。このスキルがそれを置き換えたり短縮したりすることはありません。
  2. ブローシャー - 1つの自己完結型HTMLページで、同じ作業を視覚的に説明します。ユーザーはチャットの横に開いて、図やスクリーンショット、注釈付きコードを通じて変更内容を理解できます。段落を読む必要はありません。

ブローシャーはコードに対して正確でなければなりません。すべての主張、数値、ファイルパス、スクリーンショットは、実際の差分、実行したコマンド、確認したアプリケーションに基づいています。実行していないテストや確認していない結果を決して作り出してはいけません。

手順

1. まずチャット用の要約を書く

通常通り作業を完了し、通常のテキスト要約とwrap_up(アプリが備えている場合)を含めます。その後でブローシャーを作成します。ユーザーが以前の作業のブローシャーのみを依頼した場合は、手順2に直接進みます。

PRが作成された後(プラグインのPostToolUseフック、または設定内のフックがgh pr create後にリマインダーを追加します)、同じターンでgather.sh --pr <N>を実行してそのPRのブローシャーを作成し、ブローシャーへのリンクをクロージングメッセージに含めます。ユーザーが依頼しない限り、PR本文を編集してリンクを追加しないでください。PRが些細な1行変更(タイポ、バージョン番号の変更)の場合のみスキップします。

2. 情報を収集する

リポジトリルートからヘルパースクリプトを実行します(コミット、フォルダーごとにグループ化されたファイルごとの差分統計、未コミットの変更、PR情報を出力します):

bash <skill-dir>/scripts/gather.sh            # このブランチ vs main + 未コミット
bash <skill-dir>/scripts/gather.sh A..B       # 任意のgit範囲(例:すでにマージ済みの作業)
bash <skill-dir>/scripts/gather.sh --pr 51    # GitHub PR

次に、差分の重要な部分を読みます(git diff <range> -- <path>)。すべてを読む必要はありません。また、この会話からも情報を収集します:

  • 理由:ユーザー自身の言葉による問題やリクエスト。
  • 決定事項:検討した選択肢と、その中からこれを選んだ理由。
  • 検証:実行したコマンドと実際の出力、取得したスクリーンショット、ブラウザやシミュレーターで確認した内容、そして確認できなかった内容。
  • 未完了事項:フォローアップ、リスク、残っている作業。
  • ユーザーの判断が必要なこと:ユーザーだけが決定、目視確認、承認できること。

3. 実際のアプリをキャプチャする(変更が可視的な場合)

変更がUIに現れる場合、ブローシャーには実際のアプリケーションを表示し、説明文だけで済ませてはいけません。

  • 変更後:プレビューツール(プロジェクトのlaunch.jsonのサーバーを使ったpreview_start、ナビゲート、computer {action: "screenshot"})、またはiOSシミュレーターのscreenshotを使用して、変更後の画面のスクリーンショットを取得します。レイアウトが変更された場合は、デスクトップと電話の両方の幅でキャプチャします。
  • 変更前:差分がポイントである場合、基本リビジョンをスクラッチパッドに一時的なワークツリーとしてチェックアウトし(git worktree add <scratchpad>/before <base>)、別のポートでサーブし、同じビューをスクリーンショットし、その後ワークツリーを削除します(git worktree remove)。変更が純粋に追加的であったり、「変更前」が何ももたらさない場合はスキップします。
  • スクリーンショットをスクラッチパッドにファイルとして保存し、縮小します(sips -Z 1400 -s format jpeg -s formatOptions 78 in.png --out out.jpg)、そしてdata: URIとして埋め込みます。ページ全体を約8MB以下に保ちます。
  • 動画やアニメーションの変更の場合は、いくつかの静止画(ffmpeg -ss <t> -i clip.mp4 -frames:v 1 -vf scale=900:-1 still.jpg)またはフレームストリップを、測定値とともに埋め込みます。
  • 非可視的な変更(スクリプト、データ、バックエンド)の場合は、スクリーンショットの代わりに図と実際の出力を使用します。

4. ストーリーを計画し、ビジュアルを選ぶ

ユーザーが説明を望む順序でページを構成します。最初に結果、次に仕組み、最後に詳細です。変更内容に基づいてビジュアルを選びます。テキストよりも図で説明する方が速い場合には図を優先し、文章は短いキャプションと1~3文の段落に留めます。

変更内容使用するビジュアル
ロジック、パイプライン、決定ルール新しいフローのMermaid flowchart。新規/変更されたノードを classDef changed で強調
コンポーネント間のリクエスト(UI→API→ストレージ)Mermaid sequenceDiagram
構造(モジュール、ファイル、データ形状)+/− バー付きファイルマップ。接続を示すMermaid graph。変更前後のフィールドテーブル
UI変更前/後のスクリーンショットペア。画像上に番号付きコールアウトを注釈
数値(タイミング、サイズ、カウント、パフォーマンス)実寸で描かれたインラインSVG棒グラフ(変更前 vs 変更後)
状態やライフサイクルMermaid stateDiagram-v2
一連の作業(移行、複数ステップの変更)番号付きウォークスルーステップ(順序が実際に重要な場合のみ)
重要なコード短い差分抜粋(5~25行)。重要な行にマークを付け、<details> 内に配置してページを支配しないようにする

機能サイズの変更には少なくとも3つ以上の異なるビジュアルを、それより小さい変更には少なくとも1つを目指します。図は実際のメカニズム(実際の関数名、ファイル名、値)を説明し、一般的なボックスを使用してはいけません。

5. テンプレートからページを構築する

<skill-dir>/template.html をコピーして内容を埋めます。テンプレートにはスケッチパッドの外観(意図的に1つのライトテーマ:方眼紙の背景、手書き風見出し、鉛筆描きのカード、手描き図)、レイアウト、および上記のすべてのコンポーネントがすでに含まれています。ユーザーが依頼しない限り、ダークモードを追加したり、見た目を変更したりしないでください。ルール:

  • <style> ブロックとMermaidローダースクリプトは保持し、サンプルコンテンツを置き換えます。該当しないセクションは薄い内容のまま残すのではなく削除します(例:純粋なリファクタリングでは「変更前→変更後」は不要)。
  • <title>:機能の名前を2~4単語で(例:「チェックアウト再試行ロジック」)。「作業概要:…」ではありません。
  • ヒーロー:結果についての1文、メタ行(ブランチ、PRリンク、日付)、統計バー(ファイル数、行数 +/−、コミット数、チェック通過数)。数値はgather.shから計算し、推定しないこと。
  • あなたの入力を待つ項目(ヒーローの下に付箋):ユーザーを待っている実際の依頼のみ、1行ずつ、どこを見るべきか明記。最大3つ。該当なしの場合はノート全体を削除し、埋め合わせしないこと。
  • なぜこの方法か(決定テーブル):セッションで実際に検討された2~4の選択肢、1つを「採用」とマーク、各選択肢のトレードオフを1行で。埋め合わせのために選択肢をでっち上げないこと。実際に選択が行われなかった場合はセクションを削除。
  • ページを簡潔に保つ:上記2つと該当するセクションのみ。テンプレートを超えてセクションを追加しないこと。
  • ファイルマップ:意味のあるファイルごとに1行(生成ファイルやバイナリファイルは1行にまとめる)、+/− バーの幅は最大ファイルの合計に対するパーセンテージ、さらにそのファイルがなぜ変更されたのかを平易な英語で1行。
  • 差分抜粋:<、>、& をエスケープ。class="add"、class="del"、または class="hl"(重要な変更のない行)で行をマーク。
  • Mermaidは <pre class="mermaid"> に記述し、タグの直後にテンプレートのconfigブロック(--- / config: / look: handDrawn / theme: neutral / ---)を置き、ローカルファイルとclaude.aiの両方で手描き風にレンダリングされるようにします。テンプレートの classDef changed fill:#dfe7ff,stroke:#1f4fd1,stroke-width:2px 行は保持。ラベル内の </> は &lt;/&gt; にエスケープし、この作業で追加・変更されたものには class <ids> changed を使用。各ダイアグラムは約5~9ノードに抑え、1画面に収まるようにします。連続するステップは1つのノードにまとめ、<br/> で詳細行を追加。長いフローは2つの図に分割。短いチェーンには flowchart LR、分岐があるものには TD を使用。
  • 検証:各チェックを pass / fail / not-checked のチップとその証拠(出力抜粋またはスクリーンショット)とともにリスト。存在する場合、「未チェック」項目は必須。
  • 平易に書く:短い文、ユーザーの用語、冗長さなし。

<repo-root>/.claude/work-briefs/<YYYY-MM-DD>-<slug>.html として保存します。このフォルダーはすべてのリポジトリでGitの管理対象外に保ち、各リポジトリの .gitignore に触れずにローカル除外ファイルに1回追加します:

mkdir -p .claude/work-briefs && x="$(git rev-parse --git-common-dir)/info/exclude" && (grep -qxF '.claude/work-briefs/' "$x" 2>/dev/null || echo '.claude/work-briefs/' >> "$x")

6. 1回確認して、配信する

  1. ブラウザペインで1回開き(preview_start に url: file://<path> またはプロジェクトの静的サーバーを使用)、図がレンダリングされ、オーバーフローがないことを1枚のスクリーンショットで確認します。その1回の表示で問題を修正し、ループしないこと。
  2. サイドパネルに表示:SendUserFile で display: "render" を使用。
  3. プライベートアーティファクトとして公開(Artifact 公開、ファイルパス、icon: "document"、および1文の説明付き)。これにより、ワークツリーがクリーンアップされた後も永続化されます。これが永続的なコピーです。アーティファクトはデフォルトでプライベートです。Artifactツールが利用できない場合(例:プレーンなターミナルセッション)はスキップし、ローカルパスを提供します。
  4. チャットで、通常の要約の後に、ブローシャーへのリンクとローカルファイルパスを1行追加します。

更新:ユーザーが変更を要求した場合、同じファイルを編集し、同じパスに再公開してリンクが同じままになるようにします。

良いブローシャーの例

  • セッションに参加していなかった人が、2分以内のスクロールで何が変わったか、なぜ変わったかを理解できる。
  • 最初の画面で、「何が変わったのか?」がスクロールせずにわかる。
  • すべての図、チャート、スクリーンショットがこの変更に関するもの。
  • 正直な状況が可視化されている:何が検証されたか、されなかったか、何が残っているか。

関連スキル