A general-purpose skill for systematically reviewing PRs and code changes. Used by combining language-independent common review criteria with language/framework-specific best practices.
Directory structure
code-review/
├── SKILL.md (このファイル)
└── references/
├── typescript-best-practices.md # TypeScript固有のチェック
├── authorization-review-general.md # 認可レビュー観点（一般編）
├── authorization-review-postgres-rls.md # 認可レビュー観点（PostgreSQL RLS編）
├── github-pr-review-actions.md # GitHub PRレビューアクション
├── ci-optimized-workflow.md # CI環境でのコスト最適化ワークフロー
├── incremental-review.md # インクリメンタルレビューの詳細
├── skill-review.md # Claude Codeスキル（SKILL.md）レビュー基準
├── skill-overview.md # スキル概要（公式ドキュメント）
└── skill-best-practices.md # スキルベストプラクティス（公式ドキュメント）
Runtime files
Files automatically generated when CI runs. Do not commit to the repository.
| File | Purpose | Lifecycle |
|---|---|---|
.pr-triage.json |
Triage result | Generated every time |
.pr-review-state.json |
Review state | actions/cache Persisted across runs in |
External skill integration
For React / Next.js best practices, use the vercel-react-best-practices skill provided by Vercel.
- Repository: https://github.com/vercel-labs/agent-skills/tree/main/skills/react-best-practices
- Installation:
npx -y skills add vercel-labs/agent-skills --skill vercel-react-best-practices --agent claude-code --yes - Coverage: Eliminating asynchronous waterfalls, bundle size optimization, server-side performance, client-side data fetching, re-render optimization, rendering performance, advanced patterns, JavaScript performance (8 categories, 40+ rules)
Cost optimization (CI environment)
When running in a CI environment such as GitHub Actions, costs can be significantly reduced by delegating the triage phase to a lightweight model (Haiku). For details, see references/ci-optimized-workflow.md .
Utilizing triage results
If pre-triage has been run in the CI environment, .pr-triage.json exists in the working directory.
If this file exists, apply the following optimizations:
- Skip step 1 — Use the triage result's
summaryuse - Selective loading of references —
required_referencesRead only what is included in - Omitting surface-level checks —
surface_issuesTreat the Minor/Suggestion issues included in - Efficient diff checking —
filesUtilize the category classification in
// .pr-triage.json の構造
{
"pr_number": 123,
"summary": "認証ミドルウェアの追加とユーザーAPI新規作成",
"files": {
"added": ["src/middleware/auth.ts", "src/api/users.ts"],
"modified": ["src/routes/index.ts"],
"deleted": []
},
"languages": ["typescript"],
"frameworks": ["express"],
"change_categories": {
"has_auth_changes": true,
"has_db_changes": false,
"has_rls_changes": false,
"has_api_changes": true,
"has_test_changes": false,
"has_config_changes": false,
"has_skill_changes": false
},
"required_references": [
"typescript-best-practices.md",
"authorization-review-general.md"
],
"surface_issues": [
{
"severity": "Minor",
"file": "src/api/users.ts",
"line": 15,
"issue": "`any`型が使用されている",
"suggestion": "具体的な型に変更する"
}
],
"diff_summary": "認証ミドルウェアを新規追加。JWTトークン検証を実装。ユーザーCRUD APIを新規作成。テストは未追加。",
"estimated_complexity": "medium",
"focus_areas": ["セキュリティ: JWT検証の実装", "認可: ユーザーAPIのアクセス制御"]
}
.pr-triage.jsonIfdoes not exist, run all steps from step 1 as before (backward compatible).
Incremental review (diff optimization on PR updates)
On PR update (synchronizeevent), reduce token consumption by utilizing the previous review state.
For details, see references/incremental-review.md .
.pr-review-state.jsonIf(initial review) does not apply incremental optimization and performs a full triage. If the format is invalid, it also outputs a warning and performs a full triage.
Review workflow
Copy the following checklist to track progress:
レビュー進捗：
- [ ] ステップ1: 変更概要の把握
- [ ] ステップ2: 共通品質チェック
- [ ] ステップ3: 言語/フレームワーク固有チェック
- [ ] ステップ4: approve/reject判定
- [ ] ステップ5: レビュー結果の出力
Step 1: Understand the change overview
.pr-triage.jsonIf exists: Read this file andsummary、files、change_categories、diff_summaryuse . Skip the following manual checks and proceed to step 2.
Understand the changes.
- Check the list of changed files - Understand the scope and extent of the changes
- Check the code diff - Understand what was added, changed, or deleted
- Understand the intent of the changes - Confirm the purpose from the PR description or commit messages
Points to check:
- Are the changes focused on a single purpose?
- Is the scope appropriate (not making too many changes in one PR)?
- Are related changes included without omission?
Step 2: Common quality check
.pr-triage.jsonIf exists:surface_issuesMinor/Suggestion issues included in have already been checked. Here, focus on detecting Critical/Major level issues (security, logic/correctness, major performance issues). There is no need to re-check superficial issues (naming conventions, destructuring, etc.).
Perform general checks that are not language-dependent.
2-1. Security
| Check item | Severity |
|---|---|
| Are there no hardcoded secrets (API keys, passwords, tokens)? | Critical |
| Is there proper validation/sanitization of user input? | Critical |
| Are there no SQL injection, XSS, or command injection vulnerabilities? | Critical |
| Are authentication/authorization checks properly implemented? | Critical |
| Is sensitive data not inadvertently output to logs? | Major |
| Is the CORS configuration appropriate? | Major |
Detailed review of authorization: If there are changes related to authorization,references/authorization-review-general.md refer to and perform detailed checks. If using PostgreSQL RLS, additionally references/authorization-review-postgres-rls.md also refer to .
2-2. Logic/correctness
| Check item | Severity |
|---|---|
| Are edge cases handled appropriately (null, empty array, boundary values)? | Major |
| Is error handling appropriate (swallowing exceptions, inappropriate catch)? | Major |
| Is the conditional branching logic correct (off-by-one, mistakes in logical operators)? | Major |
| Are there race conditions in asynchronous processing? | Major |
| Reliable release of resources (files, connections, locks) | Major |
2-3. Design and Maintainability
| Check Item | Importance |
|---|---|
| Is the responsibility of the function/method single? | Minor |
| DRY principle: Is there no unnecessary duplicate code? | Minor |
| Do the names accurately express the intent? | Minor |
| Are there no magic numbers or meaningless string literals? | Minor |
| Is it designed with an appropriate level of abstraction (excessive abstraction or insufficient)? | Minor |
| Are there no circular references or inappropriate dependencies? | Major |
2-4. Performance
| Check Item | Importance |
|---|---|
| Are there no inefficient data access patterns such as N+1 queries? | Major |
| Are there no unnecessary loops or nesting, or processes with high computational complexity? | Minor |
| Is there no possibility of a memory leak? | Major |
| Appropriate pagination and streaming processing for large amounts of data | Minor |
2-5. Testing
| Check Item | Importance |
|---|---|
| Have tests corresponding to the changes been added/updated? | Major |
| Are edge case tests included? | Minor |
| Do the tests test behavior rather than implementation details? | Minor |
| Do the test names clearly express the behavior being tested? | Suggestion |
Step 3: Language/Framework-Specific Checks
.pr-triage.jsonIf exists:required_referencesRead only the references listed in . Do not read references not in the list (to save tokens).
Depending on the language/framework of the changed files, refer to the corresponding reference files.
Available references:
| Language/FW | Reference | Type |
|---|---|---|
| TypeScript | references/typescript-best-practices.md | Internal reference |
| React / Next.js | vercel-react-best-practices skill (provided by Vercel) |
External skill |
| Perspective | Reference | Type |
|---|---|---|
| Authorization (General) | references/authorization-review-general.md | Internal reference |
| Authorization (PostgreSQL RLS) | references/authorization-review-postgres-rls.md | Internal reference |
| GitHub PR review | references/github-pr-review-actions.md | Internal reference |
| Claude Code skill | references/skill-review.md | Internal reference |
Reference rules:
- TypeScript changes → Read the internal reference
- React / Next.js changes →
vercel-react-best-practicesUse the skill together (if installed) - Changes involving authorization (authentication/permission checks, data access control, etc.) → Refer to the authorization reference (General edition)
- If using PostgreSQL RLS → Also refer to the authorization reference (RLS edition)
- When running PR reviews in a CI environment such as GitHub Actions → Refer to the GitHub PR review action (comment posting and evaluation methods)
- Changes that include a SKILL.md file → Refer to the skill review reference and additionally perform a skill quality check
- For changes spanning multiple languages/FWs, refer to all applicable references
- For languages with no reference, judge based only on the common checks in Step 2
Step 4: approve/reject decision
Based on all check results, decide approve/reject according to the following criteria.
Issue severity and point deductions
| Severity | Description | Deduction |
|---|---|---|
| Critical | Must be fixed before merging. Security vulnerabilities, data loss risks, critical bugs | -3 points/item |
| Major | Should be fixed on a priority basis. Logic issues, performance degradation, insufficient tests | -2 points/item |
| Minor | Improvement desirable. Design improvements, readability improvements, minor issues | -1 point/item |
| Suggestion | Suggestion. Recommendations for best practices, presentation of better approaches | -0.5 points/item |
Decision criteria
The maximum score is 10 points, and the decision is made according to the following criteria.
| Decision | Condition | Action |
|---|---|---|
| Reject | There is 1 or more Critical issues | REQUEST_CHANGES |
| Reject | There are 3 or more Major issues | REQUEST_CHANGES |
| Reject | Score is less than 5 points | REQUEST_CHANGES |
| Conditional Approve | No Critical issues, 1-2 Major issues, score of 5 points or more | APPROVE (comment on improvement points) |
| Approve | No Critical/Major issues, score of 8 points or more | APPROVE |
Decision flowchart
Critical問題あり？ → Yes → Reject（REQUEST_CHANGES）
↓ No
Major問題が3件以上？ → Yes → Reject（REQUEST_CHANGES）
↓ No
スコア5点未満？ → Yes → Reject（REQUEST_CHANGES）
↓ No
Major問題が1-2件？ → Yes → Conditional Approve
↓ No
スコア8点以上？ → Yes → Approve
↓ No
Conditional Approve
Step 5: Output review results
.pr-triage.jsonexists: Triage phasesurface_issuesinto the "Detected Issues" table of the review results (excluding duplicates). Include triage findings in the scoring as well.
Output the review results in the following format.
Posting reviews on GitHub: Only when executing a PR review in a CI environment such as GitHub Actions,references/github-pr-review-actions.md refer to, and
ghpost the review results on GitHub using commands or inline comments. When running in a local environment, only display the results to standard output.Follow-up on fixed issues：
.pr-triage.jsonにresolved_issuesis included (during incremental review), reply to the original inline comment to report the fix. After the review is complete, record the posted comment IDs in.pr-review-state.json.
## Code Review: [判定結果]
### 変更概要
- **スコープ**: [変更の概要を1-2文で]
- **変更ファイル数**: [N]ファイル
- **主な言語/FW**: [検出された言語/FW]
### スコア: X/10
### 検出された問題
| # | 重要度 | ファイル | 問題 | 推奨される対応 |
|---|--------|---------|------|---------------|
| 1 | [Critical/Major/Minor/Suggestion] | [ファイルパス:行番号] | [問題の説明] | [対応方法] |
### 良い点
- [コードの良い点を具体的に記載]
### 判定
- **結果**: [Approve / Conditional Approve / Reject]
- **理由**: [判定理由の要約]
### 次のステップ
- [修正が必要な場合の具体的なアクション]
Important notes
- The purpose of review is to improve code quality, not to criticize. Keep constructive feedback in mind
- Always attachspecific improvement suggestionswhen pointing out issues
- Respect theintent of the changeand judge based on objective criteria rather than stylistic preferences
- Leave judgments involving domain knowledge or business logic that are difficult to detect automatically to human reviewers
- Suggestions are not mandatory, and whether to adopt them is left to the author's discretion