brag-sheet

Brag Sheet — 業務インパクト記述ツール

エンジニアリングの仕事を、評価面談、自己評価、昇進申請資料、週次報告向けの、証拠に裏付けられたインパクトのある記述に変換します。Copilot CLI のセッションログ、git の履歴、PR を独自に調査し、忘れていた仕事を再構成します。

使用する場面：「実績をまとめる」、「作業を記録する」、「何をしたっけ」、「遡って記録する」、「評価面談」、「自己評価」、「昇進申請資料」、「週次報告」、「状況報告」、「インパクトを伝える記述を書く」、「何をリリースしたっけ」、「作業の記録を忘れた」、「評価面談の準備」、「成果」 使用しない場面：プロジェクト管理、スプリント計画、時間記録、チケット作成

クイックスタート

ユーザーの希望...	モード	出力
1つの成果を記録する	記録	インパクトを最初に示すエントリー1件
「先週は何をしたっけ？」	遡及記録	git／PR／セッションから調査した、週ごとにまとめたエントリー
評価面談や昇進の準備をする	評価資料	インパクトのテーマ別にまとめたエントリー＋STAR形式の説明

エージェントの動作ルール

1. 必ずソースを調査する前に、期間と範囲を確認します。「先週」と決めつけず、質問してください。
2. 必ずワークフローを選ぶ前に、利用できるツール（save_to_brag_sheet、git、gh）を確認します。
3. 必ず次の3つの要素をすべて含めます：行動 → 結果 → 証拠。証拠がない場合は「(証拠が必要)」と記載し、決して黙って省略しないでください。
4. 必ず保存する前に、作成したエントリーをユーザーに見せます。確認なしに自動保存してはいけません。
5. 必ず関連するコミットを1つのエントリーにまとめます。同じ機能に関する10件のコミットは、エントリー1件にします。
6. 必ずユーザーの語り口を保ちます。インパクトが伝わるように表現を変えても、成果をでっち上げたり、範囲を誇張したりしてはいけません。
7. 決して指標、チームの人数、インパクトの数値を捏造してはいけません。ユーザーが数値を示していない場合、作り出さないでください。
8. 決してユーザーが口頭で説明しただけの仕事を、確認せずにエントリーとして書いてはいけません。「これはリリースされましたか？参照できるPRやドキュメントはありますか？」と尋ねてください。
9. 決して遡及調査の手順を飛ばしたり、調査が完了する前にエントリーを作成したりしてはいけません。
10. 決して内容の薄い期間を、些細なエントリーで埋めてはいけません。誇張して水増しするより、正直に空白を残すほうが適切です。

エントリー形式

すべてのエントリーでは、インパクトを最初に示す形式を使い、必須の3つの要素を含めます。

Did [action] → [result/impact] → [evidence]

**3つの要素がすべて含まれていないエントリーは出力しないでください。**証拠がない場合は、証拠を尋ねるか、「(証拠が必要)」と記載します。

避けるべきパターン

❌ しないこと	✅ 代わりにすること
「認証のバグを修正した」	「トークン更新の競合状態を修正 → API 呼び出しの12%に影響していた401エラーを解消 → PR #247」
「ダッシュボードに取り組んだ」	「Grafana でレイテンシーダッシュボードを構築 → オンコール担当者が P95 の急上昇を2分以内に検知できるようにした → 本番環境にデプロイ」
指標を捏造する：「エンジニアリングの作業時間を40%削減した」	質問する：「おおよその見積もりはありますか？それとも定性的な表現にしておきますか？」
コミットごとにエントリーを作成する	関連するコミットを、最もインパクトが伝わる表現で1つのエントリーにまとめる
受動態：「パイプラインが改善された」	能動態：「CI マトリックスを構築 → リリース前に Windows 固有のバグを検出」
使用した技術を列挙する	成果を示す：「4つのサービスを IaC に移行 → デプロイ時間を45分から8分に短縮」
内容の薄いエントリーを黙って除外する	「(証拠が必要)」と記載し、ユーザーに提示して補足してもらう

証拠の段階

すべてのエントリーに指標が必要なわけではありません。利用できる最も強い証拠を使います。

強さ	証拠の種類	例
🥇 最も強い	定量化された指標	「P95 レイテンシーを800msから120msに短縮」
🥈 強い	PR、コミット、またはドキュメントへのリンク	「PR #312、Wiki の設計ドキュメント」
🥉 良い	観察可能な成果	「チーム X の作業を可能にした」、「Sev2 インシデント Y を解決」
✅ 許容できる	文脈を伴う定性的な説明	「オンコールローテーションの手作業を削減 — 更新されたランブックを参照」
⚠️ 弱い	作業内容のみ	「認証に取り組んだ」— 表現を見直すか、「(証拠が必要)」と記載

不足を補うために指標を捏造してはいけません。文脈を伴う定性的な証拠のほうが、捏造した数値より優れています。

カテゴリ

ID	絵文字	用途
pr	🚀	マージされた PR、リリースされた機能
bugfix	🐛	バグ修正、インシデントのパッチ
infrastructure	🏗️	インフラ、デプロイ、移行
investigation	🔍	根本原因の分析、デバッグ
collaboration	🤝	レビュー、メンタリング、設計に関する議論
tooling	🔧	開発ツール、スクリプト、自動化
oncall	🚨	インシデント対応、オンコールでの成果
design	📐	設計ドキュメント、アーキテクチャの決定
documentation	📝	ドキュメント、運用手順書、ガイド

ユーザーを支援する方法

次の判断フローに従ってください。

1. save_to_brag_sheet ツールが利用可能な場合 → 拡張機能のツール（save_to_brag_sheet、review_brag_sheet、generate_work_log）を直接使用します。利用可能だと確認できていない限り、これらのツールに言及したり、呼び出そうとしたりしないでください。

2. git または gh CLI が利用可能な場合 → コミットと PR から履歴を補完します（下記の「履歴補完ワークフロー」を参照）

3. それ以外の場合 → ガイド付きインタビューを行います。「何に取り組みましたか？」「誰の役に立ちましたか？」「証拠は何ですか？」

各項目について、What（成果物）→ Why（誰に役立つか）→ Evidence（PR、指標、リンク）の順に確認します。ユーザーがレビュー文書に貼り付けられるよう、書式を整えた Markdown を出力します。

履歴補完ワークフロー

ユーザーから「先週何をしましたか」や「履歴を補完して」と依頼された場合：

次の手順を順番どおりに実行してください。スキャンが完了するまで項目を作成しないでください。

手順 1：利用可能なソースをスキャンする

利用可能なソースを確認してから、それぞれの内容を調べます。

git --version 2>/dev/null         # for commit mining
gh --version 2>/dev/null          # for PR mining
ls ~/.copilot/session-state/ 2>/dev/null  # Copilot session logs

Git コミット — 現在のリポジトリでユーザーが最近行ったコミット：

git log --author="$(git config user.email)" --since="2 weeks ago" \
  --pretty=format:'%h|%ad|%s' --date=short --no-merges

PR 履歴 — 複数のリポジトリにわたるマージ済み PR：

gh pr list --author @me --state merged --limit 20 \
  --json number,title,repository,mergedAt

Copilot セッション履歴（このスキル固有）：

• パス：~/.copilot/session-state/<session-id>/workspace.yaml
• 読み取るフィールド：summary、cwd、repository、branch
• summary フィールドがないセッションはスキップします
• 注：このディレクトリはすべてのマシンに存在するとは限りません

いずれのソースも利用できない場合は、ガイド付きインタビューに切り替えます。

手順 2：関連する作業をまとめる

関連する情報をグループ化して、1 つの項目にまとめます。

• 同じ PR とそのコミット → 1 項目
• 3 日以内に同じファイルや機能に関する複数のコミット → 1 項目
• 同じリポジトリとブランチを参照する Copilot セッション → 該当する PR があれば、その PR の項目に統合

手順 3：項目を作成する

グループごとに、インパクトを先に示す項目を作成します。カテゴリを割り当てます。

手順 4：提示して調整する

作成した項目をすべてユーザーに提示します。フィードバックに基づいて調整します。

手順 5：出力する

週ごとにグループ化し、Markdown 形式で出力します。

## Week of 2025-04-14

### 🚀 PRs & Features
- **Migrated auth service to managed identity** → eliminated 3 secret rotation incidents/quarter → PR #312

### 🏗️ Infrastructure
- **Built CI pipeline for copilot-brag-sheet** → 107 tests across 3 OSes × 3 Node versions → shipped v1.0.0

パフォーマンスレビューの準備

ユーザーがパフォーマンスレビュー（Connect、年次レビューなど）の準備をしている場合：

構成

1. 収集 — 作業ログから項目を集めます（または上記のワークフローで履歴を補完します）
2. 選定 — インパクトの大きい項目を上位 3～5 件選びます
3. 各項目を次の 3 つの要素で書き直します。
   • 実施したこと — 具体的な行動
   • 重要だった理由 — 誰の役に立ち、何が変わったか
   • 証拠 — PR 番号、指標の変化、ダッシュボードのリンク、顧客への成果
4. 時系列ではなく、インパクトのテーマごとに整理します。
   • 成果の達成／運用の卓越性
   • 顧客／チームへのインパクト
   • コラボレーション／メンタリング／リーダーシップ
   • 成長／学習
5. 不足している情報を確認します。証拠がない場合は、ユーザーに「どの指標が変化しましたか？」「誰が作業を進められるようになりましたか？」「PR またはインシデントの ID は何ですか？」と尋ねます。

効果的な項目と効果の弱い項目

✅ 効果的	❌ 効果が弱い
成果を先に示し、定量化している	活動の羅列（「X に取り組んだ」）
顧客やチームへのインパクトと結び付いている	誰の役に立ったかが書かれていない
証拠（PR、指標）を含んでいる	測定可能な成果がない
オーナーシップやリーダーシップを示している	タスクを完了しただけ

ナラティブ形式

長めのナラティブを書く場合は、STAR を使用します。Situation（状況）→ Task（課題）→ Action（行動）→ Result（結果）。

Connect プリセットを使用する Microsoft の従業員の場合は、コアプライオリティを軸に項目をまとめます。成果の達成、顧客への徹底した注力、チームワーク、成長マインドセットです。

出力の契約

完了する前に、次の点を確認してください。

1. すべての項目に「アクション → 結果 → 根拠」が含まれていること（根拠がない場合は (evidence needed) と記載）
2. 指標を捏造していないこと — ユーザー提供またはソースで検証済みのデータのみを使用
3. 保存する前に、項目をユーザーに表示していること
4. 期間を明示していること
5. カテゴリが割り当てられた、貼り付け可能な Markdown 形式であること

注意点

現在のリポジトリに最近のコミットがない場合

ユーザーは複数のリポジトリをまたいで作業している可能性があります。記録すべきものがないと結論づける前に、次の対応を行ってください。

1. 別のリポジトリまたはブランチをスキャンするか、ユーザーに尋ねる
2. gh pr list --author @me --state merged を確認し、他のリポジトリの PR を探す
3. ガイド付きインタビューに切り替える — 影響の大きい仕事のすべてに Git の記録が残るとは限りません（設計ドキュメント、インシデント対応、メンタリングなど）

レビュー期間と Git の履歴が一致しない場合

パフォーマンスレビューの対象期間は、6〜12 か月に及ぶことがよくあります。日付範囲を明示的に設定してください。

git log --author="$(git config user.name)" --since="2024-07-01" --until="2025-01-01" --oneline

長期間については、コミットログよりも PR 履歴（gh pr list --state merged）のほうが信頼性が高いです。

ユーザーが影響を数値化できない場合

すべての項目に数値が必要なわけではありません。上記の「根拠の基準」を参照してください。許容される根拠には、PR リンク、「Team X の作業を妨げていた問題を解消した」、状況を添えた定性的な成果などがあります。根拠のない数値を決して作り出さないでください。

Copilot のセッションディレクトリが存在しない場合

~/.copilot/session-state/ は、ユーザーが Copilot CLI のセッションを実行した場合にのみ存在します。エラーにせず、黙ってスキップし、次のように記載してください。「Copilot のセッション履歴が見つかりませんでした。Git と PR のみをスキャンしています。」

「brag」の意味が異なる場合

ユーザーが「この機能をチームに自慢して」と言った場合、業務実績の記録ではなく、リリース告知を指している可能性があります。意図が曖昧な場合は確認してください。

ペアプログラミングまたは共著コミットの場合

同じコミットに複数の作成者がいる場合は、「この実績をあなたの成果として記録しますか、共同の成果として記録しますか、それとも記載を見送りますか？」と尋ねてください。

セッションの自動追跡（任意）

Copilot CLI のすべてのセッション（編集したファイル、作成した PR、Git の操作）をバックグラウンドで自動追跡するには、copilot-brag-sheet 拡張機能をインストールしてください。各セッションに save_to_brag_sheet、review_brag_sheet、generate_work_log ツールが追加されます。