code-review

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Code Review

實作後的程式碼審查。四個維度逐段檢視，每個議題給選項和建議，確認後才進下一段。

定位：審查已寫好的程式碼（架構、品質、測試、效能），不是計畫審查。計畫層面的審查請用

/plan-review

。

Post-implementation code review. Inspect in four dimensions section by section, provide options and suggestions for each issue, and proceed to the next section only after confirmation.

Positioning: Review completed code (architecture, quality, testing, performance), not plan review. For plan-level reviews, use

/plan-review

Step 0: 定位審查範圍 + 選擇深度

Step 0: Define Review Scope + Select Review Depth

定位審查範圍

Define Review Scope

按 ARGUMENTS 判斷：

檔案路徑 → 讀取指定檔案
PR 編號（如
```
#123
```
）→
```
gh pr diff 123
```
取得變更
diff
→
```
git diff
```
+
```
git diff --staged
```
取得所有未提交變更
空白 → 預設行為同
```
diff
```
分支名 →
```
git diff main...<branch>
```
取得分支差異

讀取變更後，摘要變更範圍（改了哪些檔案、大致做了什麼），確認審查對象正確。

Determine based on ARGUMENTS:

File path → Read the specified file
PR number (e.g.,
```
#123
```
) → Retrieve changes via
```
gh pr diff 123
```
diff
→ Retrieve all unstaged changes via
```
git diff
```
+
```
git diff --staged
```
Empty → Default behavior is the same as
```
diff
```
Branch name → Retrieve branch differences via
```
git diff main...<branch>
```

After retrieving changes, summarize the scope of changes (which files were modified, what was roughly done) and confirm the review target is correct.

讀取上下文

Read Context

變更檔案的 完整內容（不只 diff hunk）→ 全部讀取。同時讀取被 import 或依賴的關鍵檔案，理解上下文後才能給出有意義的建議。

Read the full content of modified files (not just diff hunks). Also read key files that are imported or depended on; meaningful suggestions can only be provided after understanding the context.

選擇審查深度

Select Review Depth

用 AskUserQuestion 詢問：

深度審查：每段最多 4 個議題，適合重要功能或 PR
快速審查：每段最多 1 個議題，適合小修改或 hotfix

Ask via AskUserQuestion:

In-depth Review: Max 4 issues per section, suitable for important features or PRs
Quick Review: Max 1 issue per section, suitable for small changes or hotfixes

Step 1-4: 四段審查

Step 1-4: Four-Section Review

依序執行。每段完成後用 AskUserQuestion 確認決策，再進下一段。

Execute in order. After completing each section, confirm the decision via AskUserQuestion before proceeding to the next section.

第一段：架構

Section 1: Architecture

系統設計層面的問題。

元件邊界是否合理？有沒有跨層存取或職責混亂？
依賴方向是否正確？有沒有循環依賴？
資料流模式是否清晰？有沒有隱式狀態傳遞？
安全考量：認證、授權、輸入驗證、API 邊界

Issues at the system design level.

Are component boundaries reasonable? Is there cross-layer access or confused responsibilities?
Is the dependency direction correct? Are there circular dependencies?
Is the data flow pattern clear? Is there implicit state transfer?
Security considerations: Authentication, authorization, input validation, API boundaries

第二段：程式品質

Section 2: Code Quality

程式碼本身的問題。

DRY 違規——積極標記重複邏輯（即使只重複兩次）
錯誤處理：是否有未處理的錯誤路徑？catch 區塊是否吞掉錯誤？
邊界案例：空值、空陣列、並發、超時、大量資料
命名與可讀性：變數名是否表達意圖？邏輯是否過於隱晦？
過度工程：不必要的抽象、用不到的彈性、過早最佳化

Issues with the code itself.

DRY violations—proactively flag duplicate logic (even if only repeated twice)
Error handling: Are there unhandled error paths? Do catch blocks swallow errors?
Edge cases: Null values, empty arrays, concurrency, timeouts, large datasets
Naming and readability: Do variable names express intent? Is the logic too obscure?
Over-engineering: Unnecessary abstractions, unused flexibility, premature optimization

第三段：測試

Section 3: Testing

測試覆蓋與品質。

有沒有新增或修改的邏輯缺少對應測試？
測試是否驗證行為而非實作細節？
邊界案例覆蓋：錯誤輸入、空值、極端值、並發
失敗路徑：網路錯誤、權限不足、資源不存在、超時
測試是否可維護？有沒有過度 mock 或脆弱的斷言？

Test coverage and quality.

Is there any new or modified logic without corresponding tests?
Do tests validate behavior rather than implementation details?
Edge case coverage: Invalid inputs, null values, extreme values, concurrency
Failure paths: Network errors, insufficient permissions, non-existent resources, timeouts
Are tests maintainable? Is there over-mocking or fragile assertions?

第四段：效能

Section 4: Performance

效能與資源使用。

N+1 查詢：迴圈中的資料庫/API 呼叫
不必要的計算或重複工作
記憶體：大物件、未釋放的資源、無界限的集合
快取機會：重複的昂貴操作
演算法複雜度：有沒有 O(n²) 可以降為 O(n)？

Performance and resource usage.

N+1 queries: Database/API calls within loops
Unnecessary computations or repeated work
Memory: Large objects, unreleased resources, unbounded collections
Caching opportunities: Repeated expensive operations
Algorithm complexity: Can any O(n²) operations be reduced to O(n)?

議題呈現格式

Issue Presentation Format

每個議題必須包含：

問題描述 — 具體指出
```
file:line
```
或
```
file:SymbolName
```
選項 — 2-3 個選項（含「不處理」），每個標明：
- 實作成本（低/中/高）
- 風險（引入 bug 的可能性）
- 影響範圍（改幾個檔案？影響其他功能？）
- 維護負擔（長期影響）
建議 — 推薦的選項及理由

Each issue must include:

Issue Description — Specifically indicate
```
file:line
```
or
```
file:SymbolName
```
Options — 2-3 options (including "No action"), each marked with:
- Implementation cost (Low/Medium/High)
- Risk (Likelihood of introducing bugs)
- Scope of impact (How many files to modify? Will other functions be affected?)
- Maintenance burden (Long-term impact)
Recommendation — Recommended option and rationale

輸出範例

Output Example

undefined

undefined

1. 品質：驗證邏輯重複

1. Quality: Duplicate Validation Logic

問題：

src/handlers/create.ts:23

和

src/handlers/update.ts:31

有幾乎相同的 email 驗證邏輯（正則 + 長度檢查 + domain 白名單）。

選項：

A) 抽出 validateEmail() 共用函式（建議）成本：低 | 風險：低 | 影響：2 個檔案 | 維護：減少重複
B) 不處理 成本：零 | 風險：中（改一處忘改另一處）| 影響：無 | 維護：兩份要同步
C) 用 zod schema 統一驗證 成本：中 | 風險：低 | 影響：需加 zod 依賴 | 維護：宣告式更清晰

建議 A：最低成本消除重複，不引入新依賴。

undefined

Issue:

src/handlers/create.ts:23

and

src/handlers/update.ts:31

have nearly identical email validation logic (regex + length check + domain whitelist).

Options:

A) Extract validateEmail() as a shared function (Recommended) Cost: Low | Risk: Low | Impact: 2 files | Maintenance: Reduces duplication
B) No action Cost: Zero | Risk: Medium (Forgot to update one when changing the other) | Impact: None | Maintenance: Two copies need to be synchronized
C) Unify validation with zod schema Cost: Medium | Risk: Low | Impact: Requires adding zod dependency | Maintenance: Declarative and clearer

Recommendation A: Eliminates duplication at the lowest cost without introducing new dependencies.

undefined

AskUserQuestion 格式

AskUserQuestion Format

每段結束時用 AskUserQuestion：

選項標籤標示 議題編號 + 選項字母
建議選項放第一個
深度模式範例：
```
1A + 2B + 3A + 4A
```
快速模式直接用選項字母

At the end of each section, use AskUserQuestion:

Option labels marked with Issue number + Option letter
Recommended option placed first
In-depth mode example:
```
1A + 2B + 3A + 4A
```
Quick mode uses option letters directly

Step 5: 審查摘要

Step 5: Review Summary

四段審查完成後，輸出：

markdown

undefined

After completing the four sections, output:

markdown

undefined

程式碼審查摘要

Code Review Summary

#	維度	議題	決策
1	架構	UserService 跨層耦合	A: 透過 OrderService
2	品質	驗證邏輯重複	A: 抽出共用函式
3	測試	缺少錯誤路徑測試	A: 補 3 個測試
4	效能	N+1 查詢	A: 改用 batch query

#	Dimension	Issue	Decision
1	Architecture	UserService cross-layer coupling	A: Via OrderService
2	Quality	Duplicate validation logic	A: Extract shared function
3	Testing	Missing failure path tests	A: Add 3 tests
4	Performance	N+1 query	A: Switch to batch query

待修項目

To-Do Items

```
src/services/user.ts:45
```
— 改用 OrderService 間接存取
```
src/handlers/
```
— 抽出 validateEmail() 到 src/utils/validation.ts
```
src/handlers/create.test.ts
```
— 補充 3 個錯誤路徑測試
```
src/repositories/order.ts:67
```
— N+1 改為 batch query


如果所有議題都選擇「不處理」，直接輸出 **LGTM** 並說明原因。

---

```
src/services/user.ts:45
```
— Use OrderService for indirect access
```
src/handlers/
```
— Extract validateEmail() to src/utils/validation.ts
```
src/handlers/create.test.ts
```
— Add 3 failure path tests
```
src/repositories/order.ts:67
```
— Change N+1 query to batch query


If "No action" is selected for all issues, directly output **LGTM** and explain the reason.

---

審查原則

Review Principles

DRY 重要 — 積極標記重複，即使只重複兩次
測試優先 — 寧可多測不可少測
工程適度 — 不過度抽象，也不太 hacky
邊界案例 — 寧可多想不可遺漏
明確優於聰明 — explicit > clever
只審查變更 — 不要對沒改動的程式碼提意見（除非變更暴露了既有問題）

DRY is important — Proactively flag duplicates, even if only repeated twice
Testing first — Better to test more than less
Moderate engineering — Neither over-abstract nor too hacky
Edge cases — Better to think more than miss
Explicit over clever — explicit > clever
Only review changes — Do not comment on unchanged code (unless changes expose existing issues)

Now Execute

使用者的審查請求見下方

ARGUMENTS:

。從 Step 0 開始。

The user's review request is shown below in

ARGUMENTS:

. Start from Step 0.