Reviewing Docs

ドキュメントレビュースキル

コード内コメントの品質チェックと、ドキュメント更新が必要な箇所を検出する。

参照ドキュメント

実行時に WebFetch で取得:

• コメント観点: https://stackoverflow.blog/2021/12/23/best-practices-for-writing-code-comments/
• ドキュメント観点: https://agilemodeling.com/essays/agileDocumentationBestPractices.htm#ExecutableSpecifications

レビュー手順

レビュー進捗:
- [ ] Step 1: ベストプラクティスの取得
- [ ] Step 2: 対象ファイルの特定
- [ ] Step 3: レビュー実行
- [ ] Step 4: 結果の報告

Step 1: ベストプラクティスの取得

WebFetch で以下2つのURLを 並列に 取得:

• コメント観点: https://stackoverflow.blog/2021/12/23/best-practices-for-writing-code-comments/
• ドキュメント観点: https://agilemodeling.com/essays/agileDocumentationBestPractices.htm#ExecutableSpecifications

取得失敗時: エラー内容をユーザーに報告し、手動でURLを開いて内容を貼り付けるよう依頼する。

Step 2: 対象ファイルの特定

引数あり: 指定されたファイルパスを使用

引数なし: 変更ファイル一覧を取得

# デフォルトブランチを自動検出して差分を取得
git diff --name-only origin/$(git symbolic-ref refs/remotes/origin/HEAD | sed 's@^refs/remotes/origin/@@')...HEAD

Step 3: レビュー実行

1. ファイル読み込み: Read ツールで対象ファイルを読み込む（複数ファイルの場合は 並列に 実行）

1. コメント品質チェック: 以下の観点でコードとコメントを分析

| 種類 | 検出パターン | | ---------------- | ------------------------------------------------ | | Why不足 | コメントが「何をしているか」のみで「なぜ」がない | | 不要コメント | // i++ のようなコード自明な説明 | | TODO形式不備 | // TODO: あとで のように Issue 番号がない | | マジックナンバー | 説明のない定数値（const LIMIT = 100） | | 正規表現未説明 | パターンの意図が不明な正規表現 |

1. ドキュメント更新チェック: 実装変更に対してドキュメントの更新が必要か判断

a. docs/README.md を読んでドキュメント構成を把握 b. 関連する既存ドキュメントを Read で読み込む（docs/adr/ は除外） c. コード変更と照合し、更新・追記・新規作成が必要な箇所を検出

注意: docs/adr/ は自動更新対象外（設計決定は人間が管理）

1. 問題箇所の記録: ファイルパス:行番号 形式で記録

Step 4: 結果の報告

出力形式に従ってユーザーにテキスト出力する。

エラーハンドリング

| エラー | 対応 | | ------------------------ | -------------------------------------------------------------------------------------------------- | | 変更ファイルが0件 | 「変更ファイルがありません。レビュー対象のファイルパスを指定してください。」と報告 | | 指定ファイルが存在しない | 「ファイルが見つかりません: {path}」と報告し、他のファイルの処理を継続。サマリーでエラー件数を報告 | | Gitリポジトリ外で実行 | 「Gitリポジトリ内で実行してください。」と報告して終了 | | WebFetch失敗 | エラー内容を報告し、手動でURLを開いて内容を貼り付けるよう依頼 |

出力形式

出力構成

## 1. レビュー対象ファイル
## 2. コメント品質の問題
## 3. ドキュメント更新の提案
## 4. サマリー

2. コメント品質の問題

ファイル: src/utils/format.ts:42
種類: Why不足
問題: ポリフィル使用の理由が不明
修正提案: `// Safari では Intl.Segmenter 未サポートのためポリフィル使用`

3. ドキュメント更新の提案

対象ドキュメント: docs/development/setup.md
理由: 新しい環境変数 API_KEY が追加された
推奨アクション: 環境変数セクションに API_KEY の説明を追記

実行例

例1: 単一ファイル指定

入力:

/reviewing-docs apps/web/src/services/auth.ts

出力:

## 1. レビュー対象ファイル
- apps/web/src/services/auth.ts

## 2. コメント品質の問題

ファイル: apps/web/src/services/auth.ts:42
種類: マジックナンバー
問題: トークン有効期限の値に説明がない
修正提案: `// JWT標準に基づく24時間（86400秒）`

## 3. ドキュメント更新の提案

なし

## 4. サマリー
コメント問題: 1件 / ドキュメント更新: 0件

例2: 引数なし（git diff から検出）

入力:

/reviewing-docs

出力:

## 1. レビュー対象ファイル（git diff から検出）
- apps/web/src/routes/api.ts
- packages/config/src/env.ts

## 2. コメント品質の問題

なし

## 3. ドキュメント更新の提案

対象ドキュメント: docs/development/setup.md
理由: packages/config/src/env.ts で新しい環境変数 `REDIS_URL` が追加された
推奨アクション: 「環境変数一覧」セクションに REDIS_URL の説明を追記

## 4. サマリー
コメント問題: 0件 / ドキュメント更新: 1件

例3: 問題なし

出力:

## 1. レビュー対象ファイル
- apps/web/src/services/user.ts

## 2. コメント品質の問題

なし

## 3. ドキュメント更新の提案

なし

## 4. サマリー
コメント問題: 0件 / ドキュメント更新: 0件

注意事項

• 批判的ではなく建設的なフィードバックを提供
• 具体的なファイルパスと行番号を含める

Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: TomokiIchi
• Source: TomokiIchi/my-claude-skills
• License: MIT

Install and usage instructions live in the source repository linked above.