qa-report-humanizer

問題を何も伝えない洗練された QA レポートより、何が壊れたかを伝える粗削りなレポートのほうが優れています。 「認証モジュールで重大な欠陥が特定されました」は、あらゆる文法チェックを通過しますが、読み手には何も伝わりません。このスキルは、QA レポート、バグレポート、テストサマリー、ステータス更新を書き換え、実際のエンジニアが対応できる内容にします。また、元の文章にない数値、エラー、重要度を絶対に作り出さないことを保証します。

確認事項

まず .agents/qa-project-context.md を確認してください。チームの文体、トラッカー、重要度の規則が記載されています。そこで回答されている質問は省略してください。そのうえで、書き換えに影響する点だけを確認します。

• 誰が読みますか。エンジニア、経営幹部、それとも顧客ですか？ エンジニアには失敗したセレクターと再現手順が必要です。経営幹部にはリリース可否と未解決のブロッカーが必要です。顧客には影響とスケジュールが必要です。相手によって文体と削る情報が変わります。
• どのチャネルで使いますか。Slack、PR コメント、それとも正式なレポートですか？ Slack なら 2～3 行とリンク、PR コメントなら具体的なコードやセレクターの修正、レポートなら構成が必要です。長さと書式はチャネルに合わせます。
• 数値と重要度は、そのまま維持すべき確定情報ですか？ 元の文章に「9 件失敗」「P1」とあれば、変更せず引き継ぎます。数値が欠けている場合は、その不足を明記してください。作り出してはいけません（コア原則 5 を参照）。

コア原則

1. 網羅性より具体性を優先します。「メールアドレスにプラス記号が含まれるとログインに失敗する」は、「認証に関するさまざまなエッジケースが見つかりました」より優れています。前者なら読み手は修正でき、後者からは何も学べません。挙動、発生条件、影響範囲を明記してください。

2. 分類名ではなく、何が起きたかを書きます。「認証モジュール」は分類名ですが、「プラス記号を含むメールアドレスでログインする」はバグです。分類名を使うと、書き手は詳細を把握していないことを隠しながら、網羅的に見せることができます。分類名はすべて、その中にある具体的な事象に置き換えてください。

3. 何が壊れたのか、何をすべきなのかが読み手にわからなければ、レポートとして失敗です。 金曜の午後 4 時に修正する担当者に向けて書いてください。壊れているもの、またはリスクがあるものから始め、それに対して何をすべきかを示します。誰も読まない部分は省いてください。

4. すべての事実を残し、形容詞はすべて削ります。 書き換えるのは文章表現であり、データではありません。数値、エラー文字列、重要度、バグの説明、テスト結果を変更してはいけません。削除してよいのは、情報ではなく、冗長表現、曖昧な表現、同義語の重ね使いだけです。

5. 追加を求められた具体情報を、決して作り出してはいけません。「具体的にして」という指示は、モデルに正確な割合、インシデント件数、あるいは見たことのない再現手順を捏造させるおそれがあります。そうしてはいけません。元の文章が曖昧で、数値を検証できない場合は、「ユーザーへの影響は未測定」のように不足情報を正直に示してください。「ユーザーの 8%」などと書いてはいけません。指標の捏造は、曖昧な記述よりも深刻な失敗です。

検出して修正する QA 特有の AI パターン

それぞれについて、悪い例、書き換え例、理由を示します。最も有害なパターンであるテンプレートの書き出しは全文を掲載し、ほかは簡潔に示します。

1. テンプレートの書き出し（最も問題のあるパターン）

悪い例：

Sprint 47 のテスト実行は正常に完了しました。5 つのテストスイートで合計 342 件のテストケースを実行し、合格率は 97.4% でした。以下のセクションでは、結果の詳細を説明します。

改善例：

Sprint 47：342 件のテストを実行し、9 件失敗。うち 6 件はチェックアウト（支払いフォームの検証）での失敗です。残り 3 件は、以前にも発生した不安定なタイミングの問題です。

理由：最初の例は前置きに埋もれて、重要な情報が見えません。2 つ目の例なら、何が起きたのか、どこを調べるべきかが 1 行でわかります。

2. 深刻さを誇張する表現

悪い例：「認証モジュールで重大な欠陥が確認され、複数のタッチポイントでユーザー体験に影響する可能性があります。」 良い例：「メールアドレスに+が含まれているとログインできません。アナリティクスを確認したところ、ユーザーの約8％がプラス記号を含むメールアドレスを使っています。リリース前に修正が必要です。」

理由：「認証モジュールの重大な欠陥」は分類にすぎませんが、「メールアドレスにプラス記号が含まれているとログインできない」なら修正できます。（ここでの8％は、ソースに記載された独自のアナリティクスの数値です。ソースにない数値を追加しないでください。）

3. 合格率への執着

悪い例：「全体の合格率は94.2％から97.1％に上昇し、大幅な改善を示すとともに、チームの品質への取り組みを示しています。」 良い例：「合格率は94％から97％になりました。その大半は、ダッシュボードの読み込み時にタイムアウトを繰り返していた不安定なPlaywrightテスト3件の修正によるものです。実際に見つかったバグは2件です（どちらも新しいエクスポート機能に関するものです）。」

理由：合格率は、背景がなければ見栄えだけの指標です。実際に何が変わったのかを伝えてください。

4. 汎用的なリスク表現

悪い例：「慎重な監視が必要な高リスク領域がいくつか特定されています。チームは、引き続き警戒を怠らず、積極的にテストすることを推奨します。」 良い例：「決済フローでは、3D SecureカードのE2Eテストがありません。過去6か月で、この問題による本番環境のインシデントが2回発生しています。管理パネルの作業より、こちらを優先したいです。」

理由：「高リスク領域」や「引き続き警戒」では何も伝わりません。対象領域とリスクを明示し、何をすべきか述べてください。

5. テスト結果を言い換え続ける

悪い例：「認証テストは正常に合格しました。ログイン検証スイートは問題なく完了しました。認証情報の検証チェックで良好な結果が得られました。サインインのワークフローテストは想定どおり実行されました。」 良い例：「すべての認証テストに合格しました（ログイン、登録、パスワードのリセット、SSO）。」

理由：「認証テストに合格した」を4通りで言う必要はありません。1つの結果には、動詞を1つ使えば十分です。

6. 「課題はありましたが」で締めくくる

悪い例：「テストフェーズでいくつかの課題に直面したものの、チームは予定していたすべてのテスト活動を無事完了しました。今後は継続的な改善に注力します。」 良い例：「今スプリントではモバイルブラウザーのテストまで手が回りませんでした。チェックアウトのリグレッション対応で時間切れになりました。これらのテストは次のスプリントに持ち越します。それ以外はすべて完了しています。」

理由：未完了の内容とその理由を示し、次に持ち越す計画を伝えてください。「課題はありましたが」という言い回しは不要です。

7. 曖昧な関係者向けの報告

悪い例：「品質指標は引き続き良好な傾向です。チームは優先事項について認識を共有しており、高品質なリリースを実現することに取り組んでいます。」 良い例：「リリースに問題はなさそうです。未解決のバグは4件で、すべてP2以下です。P1のログイン時にプラス記号を含むメールアドレスが使えないバグは、昨日修正しました。ステージング環境でスモークテストに合格しています。」

理由：リリース可否と未解決のブロッカーから始めてください。読み手が判断したいのはそこです。

8. 何も伝えないPRレビューコメント

悪い例：「素晴らしい実装ですね！テストカバレッジと堅牢性を全体的に高める、改善の余地がありそうな箇所をいくつか見つけました。」 良い例：「このテストでは正常系しか確認していません。APIが429を返した場合はどうなりますか？また、セレクター.btn-submitは、CSSクラスを変更すると動かなくなります。代わりにgetByRole('button', { name: 'Submit' })を使ってください。」

理由：不足しているシナリオと壊れやすい行を示し、具体的な修正方法を伝えてください。getByRoleは、ユーザーが目にする要素を特定するためにPlaywrightが推奨するロケーターです。CSSクラスのセレクターよりもこちらを優先してください。

9. バグ報告の水増し（再現手順と証拠を添える）

悪い例：「ユーザー管理モジュールの包括的な回帰テストを実施するなかで、システムの中核機能に影響する重大な不具合が見つかりました。」 良い例：

ユーザーを削除しても API トークンが失効せず、削除後も API を呼び出せます。 再現手順：ユーザーを作成し、トークンを発行して、DELETE /api/users/{id} を実行したあと、そのトークンで GET /api/me を実行します。 401 Unauthorized ではなく、ユーザーのデータとともに 200 OK が返ります。ユーザー管理 API で見つかりました。

理由：「発見されました」という受け身の表現やテスト実施の前置きをやめ、問題の挙動を最初に述べます。2 行の再現手順と実際のエラー／ステータスを示せば、修正担当者は数秒で再現できます。

10. 3 つの美徳を並べる要約

悪い例：「今スプリントでは、品質、スピード、自信が向上しました。チームは優れた連携、技術力、顧客重視の姿勢を発揮しました。」 良い例：「今スプリントでは、決済の不安定さを解消しました（失敗率は 12％ から 1％ 未満に低下）。新しいエクスポート機能の E2E テストも追加しました。」

理由：スプリントの要約で 3 つの抽象的な美徳を三段論法のように並べるのは、AI らしさが最も強く出る表現です。実際に起きた 2 つのことに置き換えましょう。

書き換え方

1. 冒頭の段落を削る。 導入の大半は前置きにすぎません。最初に役立つ事実より前の部分はすべて削除します。
2. 重要なことを最初に書く。 何が壊れましたか？何がリスクですか？何をすべきですか？これらを最初に書きます。
3. 分類名を具体的な内容に置き換える。 「認証モジュール」→「プラス記号を含むメールアドレスでログインする」。「パフォーマンスの低下」→「ダッシュボードの読み込みに 8 秒かかる（以前は 2 秒）」。「複数のエッジケース」→「空のカート、期限切れのクーポン、通貨の不一致」。
4. 水増し表現をなくす。 references/filler-blocklist.md にある表現をすべて削除します。「注目すべき点として」「今後は」「困難はありましたが」「チームは〜に取り組んでいます」「関係者は安心できます」など、すべてが対象です。
5. 役立つ情報を加える。ただし、作り上げない。 読者は次に何をすべきですか？対応しない場合のリスクは何ですか？どの程度確信がありますか（正直に書きましょう。「まだ安定しているか確信がありません」でも問題ありません）。主張を裏付ける数値が元の資料にない場合は、その旨を伝え、数値を捏造しないでください。
6. 声に出して読む。 スタンドアップで言わないような表現なら、書き直しましょう。

形式ごとのガイダンス

形式	最初に書くこと	省くこと	併せて含めること
テスト実行の要約	失敗件数、発生箇所、新たに発生したものかどうか	総件数、合格率（求められた場合を除く）	まだカバーされていない範囲、注意すべき点
バグ報告	何が壊れるか、再現方法、影響を受ける人	「包括的なテストを実施するなかで……」	実際のエラーメッセージ、ステータスコード、スクリーンショット、またはコンソール出力
スプリント報告（関係者向け）	リリース可能かどうか（可能／不可／条件付き）、未解決のブロッカー	手法、プロセス、チームの士気に関する記述	リリースするかどうかを判断する立場なら知りたいこと
Slack メッセージ	結果を 2〜3 行で述べ、リンクを添える	挨拶、「共有したいことがあります……」	—
ポストモーテム	何が壊れたか、いつ起きたか、どのくらい続いたか、誰が影響を受けたか	「このポストモーテムの目的は……」	見落としたこととその理由についての率直な説明

Slack の例 — 悪い例：「チームのみなさん、最新のテスト実行結果を共有したいと思います……」 良い例：「E2E の実行は合格しました。不安定な失敗が 2 件ありました（どちらも既知の問題であるダッシュボードのタイムアウトです）。全レポート：[link]」

アンチパターン

• 追加するよう求められた内容をでっち上げる。 元の情報にない割合、インシデント件数、再現手順を作り、曖昧な草稿を具体的に聞こえる文章に書き換えることです。これは事実を保持するという保証を損ないます。情報が不足していることを明記してください。
• テストに失敗しているのに「テスト実行は正常に完了しました」で始める。 冒頭と本文が矛盾します。失敗から始めてください。
• 実際の影響の代わりに「潜在的な影響」と書く。 影響が分かっているなら明記し、分からないなら未測定としてください。「潜在的」という表現は、どちらなのかを曖昧にする逃げ道です。
• どんな文脈でも「チーム内で認識が一致しています」と書く。 情報をまったく伝えず、AI らしさが露呈するだけです。
• 同じ内容を言い換えて、3 つの箇条書きを 12 個に水増しする。 類義語を並べるだけです。結果は 1 つにつき 1 文で述べてください。
• 情報を加えない楽観的な表現で締めくくる。 「今後は継続的な改善に注力していきます」などは削除してください。
• 何が壊れたのかを明記しないために受動態を使う。 「問題が特定されました」では、何が問題なのかが分かりません。何が、どこで壊れたのかを明記してください。
• バグではなくテストセッションからバグレポートを始める。 「モジュールの回帰テストを実施中に」は不要です。壊れた動作から始めてください。

検証

事実を保持するという約束（基本原則 4）は、最も重要な主張です。機械的に、最小のチェックから検証してください。

1. 数値と重大度が保持されている。 入力と出力からすべての数値を抽出し、差分を確認します。出力の集合は入力の集合の部分集合でなければなりません。出力に入力にない情報があれば、事実の捏造です。

   grep -oE '[0-9]+(\.[0-9]+)?%?|P[0-3]|[0-9]{3}' input.md  | sort -u > /tmp/in.txt
   grep -oE '[0-9]+(\.[0-9]+)?%?|P[0-3]|[0-9]{3}' output.md | sort -u > /tmp/out.txt
   comm -13 /tmp/in.txt /tmp/out.txt   # must be empty (allow only obvious rounding, e.g. 97.4 -> 97)
   

2. フィラーブロックリストに一致する項目がない。 references/filler-blocklist.md の「Grep-ready regex」の行を BLOCKLIST にコピーし、出力に対して grep を実行します。

   BLOCKLIST='it('\''?s)? worth noting|moving forward|in conclusion|despite (several )?challenges|the team is (committed|aligned)|stakeholders can feel confident'
   grep -iE "$BLOCKLIST" output.md   # expect no output; extend BLOCKLIST with the full regex from the reference
   

   一致した箇所は AI らしさが残っています。その行を書き直してください。
3. 2 回目のチェックを通過する。 グローバルの humanizer（または avoid-ai-writing）スキルを検出モードで実行し、出力を確認します。ダッシュの過剰使用、三段論法、曖昧な帰属表現が残っていないことを確認してください。このスキルが見逃した QA 固有の指摘があれば、ここでも修正してください。

完了条件

• 出力内の数値、重大度、エラー文字列、バグの説明がすべて入力にも存在する（検証手順 1 の comm -13 の差分が、丸めの違いを除いて空である）。
• フィラーブロックリストの正規表現が、出力に対して一致を返さない（検証手順 2）。
• 類義語を並べていない。同じテスト結果を複数回述べていない（「合格／問題なく完了／良好な結果を返した」のような連続表現がない）。
• 出力がグローバルの humanizer／avoid-ai-writing によるチェックを通過し、指摘されるパターンがない（検証手順 3）。
• 納品物は書き直したバージョンです。元の草稿はアーカイブするか破棄し、納品物と一緒に提出しないでください。

関連スキル

• ai-bug-triage — バグレポートのテンプレートと重大度／優先度マトリックスです。トリアージでは、バグの内容と分類方法を判断します。このスキルでは、分類済みのレポートの文章を書き直します。
• qa-metrics — 実際に追跡すべき指標です。レポートに実際の指標を記載する場合に使用します。このスキルでは、見栄えだけの数値ではなく、文脈を添えて指標を示せるようにします。
• qa-dashboard — ダッシュボードの設定と関係者向けレポートのレイアウトです。このスキルでは、ダッシュボードに添える説明文を読みやすく整えます。
• quality-postmortem — ポストモーテムの構成と根本原因分析です。ポストモーテムはそこで作成し、説明文はこちらで読みやすく整えてください。

外部スキル

これらはグローバルの Claude スキルセットにあり、このリポジトリの skills/ ディレクトリにはありません。

• humanizer ／ avoid-ai-writing — AI らしい文章を避ける汎用エンジンです。両方を使う場合は、言語レベルの調整（ダッシュの過剰使用、三段論法、曖昧な帰属表現）にグローバルスキルを実行し、QA 固有の構成と事実の保持にはこのスキルを使ってください。エンジニア本人の実際のスタンドアップや Slack での文体が分かる場合は、サンプルをグローバル humanizer の voice モードに入力し、一般的な「人間らしい」文体ではなく、その人の文体に合わせて書き直してください。

参照ファイル（references/ 内）

• filler-blocklist.md — 禁止されている冗長な表現のコピー＆ペースト用ブロックリスト、検証で使用する grep 用正規表現、類義語の不自然な使い回しの兆候、受動態を使った「誰が壊したのか」を曖昧にする表現。