github-code-review

GitHub のコードレビュー

プッシュする前にローカルの変更をレビューしたり、GitHub 上のオープンな PR をレビューしたりできます。このスキルの大部分では通常の git を使用します。PR レベルの操作でのみ、gh と curl の使い分けが重要になります。

前提条件

• GitHub で認証済みであること（github-auth スキルを参照）
• git リポジトリ内にいること

セットアップ（PR の操作向け）

if command -v gh &>/dev/null && gh auth status &>/dev/null; then
  AUTH="gh"
else
  AUTH="git"
  if [ -z "$GITHUB_TOKEN" ]; then
    if _hermes_env="${HERMES_HOME:-$HOME/.hermes}/.env"; [ -f "$_hermes_env" ] && grep -q "^GITHUB_TOKEN=" "$_hermes_env"; then
      GITHUB_TOKEN=$(grep "^GITHUB_TOKEN=" "$_hermes_env" | head -1 | cut -d= -f2 | tr -d '\n\r')
    elif grep -q "github.com" ~/.git-credentials 2>/dev/null; then
      GITHUB_TOKEN=$(uv run python "${HERMES_HOME:-$HOME/.hermes}/skills/github/github-auth/scripts/git-credential-token.py")
    fi
  fi
fi

REMOTE_URL=$(git remote get-url origin)
OWNER_REPO=$(echo "$REMOTE_URL" | sed -E 's|.*github\.com[:/]||; s|\.git$||')
OWNER=$(echo "$OWNER_REPO" | cut -d/ -f1)
REPO=$(echo "$OWNER_REPO" | cut -d/ -f2)

---

1. ローカルの変更をレビューする（プッシュ前）

通常の git のみを使うため、どこでも動作し、API も必要ありません。

差分を取得する

# Staged changes (what would be committed)
git diff --staged

# All changes vs main (what a PR would contain)
git diff main...HEAD

# File names only
git diff main...HEAD --name-only

# Stat summary (insertions/deletions per file)
git diff main...HEAD --stat

レビューの進め方

1. まず全体像を把握します。

git diff main...HEAD --stat
git log main..HEAD --oneline

2. ファイルごとにレビューします。 変更されたファイルの全体的なコンテキストを確認するには read_file を使い、何が変更されたかを確認するには差分を使います。

git diff main...HEAD -- src/auth/login.py

3. よくある問題がないか確認します。

# Debug statements, TODOs, console.logs left behind
git diff main...HEAD | grep -n "print(\|console\.log\|TODO\|FIXME\|HACK\|XXX\|debugger"

# Large files accidentally staged
git diff main...HEAD --stat | sort -t'|' -k2 -rn | head -10

# Secrets or credential patterns
git diff main...HEAD | grep -in "password\|secret\|api_key\|token.*=\|private_key"

# Merge conflict markers
git diff main...HEAD | grep -n "<<<<<<\|>>>>>>\|======="

4. ユーザーに構造化されたフィードバックを提示します。

レビュー結果の形式

ローカルの変更をレビューする際は、次の構成で指摘事項を提示します。

## Code Review Summary

### Critical
- **src/auth.py:45** — SQL injection: user input passed directly to query.
  Suggestion: Use parameterized queries.

### Warnings
- **src/models/user.py:23** — Password stored in plaintext. Use bcrypt or argon2.
- **src/api/routes.py:112** — No rate limiting on login endpoint.

### Suggestions
- **src/utils/helpers.py:8** — Duplicates logic in `src/core/utils.py:34`. Consolidate.
- **tests/test_auth.py** — Missing edge case: expired token test.

### Looks Good
- Clean separation of concerns in the middleware layer
- Good test coverage for the happy path

---

2. GitHub のプルリクエストをレビューする

PR の詳細を表示する

gh を使用する場合：

gh pr view 123
gh pr diff 123
gh pr diff 123 --name-only

git と curl を使用する場合：

PR_NUMBER=123

# Get PR details
curl -s \
  -H "Authorization: token $GITHUB_TOKEN" \
  https://api.github.com/repos/$OWNER/$REPO/pulls/$PR_NUMBER \
  | python -c "
import sys, json
pr = json.load(sys.stdin)
print(f\"Title: {pr['title']}\")
print(f\"Author: {pr['user']['login']}\")
print(f\"Branch: {pr['head']['ref']} -> {pr['base']['ref']}\")
print(f\"State: {pr['state']}\")
print(f\"Body:\n{pr['body']}\")"

# List changed files
curl -s \
  -H "Authorization: token $GITHUB_TOKEN" \
  https://api.github.com/repos/$OWNER/$REPO/pulls/$PR_NUMBER/files \
  | python -c "
import sys, json
for f in json.load(sys.stdin):
    print(f\"{f['status']:10} +{f['additions']:-4} -{f['deletions']:-4}  {f['filename']}\")"

PR をローカルにチェックアウトして全体をレビューする

通常の git で動作し、gh は必要ありません。

# Fetch the PR branch and check it out
git fetch origin pull/123/head:pr-123
git checkout pr-123

# Now you can use read_file, search_files, run tests, etc.

# View diff against the base branch
git diff main...pr-123

gh を使用する場合（ショートカット）：

gh pr checkout 123

PR にコメントする

PR 全体へのコメント — gh を使用する場合：

gh pr comment 123 --body "Overall looks good, a few suggestions below."

PR 全体へのコメント — curl を使用する場合：

curl -s -X POST \
  -H "Authorization: token $GITHUB_TOKEN" \
  https://api.github.com/repos/$OWNER/$REPO/issues/$PR_NUMBER/comments \
  -d '{"body": "Overall looks good, a few suggestions below."}'

インラインレビューコメントを残す

インラインコメントを 1 件残す — gh を使用する場合（API 経由）：

HEAD_SHA=$(gh pr view 123 --json headRefOid --jq '.headRefOid')

gh api repos/$OWNER/$REPO/pulls/123/comments \
  --method POST \
  -f body="This could be simplified with a list comprehension." \
  -f path="src/auth/login.py" \
  -f commit_id="$HEAD_SHA" \
  -f line=45 \
  -f side="RIGHT"

インラインコメントを 1 件残す — curl を使用する場合：

# Get the head commit SHA
HEAD_SHA=$(curl -s \
  -H "Authorization: token $GITHUB_TOKEN" \
  https://api.github.com/repos/$OWNER/$REPO/pulls/$PR_NUMBER \
  | python -c "import sys,json; print(json.load(sys.stdin)['head']['sha'])")

curl -s -X POST \
  -H "Authorization: token $GITHUB_TOKEN" \
  https://api.github.com/repos/$OWNER/$REPO/pulls/$PR_NUMBER/comments \
  -d "{
    \"body\": \"This could be simplified with a list comprehension.\",
    \"path\": \"src/auth/login.py\",
    \"commit_id\": \"$HEAD_SHA\",
    \"line\": 45,
    \"side\": \"RIGHT\"
  }"

正式なレビューを送信する（承認／変更をリクエスト）

gh を使用する場合：

gh pr review 123 --approve --body "LGTM!"
gh pr review 123 --request-changes --body "See inline comments."
gh pr review 123 --comment --body "Some suggestions, nothing blocking."

curl を使用する場合 — 複数のコメントをまとめてレビューとして送信：

HEAD_SHA=$(curl -s \
  -H "Authorization: token $GITHUB_TOKEN" \
  https://api.github.com/repos/$OWNER/$REPO/pulls/$PR_NUMBER \
  | python -c "import sys,json; print(json.load(sys.stdin)['head']['sha'])")

curl -s -X POST \
  -H "Authorization: token $GITHUB_TOKEN" \
  https://api.github.com/repos/$OWNER/$REPO/pulls/$PR_NUMBER/reviews \
  -d "{
    \"commit_id\": \"$HEAD_SHA\",
    \"event\": \"COMMENT\",
    \"body\": \"Code review from Hermes Agent\",
    \"comments\": [
      {\"path\": \"src/auth.py\", \"line\": 45, \"body\": \"Use parameterized queries to prevent SQL injection.\"},
      {\"path\": \"src/models/user.py\", \"line\": 23, \"body\": \"Hash passwords with bcrypt before storing.\"},
      {\"path\": \"tests/test_auth.py\", \"line\": 1, \"body\": \"Add test for expired token edge case.\"}
    ]
  }"

イベントの値："APPROVE"、"REQUEST_CHANGES"、"COMMENT"

line フィールドは、ファイルの新しいバージョンにおける行番号を指します。削除された行には、"side": "LEFT" を使用します。

---

3. レビューチェックリスト

コードレビュー（ローカルまたは PR）を行う際は、次の項目を体系的に確認します。

正確性

• コードは意図したとおりに動作しますか？
• エッジケース（空の入力、null、大量のデータ、並行アクセス）は処理されていますか？
• エラー発生時の処理は適切ですか？

セキュリティ

• ハードコードされたシークレット、認証情報、API キーがないこと
• ユーザー向け入力が検証されていること
• SQL インジェクション、XSS、パストラバーサルがないこと
• 必要な箇所で認証／認可のチェックが行われていること

コード品質

• 命名（変数、関数、クラス）が明確であること
• 不必要な複雑さや時期尚早な抽象化がないこと
• DRY — 抽出すべきロジックが重複していないこと
• 関数の役割が絞られていること（単一責任）

テスト

• 新しいコードパスがテストされていること
• 正常系とエラーケースが網羅されていること
• テストが読みやすく、保守しやすいこと

パフォーマンス

• N+1 クエリや不必要なループがないこと
• 効果が見込める箇所で適切にキャッシュされていること
• 非同期のコードパスにブロッキング処理がないこと

ドキュメント

• 公開 API にドキュメントがあること
• 自明でないロジックについて、その理由を説明するコメントがあること
• 動作に変更があった場合、README が更新されていること

---

4. プッシュ前のレビューワークフロー

ユーザーが「コードをレビューして」または「プッシュ前に確認して」と依頼した場合：

1. git diff main...HEAD --stat — 変更の範囲を確認します
2. git diff main...HEAD — 差分全体を読みます
3. 変更された各ファイルについて、さらにコンテキストが必要であれば read_file を使います
4. 上記のチェックリストを適用します
5. 構造化された形式（Critical / Warnings / Suggestions / Looks Good）で指摘事項を提示します
6. 重大な問題が見つかった場合は、ユーザーがプッシュする前に修正することを提案します

---

5. PR レビューワークフロー（エンドツーエンド）

ユーザーが「PR #N をレビューして」「この PR を見て」と依頼した場合、または PR の URL を提示した場合は、次の手順に従います。

ステップ 1：環境をセットアップする

source "${HERMES_HOME:-$HOME/.hermes}/skills/github/github-auth/scripts/gh-env.sh"
# Or run the inline setup block from the top of this skill

ステップ 2：PR のコンテキストを収集する

コードを詳しく確認する前に、PR のメタデータ、説明、変更されたファイルの一覧を取得し、変更の範囲を把握します。

gh を使用する場合：

gh pr view 123
gh pr diff 123 --name-only
gh pr checks 123

curl を使用する場合：

PR_NUMBER=123

# PR details (title, author, description, branch)
curl -s -H "Authorization: token $GITHUB_TOKEN" \
  https://api.github.com/repos/$GH_OWNER/$GH_REPO/pulls/$PR_NUMBER

# Changed files with line counts
curl -s -H "Authorization: token $GITHUB_TOKEN" \
  https://api.github.com/repos/$GH_OWNER/$GH_REPO/pulls/$PR_NUMBER/files

ステップ 3：PR をローカルにチェックアウトする

これにより、read_file と search_files を使えるようになり、テストも実行できるようになります。

git fetch origin pull/$PR_NUMBER/head:pr-$PR_NUMBER
git checkout pr-$PR_NUMBER

ステップ 4：差分を読み、変更内容を把握する

# Full diff against the base branch
git diff main...HEAD

# Or file-by-file for large PRs
git diff main...HEAD --name-only
# Then for each file:
git diff main...HEAD -- path/to/file.py

変更された各ファイルについて、変更箇所の周辺を含む全体的なコンテキストを確認するために read_file を使います。差分だけでは、周辺のコードを見ないと分からない問題を見落とす可能性があります。

ステップ 5：ローカルで自動チェックを実行する（該当する場合）

# Run tests if there's a test suite
python -m pytest 2>&1 | tail -20
# or: npm test, cargo test, go test ./..., etc.

# Run linter if configured
ruff check . 2>&1 | head -30
# or: eslint, clippy, etc.

ステップ 6：レビューチェックリスト（セクション 3）を適用する

各カテゴリを確認します：正確性、セキュリティ、コード品質、テスト、パフォーマンス、ドキュメント。

ステップ 7：レビューを GitHub に投稿する

指摘事項をまとめ、インラインコメントを添えて正式なレビューを提出します。

gh を使用する場合：

# If no issues — approve
gh pr review $PR_NUMBER --approve --body "Reviewed by Hermes Agent. Code looks clean — good test coverage, no security concerns."

# If issues found — request changes with inline comments
gh pr review $PR_NUMBER --request-changes --body "Found a few issues — see inline comments."

curl を使用する場合 — 複数のインラインコメントを含むアトミックなレビュー：

HEAD_SHA=$(curl -s -H "Authorization: token $GITHUB_TOKEN" \
  https://api.github.com/repos/$GH_OWNER/$GH_REPO/pulls/$PR_NUMBER \
  | python -c "import sys,json; print(json.load(sys.stdin)['head']['sha'])")

# Build the review JSON — event is APPROVE, REQUEST_CHANGES, or COMMENT
curl -s -X POST \
  -H "Authorization: token $GITHUB_TOKEN" \
  https://api.github.com/repos/$GH_OWNER/$GH_REPO/pulls/$PR_NUMBER/reviews \
  -d "{
    \"commit_id\": \"$HEAD_SHA\",
    \"event\": \"REQUEST_CHANGES\",
    \"body\": \"## Hermes Agent Review\n\nFound 2 issues, 1 suggestion. See inline comments.\",
    \"comments\": [
      {\"path\": \"src/auth.py\", \"line\": 45, \"body\": \"🔴 **Critical:** User input passed directly to SQL query — use parameterized queries.\"},
      {\"path\": \"src/models.py\", \"line\": 23, \"body\": \"⚠️ **Warning:** Password stored without hashing.\"},
      {\"path\": \"src/utils.py\", \"line\": 8, \"body\": \"💡 **Suggestion:** This duplicates logic in core/utils.py:34.\"}
    ]
  }"

ステップ 8：要約コメントも投稿する

インラインコメントに加えて、PR の作成者が全体像をひと目で把握できるよう、トップレベルの要約を残します。references/review-output-template.md のレビュー出力形式を使用してください。

gh を使用する場合：

gh pr comment $PR_NUMBER --body "$(cat <<'EOF'
## Code Review Summary

**Verdict: Changes Requested** (2 issues, 1 suggestion)

### 🔴 Critical
- **src/auth.py:45** — SQL injection vulnerability

### ⚠️ Warnings
- **src/models.py:23** — Plaintext password storage

### 💡 Suggestions
- **src/utils.py:8** — Duplicated logic, consider consolidating

### ✅ Looks Good
- Clean API design
- Good error handling in the middleware layer

---
*Reviewed by Hermes Agent*
EOF
)"

ステップ 9：クリーンアップする

git checkout main
git branch -D pr-$PR_NUMBER

判断：Approve、Request Changes、Comment のどれを選ぶか

• Approve — 重大または警告レベルの問題がなく、軽微な提案のみ、または問題がない場合
• Request Changes — マージ前に修正すべき重大または警告レベルの問題がある場合
• Comment — 妨げとなる問題はないものの、所見や提案がある場合（判断に迷う場合や PR がドラフトの場合に使用）