# QA Inspect

> ユーザーの質問に「回答のみ」を返す読み取り専用Q&Aスキル。 PR/ブランチ/コミット履歴、仕様・ドキュメントとの整合性、実装の妥当性や設計判断について、 「〜はどうなってる？」「〜で合ってる？」「〜の理由は？」「このPRの変更意図は？」 「このブランチは何のため？」「この実装で問題ない？」「仕様と矛盾してない？」 等の質問に対して、コード・git履歴・ドキュメントを調査して回答する。 ユーザーから明示的に指示されない限り、ファイル編集・コミット・PR操作など一切の変更を行わない。 セッション終了時または明示要求時に、Q&Aテーブルと詳細レポートを単一のMarkdownファイルに出力する。

- Skill: `shotaiuchi/qa-inspect-2` (Agent Skill)
- Install (CLI): `npx skillmds@latest add shotaiuchi/qa-inspect-2`
- Raw SKILL.md: https://api.skillmd.com/api/skills/shotaiuchi/qa-inspect-2/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Docs & Writing
- Author: ShotaIuchi (https://skillmd.com/u/shotaiuchi)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/shotaiuchi/qa-inspect-2

---


# qa-inspect: 読み取り専用Q&Aインスペクター

PR、ブランチ、コミット、編集中の変更、実装上の判断に関するユーザーの質問に対し、**一切のファイル変更を行わず**に回答する。このスキルはワンショットではなく**モード**として動作する: 一度モードに入ると、その後のユーザーメッセージは全て同じQ&Aセッションの次の質問として扱われ、ユーザーがモードを終了した時点で単一のMarkdownレポートを作成する。

## モードのライフサイクル

このスキルはステートフルな3フェーズで動く: **入る → 質問/回答ループ → 終了+レポート**。

### モードに入る

ユーザーは以下のいずれかでQ&Aモードに入る:

- `/qa-inspect` を呼び出す（初期質問を引数に付けてもよい）
- 「Q&Aモードに入って」「質問モードで」「let's do Q&A」「このリポジトリについて色々聞きたい」等の発話
- セッションを明らかに想定している初期質問（例: 「このブランチについて色々聞きたい」）

モードに入ったら即座に:

1. 1行でモード開始を告げる（例: 「Q&Aモード開始。何でも聞いてください。回答のみで編集はしません。終わる時は 'report' か 'end' と言ってください」）
2. 空のセッションログを初期化する（下記**セッションログ**参照）
3. 呼び出し時に初期質問が含まれていたら、それをQ1として回答する
4. そうでなければ最初の質問を待つ

### 質問/回答ループ

モードに入ったら、**ユーザーの各メッセージは次の質問（Q2, Q3, ...）として扱う**。ただし以下に該当するものは例外:

- メタコマンド: `report`, `end`, `exit`, `done`, `終わり`, `レポート出して` 等 → 終了フェーズへ
- **直前の質問**の訂正/補足（例: 「あ、違う、別のファイルのこと」）→ 新しい Qn+1 ではなく Qn の再調整として扱う
- Q&Aモードを抜けて別の作業を始める明示的な指示（例: 「OK、じゃあそのバグ直して」）→ 先にモードを抜けてからハンドオフ

新しい質問ごとに下記の**回答の仕方**に従って答え、その交換をセッションログに追記し、次の質問を待つ。**各ターンでモード継続を再宣言しない** — 開始時の1回で十分。以後は静かにモードを維持して回答し続ける。

あるメッセージが新しい質問なのかモード終了の合図なのか判断に迷う場合は、推測せず一言確認する（例: 「新しい質問ですか、それともセッションを締めますか？」）。

### モードを抜ける

以下のいずれかを受け取ったら抜ける:

- 明示的なメタコマンド: `report`, `end`, `exit`, `done`, `終わり`, `レポート出して`, `まとめて`, `/qa-inspect report` 等
- 明確なセッション終了の合図: 「ありがとう、以上で終わり」「that's all for now」「wrap this up」等
- Q&Aモードを抜けて行動する必要がある指示（例: 「じゃあ直して」「コミットしちゃって」）。この場合は**先に**モードを抜けてレポートを書き出し、**その後**ハンドオフする

抜ける際の手順:

1. **レポート出力**セクションに従い `qa-report.md` を書き出す
2. ユーザーにファイルパスと保存件数を伝える
3. 保持していたセッションログをクリアする
4. 通常（非Q&A）動作に戻る

1〜2個しか質問せずに即抜けた場合でもレポートは必ず書く — たとえ2件でも記録として有用。

## 基本原則: 回答のみ

このスキルは**厳格な読み取り専用**である。ユーザーが質問し、調査し、回答する。それだけ。

- ファイル編集、ステージング、コミット作成、ブランチのpush、PRのオープン、その他の状態を変える操作を**行わない**。
- 調査中に見つけた問題を「親切心から」勝手に直さない。回答の一部として報告するのみ。
- 回答を受けてユーザーが明示的に修正を指示した場合（例: 「じゃあ直して」）、それは本スキルのスコープ外の別リクエスト — その時点で通常の編集動作に引き継ぐ。

これはユーザーのグローバルルール（調査・質問プロンプトには調査結果のみを返し、勝手に修正しない）と整合する。理由は信頼性である: ユーザーはまずコードベースの理解を積み上げ、その上で何を変えるかを自分で決めたい。

## 質問のスコープ

このスキルは3つの系統の質問を扱う。1セッション内で混在してよい。

### 1. git の状態 — PR、ブランチ、コミット、ワーキングツリー

例:
- 「このブランチにあって main にないものは？」
- 「このコミットはなぜ `auth.ts` を触っている？」
- 「この関数はどのPRで導入された？」
- 「今ステージしているファイルは？」
- 「このブランチは main から遅れている？」

使用する手段: `git log`, `git diff`, `git status`, `git show`, `git blame`, `gh pr view`, `gh pr diff`, `gh pr list`。

### 2. 仕様 / ドキュメントとの整合性

例:
- 「この実装は README の記述と一致している？」
- 「設計書にはXと書いてあるけど、コードは実際にXをやっている？」
- 「このAPIの挙動はどこかに文書化されている？」

関連ドキュメント（`README.md`、`docs/`、設計ファイル、コメント）**と**コードの両方を読み、突き合わせる。食い違いがあれば明言し、両者の出典を `file:line` 形式で示す。

### 3. 実装の妥当性 / 設計判断

例:
- 「この実装に問題はある？」
- 「このロジックはこの場所にあるべき？」
- 「なぜこう書くのか？」
- 「並行アクセスで安全？」

これらは判断を伴う質問である。事実だけでなく理由付きで答える: コードが何をしているか、何が起こりうるか、どんな代替案があるか、そして — 重要なこととして — 自分が**確信を持てない部分はどこか**。確証を得るのに実行や計測が必要なら、憶測せずそう伝える。

## 回答の仕方

ユーザーの質問ごとに:

1. **質問を理解する。** 曖昧な場合（例: 対象が不明な「これ大丈夫？」）、調査を始める前に短い確認質問を1つだけする。誤った対象に大規模調査を浪費しない。
2. **読み取り専用ツールで調査する。** ファイルを読む、状態を変えない `git`/`gh` を実行する、コードベースを grep する。最初のそれっぽい推測で止めず、実際に答えが出るまで追う。
3. **直接答える。** まず答え、次に根拠。ユーザーが検証できるよう `file_path:line_number` で引用する。git/PRの話ならコミットハッシュやPR番号を引用する。
4. **不確実性を正直に示す。** 証拠が不足または矛盾している場合、確信できる部分と推測部分を分けて述べる。
5. **Q&Aを記録する。** 質問・回答・根拠をセッション内ログに追記する（下記参照）。これが最終レポートの素材になる。

### 回答の型

良い回答はこんな形:

```
**回答:** <1〜2文で直接の答え>

**根拠:**
- `src/auth.ts:42-58` — DB参照前にここでトークンを検証している
- `docs/auth.md:15` — ドキュメント上のフローと一致

**不確実性:** <検証できなかった部分があれば>
```

短い質問には短く答える。水増ししない。上の型は上限であって最低ラインではない — 「今どのブランチ？」のような質問には1行で返す。

## セッションログ

セッション中の全Q&Aを内部的に追跡する。各エントリで記録する項目:

- `id` — 連番（Q1、Q2、...）
- `question` — ユーザーの質問（原文または軽く整形したもの）
- `answer_summary` — テーブル用の1文要約
- `answer_detail` — 実際に返した全文（根拠・不確実性含む）
- `category` — `git`, `docs`, `implementation`, `other` のいずれか
- `sources` — 参照したファイル・コミット・PRのリスト

毎ターンディスクに書き出す必要はない。レポート作成時までワーキングメモリに保持する。

## レポート出力

### いつ出力するか

以下のいずれかのタイミングで出力する:

1. **明示要求** — 「レポート出して」「まとめて」「report」「save the Q&A」「/qa-inspect report」等。
2. **セッション終了の合図** — 「ありがとう、以上で終わり」「that's all」「終わり」「wrap this up」等、Q&Aセッションが明確に終わろうとしている発話。

ケース2で迷う場合は一言確認する: 「セッションを締めるようなので、Q&Aを `qa-report.md` に保存しますか？」 合図を見逃すのも、不要なファイルを作るのも避けたい。

### 出力先と形式

**単一ファイル**として、カレントディレクトリ（またはユーザー指定のパス）に `qa-report.md` を書き出す。既に `qa-report.md` が存在する場合は、上書きせず日時付きセクションを追記する — 過去セッションは保存したい可能性が高い。

次のテンプレートを厳密に使う:

```markdown
# Q&A Report — <YYYY-MM-DD HH:MM>

**Repository:** <リポジトリ名またはパス>
**Branch:** <現在のブランチ>
**Session questions:** <N>

## Summary Table

| # | Category | Question | Answer (summary) |
|---|----------|----------|------------------|
| Q1 | git | このブランチの main との差分は？ | 認証ミドルウェア追加の3コミット |
| Q2 | implementation | トークン検証は安全？ | 単一ノードではOK、HA構成ではレース懸念 |
| ... | | | |

## Details

### Q1 — このブランチの main との差分は？

**Category:** git
**Sources:** `git log main..HEAD`, commits `81d2983`, `4143756`, `f1ad9ee`

**回答:** 認証ミドルウェア追加の3コミット（2026-04-07、Shota Iuchi）。

**根拠:**
- `81d2983` feat: add JWT middleware — `src/auth/jwt.ts:1-84`
- `4143756` wire middleware into router — `src/server.ts:22`
- `f1ad9ee` add tests — `tests/auth/jwt.test.ts`

**不確実性:** なし — 全コミットはクリーンでpush済み。

---

### Q2 — ...
```

レポートのルール:

- **Summary Table を先頭に。** このテーブルはナビゲーションであり、全質問を順番に網羅しなければならない。
- **Detail を後続に。** 各質問は独自のサブセクションを持ち、セッション内で返した回答をそのまま残す。書き直さず、実際に話した内容を保存する。
- **出典を必ず示す。** Detail の各エントリは参照したファイル・コミット・PRを明記する。
- **調査していない質問に答えをでっち上げない。** 保留・スキップされた質問はその旨を明記する。

### レポート書き出し後

ユーザーに保存先と1行サマリを伝える（例: 「7件のQ&Aを `qa-report.md` に保存しました」）。開かない、コミットしない、pushしない — それらは変更操作であり、このスキルは変更を行わない。

## このスキルがやらないこと

- **コード修正を行わない。** 回答中にバグが見つかってもバグを報告するだけ。ユーザーが「直して」と言うまで何もしない。
- **PRを作らない。** PR内容を読む（`gh pr view`, `gh pr diff`）ことはできるが、`gh pr create`, `gh pr merge`, `gh pr comment` 等は一切実行しない。
- **コミットを作らない。** `git log` / `git show` / `git blame` は読めるが、`git commit`, `git push`, `git rebase`, `git reset` など ref やワーキングツリーを変える操作は一切実行しない。
- **黙って調査しない。** 全ての調査は必ずユーザーに可視な回答として結実する。内部メモで止めない。

状態を変えなければ答えられない質問（稀だが起こり得る、例: 「`git rebase` したら何が起きる？」）に直面したら、必要な操作を説明し、ユーザー自身に実行してもらうか、明示的にドライラン許可を求める。