qc-code

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Skill: qc-code

WHAT

Purpose và context

Purpose 与 context

Purpose: review code phong cách senior theo bốn mục security · performance · naming · logic — mỗi mục điểm/10 + lỗi nặng nhất + cách sửa — sinh test ĐỎ tái hiện cho mỗi bug logic, rồi ra verdict advisory
```
PASS
```
/
```
CẦN SỬA
```
kèm JSON có bằng chứng.
Trigger (when to use):
- User muốn một cặp mắt senior soi code trước khi chốt: "review code", "soi code", "chấm điểm code".
- Trước commit một thay đổi đáng kể — cắm tùy chọn vào
```
/orca-workflow
```
  trước
```
verify-before-commit
```
  .
Non-goals: KHÔNG dùng cho: quét bảo mật tĩnh (đó là
```
/orca-sec-scans
```
— Trivy) hay xử lý một sự cố đã xảy ra (đó là
```
/orca-issue
```
— repro-first). Không review tổng quát kiểu
```
/code-review
```
built-in; không mặc định toàn codebase; verdict không chặn commit.

Purpose： 以 senior 风格审查代码，覆盖 security、performance、naming、logic 四个维度——每个维度评分/10 + 最严重问题 + 修复方式——为每个 logic bug 生成可复现的红色测试，然后给出 advisory verdict
```
PASS
```
/
```
CẦN SỬA
```
，并附带有证据的 JSON。
Trigger（何时使用）：
- 用户希望在最终确认前由资深开发者的视角审查代码：“review code”“soi code”“chấm điểm code”。
- 在提交重大更改之前——可选择将其接入
```
/orca-workflow
```
  ，置于
```
verify-before-commit
```
  之前。
Non-goals： 不用于静态安全扫描（那是
```
/orca-sec-scans
```
——Trivy），也不用于处理已经发生的故障（那是
```
/orca-issue
```
——repro-first）。不进行
```
/code-review
```
built-in 那种通用审查；默认不审查整个 codebase；verdict 不会阻止 commit。

Mental model

phạm vi (diff từ base | file user nêu) → 4 mục chấm điểm → finding [nhóm][severity] → bug logic → test qc-* ĐỎ → verdict văn xuôi + qc-verdict.json (grounding-check) → test ghi vào dự án → qc-regression.py --run auto-chạy (0-token)

. Đắt = LLM review gọi tay; rẻ = test tất định qua hook.

范围（相对 base 的 diff | 用户指定的 file） → 4 个维度评分 → finding [组别][severity] → logic bug → 红色 qc-* 测试 → 文字 verdict + qc-verdict.json（grounding-check）→ 将测试写入项目 → qc-regression.py --run 自动运行（0-token）

。高成本 = 手动调用 LLM 审查；低成本 = 通过 hook 运行确定性测试。

Phạm vi review (mặc định = diff hiện tại)

审查范围（默认 = 当前 diff）

Mặc định soi thay đổi kể từ base (

git diff

từ commit/branch gốc) — đúng lúc trước commit, nhanh, đúng thứ vừa viết. User chỉ định file/thư mục thì soi cái đó. KHÔNG mặc định toàn codebase (chậm, tốn token, phần lớn không đổi).

默认审查自 base 以来的更改（从原始 commit/branch 执行

git diff

）——最适合提交前的时机，快速且只关注刚写完的内容。用户指定 file/folder 时，则审查指定范围。默认不审查整个 codebase（速度慢、token 消耗高，而且大部分内容没有变化）。

Input và output contract

Input 与 output contract

	Field	Required?	Ý nghĩa
In	phạm vi	không (mặc định = diff từ base)	file/thư mục user chỉ định
In	runner test của dự án	có khi có bug logic	pytest/vitest/jest có sẵn
Out	báo cáo 4 mục	có	mỗi mục điểm/10 · lỗi nặng nhất · cách sửa; performance thêm 3 điểm chậm nhất; naming thêm bảng đổi tên
Out	test `qc-<slug-bug>`	mỗi bug logic	đặt trong thư mục test chuẩn của dự án, ĐỎ trên bản hiện tại
Out	verdict `PASS` / `CẦN SỬA`	có	advisory, kèm danh sách phải-sửa
Out	`harness/out/qc-verdict.json`	có	`decision` / `claim` / `reason` / `required_evidence` , qua `grounding-check` exit 0

	Field	Required?	含义
In	范围	否（默认 = 相对 base 的 diff）	用户指定的 file/folder
In	项目的 test runner	存在 logic bug 时必需	已可用的 pytest/vitest/jest
Out	四维报告	是	每个维度包含评分/10 · 最严重问题 · 修复方式；performance 额外列出 3 个最慢点；naming 额外提供重命名表
Out	`qc-<slug-bug>` 测试	每个 logic bug 均需提供	放在项目的标准测试目录中，并在当前版本上呈红色
Out	`PASS` / `CẦN SỬA` verdict	是	advisory verdict，并附带必须修改的清单
Out	`harness/out/qc-verdict.json`	是	包含 `decision` / `claim` / `reason` / `required_evidence` ，并通过 `grounding-check` exit 0

Rules và capabilities

Rules 与 capabilities

RULE-01 (MUST): Tách đắt/rẻ: LLM review (skill này) = gọi tay / bước workflow tùy chọn. Test tự-sinh = auto-chạy qua hook tất định. KHÔNG bao giờ gọi LLM trong hook (nguyên tắc hook-0-token của overstack).
RULE-02 (MUST): Verdict advisory, test tất định gác cứng — không để LLM verdict chặn commit.
RULE-03 (MUST): Không dẫm:
```
/orca-sec-scans
```
= Trivy tĩnh ·
```
/code-review
```
built-in = tổng quát ·
```
/orca-issue
```
= sự cố repro-first.
```
/qc-code
```
= senior 4-mục-chấm-điểm + sinh test.
RULE-04 (MUST): Review có unknown? Nếu một nhận định phụ thuộc thứ chưa chắc (config prod, hành vi runtime chưa thấy) → ghi nợ
```
[[150726-unknown-ledger]]
```
thay vì khẳng định bừa.
RULE-05 (MUST): Security là ranh giới tin cậy — không lười ở đây (carve-out CLAUDE.md).
RULE-06 (MUST): Mỗi finding gắn đúng MỘT nhóm + MỘT severity; severity đi theo TÁC ĐỘNG thật.
Capabilities: đọc diff/code; ghi file test vào dự án +
```
harness/out/qc-verdict.json
```
; chạy runner test có sẵn. Không mạng.

RULE-01 (MUST)：分离高成本与低成本： LLM 审查（此 skill）= 手动调用或可选的 workflow 步骤。自动生成的测试 = 通过确定性 hook 自动运行。绝不在 hook 中调用 LLM（遵循 overstack 的 hook-0-token 原则）。
RULE-02 (MUST)：Verdict 仅为 advisory，确定性测试才是硬门禁——不要让 LLM verdict 阻止 commit。
RULE-03 (MUST)：互不重叠：
```
/orca-sec-scans
```
= Trivy 静态扫描 ·
```
/code-review
```
built-in = 通用审查 ·
```
/orca-issue
```
= 以复现为优先的故障处理。
```
/qc-code
```
= senior 四维评分 + 生成复现测试。
RULE-04 (MUST)：审查中存在 unknown？ 如果某项判断依赖于尚不确定的信息（生产 config、尚未观察到的 runtime 行为）→ 将该项债务记录到
```
[[150726-unknown-ledger]]
```
，而不是擅自作出断言。
RULE-05 (MUST)：Security 是信任边界——这里绝不能敷衍（适用 CLAUDE.md 的 carve-out）。
RULE-06 (MUST)：每个 finding 必须且只能关联一个组别与一个 severity；severity 应依据实际影响确定。
Capabilities：读取 diff/code；将测试文件和
```
harness/out/qc-verdict.json
```
写入项目；运行项目已有的 test runner。不使用网络。

Failure boundaries

Không xác định được base/phạm vi → clarify (hỏi file/branch), không mặc định toàn codebase.
Dự án không có thư mục test chuẩn → partial: báo rõ và để test cạnh file nguồn, KHÔNG đoán bừa cấu trúc.
```
grounding-check
```
exit 2 → verdict CHƯA hợp lệ, phải viết lại; không nộp verdict mơ hồ.
Nhận định phụ thuộc unknown → ghi nợ unknown-ledger, không khẳng định.
Chưa có test
```
qc-*
```
nào →
```
qc-regression.py
```
fail-open.

无法确定 base/审查范围 → clarify（询问 file/branch），不要默认审查整个 codebase。
项目没有标准测试目录 → partial：明确说明，并将测试放在源文件旁边；不要猜测目录结构。
```
grounding-check
```
exit 2 → verdict 尚无效，必须重写；不要提交含糊的 verdict。
某项判断依赖 unknown → 记录到 unknown-ledger，不要作出断言。
尚无任何
```
qc-*
```
测试 →
```
qc-regression.py
```
fail-open。

HOW

Main workflow

Step	Type	Inputs	Action	Outputs/exit	Failure/next
W01	deterministic	base / file user nêu	Xác định phạm vi `git diff <base>..HEAD --stat` , đọc code	phạm vi	mơ hồ → clarify
W02	judgment	code	Chấm bốn mục + gắn nhóm/severity (bản đồ 13 nhóm)	4 mục đủ 3 phần	—
W03	effect	bug logic	Sinh test tái hiện `qc-*` cho mỗi bug	test ĐỎ chạy được	không đỏ → bug chưa chứng minh, hạ thành nghi ngờ
W04	judgment	kết quả W02–W03	Kết luận PASS / CẦN SỬA + ghi `harness/out/qc-verdict.json`	verdict + JSON	hook exit 2 → viết lại W04
W05	effect	test	Ghi test vào dự án + nhắc `qc-regression.py --run` auto-chạy	test trong repo	không có thư mục test → cạnh nguồn, báo rõ

Chi tiết từng bước (nguồn chân lý cho W01–W05):

Step	Type	Inputs	Action	Outputs/exit	Failure/next
W01	deterministic	base / 用户指定的 file	确定范围 `git diff <base>..HEAD --stat` ，并读取代码	范围	模糊 → clarify
W02	judgment	code	对四个维度评分，并关联组别/severity（13 组映射表）	四个维度均包含三部分	—
W03	effect	logic bug	为每个 bug 生成复现测试 `qc-*`	可运行的红色测试	未呈红色 → bug 尚未得到证明，降级为疑点
W04	judgment	W02–W03 的结果	得出 PASS / CẦN SỬA 结论，并写入 `harness/out/qc-verdict.json`	verdict + JSON	hook exit 2 → 重写 W04
W05	effect	测试	将测试写入项目，并提示 `qc-regression.py --run` 会自动运行	repo 中的测试	没有测试目录 → 放在源文件旁并明确说明

各步骤详情（W01–W05 的 source of truth）：

Steps

Xác định phạm vi —
```
git diff <base>..HEAD --stat
```
(hoặc file user nêu). Đọc code trong phạm vi đó.
Chấm bốn mục (mục dưới). Mỗi mục: điểm/10 · lỗi nặng nhất · cách sửa. → Xong khi cả bốn mục đều có đủ ba phần.
Mục logic: sinh test tái hiện cho mỗi bug (mục "logic & bug" bên dưới). → Xong khi mỗi bug có một test đỏ chạy được.
Kết luận —
```
PASS
```
(sang bước kế) hay
```
CẦN SỬA
```
(liệt kê phải sửa gì trước khi pass). → Xong khi verdict rõ + danh sách phải-sửa nếu CẦN SỬA.
Ghi test vào dự án (mục "Ghi test" dưới) + nhắc
```
qc-regression.py --run
```
auto-chạy chúng.

确定范围 —
```
git diff <base>..HEAD --stat
```
（或用户指定的 file）。读取该范围内的代码。
对四个维度评分（见下方）。每个维度：评分/10 · 最严重问题 · 修复方式。→ 四个维度均具备完整三部分后完成。
Logic 维度：为每个 bug 生成复现测试（见下方“logic & bug”）。→ 每个 bug 都有一个可运行的红色测试后完成。
给出结论 —
```
PASS
```
（进入下一步）或
```
CẦN SỬA
```
（列出通过前必须修改的内容）。→ 结论明确；若为 CẦN SỬA，则包含必须修改的清单。
将测试写入项目（见下方“写入测试”）+ 提示
```
qc-regression.py --run
```
会自动运行这些测试。

Bốn mục

四个维度

1. Security — điểm/10 · lỗi nặng nhất · cách sửa

1. Security — 评分/10 · 最严重问题 · 修复方式

Soi: SQL injection (chuỗi nối vào query, thiếu parameterize) · XSS (output không escape,

innerHTML

dangerouslySetInnerHTML

) · lộ API key / secrets (hardcode key, secret trong log/repo) · validate input (nhận dữ liệu ngoài không kiểm) · phân quyền (thiếu check ai-được-làm-gì, IDOR). Đây là ranh giới tin cậy — không lười ở đây (carve-out CLAUDE.md).

检查：SQL injection（字符串拼接进 query、缺少 parameterize）· XSS（输出未 escape、

innerHTML

dangerouslySetInnerHTML

）· API key / secrets 泄露（hardcode key、secret 出现在 log/repo）· 输入验证（接收外部数据却不检查）· 权限控制（缺少“谁可以做什么”的检查、IDOR）。这是信任边界——绝不能敷衍（适用 CLAUDE.md 的 carve-out）。

2. Performance — điểm/10 · lỗi nặng nhất · cách sửa · 3 điểm chậm nhất

2. Performance — 评分/10 · 最严重问题 · 修复方式 · 3 个最慢点

Soi: query N+1 (vòng lặp gọi DB từng phần tử thay vì một query) · vòng lặp lồng vô ích (O(n²) khi O(n) đủ) · memory leak âm thầm (listener/timer không gỡ, ref giữ mãi, cache không giới hạn). Chỉ ra 3 điểm chậm nhất và cách tối ưu từng cái (với ước lượng độ lớn: O(?), số round-trip).

检查：N+1 query（循环中逐个调用 DB，而不是使用一次 query）· 无用的嵌套循环（O(n) 足够时使用 O(n²)）· 隐蔽的 memory leak（listener/timer 未移除、ref 永久持有、cache 无上限）。指出 3 个最慢点及各自的优化方式（包含量级估算：O(?)、round-trip 数量）。

3. Naming & readability — điểm/10 · lỗi nặng nhất · bảng đổi tên

3. Naming & readability — 评分/10 · 最严重问题 · 重命名表

Soi: tên có nói đúng việc nó làm không (hàm

getUser

mà ghi DB, biến

data

vô nghĩa) · convention nhất quán (camelCase/snake_case lẫn lộn, số nhiều/ít lộn). Trả về bảng:

Tên cũ	Tên mới	Lý do
`d`	`dueDate`	tên một chữ không nói được gì

检查：名称是否准确表达其行为（函数名为

getUser

，实际却会写入 DB；变量名为

data

，毫无意义）· convention 是否一致（camelCase/snake_case 混用、单复数混用）。返回下表：

旧名称	新名称	原因
`d`	`dueDate`	单字母名称无法表达含义

4. Logic & bug — điểm/10 · lỗi nặng nhất · TEST tái hiện mỗi bug

4. Logic & bug — 评分/10 · 最严重问题 · 为每个 bug 生成复现 TEST

Soi: edge case (null · rỗng · số âm · overflow) · off-by-one (

<=

, index cuối) · race condition (state chia sẻ, await xen kẽ, đọc-rồi-ghi không atomic). Mỗi bug tìm được → viết một test-case ĐỎ tái hiện lỗi (chứng minh bug có thật, không phải nghi ngờ). Test đỏ là dữ kiện; verdict là ý kiến.

检查：edge case（null · 空 · 负数 · overflow）· off-by-one（

与

<=

、最后一个 index）· race condition（共享状态、await 交错、read-then-write 不具备原子性）。每找到一个 bug → 编写一个可运行的红色 test-case 来复现问题（证明 bug 确实存在，而不是仅仅怀疑）。红色测试是数据；verdict 是观点。

Bản đồ 13 nhóm lỗi (gstack) + severity

13 组错误映射表（gstack）与 severity

Mỗi finding gắn đúng MỘT nhóm + MỘT severity, format:

[<nhóm>][<severity>] <mô tả> — <cách sửa>

. 5 nhóm CRITICAL soi trước:

#	Nhóm (CRITICAL)	Soi cái gì
1	SQL & data safety	Nối chuỗi vào query (kể cả đã `.to_i` ) thay vì parameterize; check-then-set không atomic (TOCTOU); ghi DB vòng qua validation của model; N+1 thiếu eager-load.
2	Race condition & concurrency	Đọc-kiểm-ghi không có unique constraint; find-or-create thiếu index → gọi song song đẻ bản ghi trùng; chuyển status không dùng `WHERE old_status=?` atomic; render HTML thô trên dữ liệu người dùng (XSS).
3	LLM output trust boundary	Giá trị LLM sinh (email/URL/tên) ghi DB không validate format; output có cấu trúc không kiểm type/shape; URL do LLM sinh được fetch không allowlist (SSRF); output LLM vào knowledge-base không sanitize (stored prompt-injection).
4	Shell injection	`subprocess` / `os.system` với `shell=True` + nội suy chuỗi — dùng argument array; `eval` / `exec` trên code LLM sinh không sandbox.
5	Enum & value completeness	Thêm một giá trị enum/status/tier mới → PHẢI đọc code NGOÀI diff: mọi consumer switch/filter/hiển thị giá trị anh em, mọi allowlist `%w[]` , mọi chuỗi `case/if-elif` — thiếu một consumer là bug âm thầm.

8 nhóm INFORMATIONAL (soi sau, thiên về auto-fix): async/sync mixing (gọi sync blocking trong

async def

time.sleep

thay

asyncio.sleep

) · column/field-name safety (tên cột trong ORM query lệch schema → rỗng âm thầm) · LLM prompt (list 0-indexed trong prompt, prompt khai tool không khớp code, limit khai nhiều chỗ dễ drift) · type coercion (giá trị qua biên Ruby→JSON→JS đổi kiểu; input hash/digest không normalize kiểu) · view/frontend (style inline re-parse mỗi render, O(n·m) lookup trong view, filter phía app thay vì

WHERE

) · time-window safety ("hôm nay" không phủ 24h, hai feature dùng hai kiểu bucket thời gian cho cùng dữ liệu) · completeness gaps (bản 80-90% khi 100% chỉ tốn thêm chút code, test thiếu nhánh negative dễ bổ sung) · distribution & CI/CD (version tool trong workflow lệch dự án, secret hardcode, tag

v1.2.3

1.2.3

lệch nhau, publish không idempotent).

Severity (distill từ awesome-skills/code-review-skill):

[blocking]

= phải sửa trước khi merge ·

[important]

= nên sửa, không đồng ý thì bàn ·

[nit]

= nhỏ, tuỳ tác giả ·

[suggestion]

= hướng khác đáng cân nhắc, không bắt buộc. Nhóm CRITICAL thiên về

blocking/important

; nhóm INFORMATIONAL thiên về

nit/suggestion

— nhưng severity đi theo TÁC ĐỘNG thật của finding, không đi theo nhóm một cách máy móc.

每个 finding 必须且只能关联一个组别与一个 severity，格式为

[<组别>][<severity>] <描述> — <修复方式>

。优先检查 5 组 CRITICAL：

#	组别（CRITICAL）	检查内容
1	SQL & data safety	将字符串拼接进 query（即使已调用 `.to_i` ）而不是 parameterize；check-then-set 不具备原子性（TOCTOU）；写入 DB 时绕过 model 的 validation；N+1 缺少 eager-load。
2	Race condition & concurrency	read-check-write 没有 unique constraint；find-or-create 缺少 index → 并发调用会创建重复记录；状态转换未使用 `WHERE old_status=?` 保持原子性；在用户数据上直接渲染原始 HTML（XSS）。
3	LLM output trust boundary	LLM 生成的 value（email/URL/name）写入 DB 前未验证格式；结构化 output 未检查 type/shape；fetch LLM 生成的 URL 时没有 allowlist（SSRF）；LLM output 写入 knowledge-base 前未 sanitize（stored prompt-injection）。
4	Shell injection	`subprocess` / `os.system` 使用 `shell=True` 并插入字符串——应改用 argument array；对 LLM 生成的 code 执行 `eval` / `exec` 时没有 sandbox。
5	Enum & value completeness	新增一个 enum/status/tier value → 必须读取 diff 之外的 code：所有同级 consumer 的 switch/filter/display、所有 allowlist `%w[]` 、所有字符串 `case/if-elif` ——漏掉一个 consumer 就是静默 bug。

随后检查 8 组 INFORMATIONAL（偏向 auto-fix）：async/sync mixing（在

async def

中调用同步阻塞函数，使用

time.sleep

而非

asyncio.sleep

）· column/field-name safety（ORM query 中的列名与 schema 不一致 → 结果静默为空）· LLM prompt（prompt 中使用从 0 开始的列表，prompt 声明的 tool 与 code 不匹配，limit 在多处声明容易 drift）· type coercion（value 经过 Ruby→JSON→JS 边界时改变类型；input hash/digest 未 normalize 类型）· view/frontend（inline style 每次 render 都重新解析，view 中使用 O(n·m) lookup，在 app 端而非使用

WHERE

进行 filter）· time-window safety（“今天”未覆盖完整 24 小时，两项 feature 对同一份数据使用两种时间 bucket 规则）· completeness gaps（只完成 80–90%，而达到 100% 只需多写一点代码，测试缺少 negative 分支且容易补充）· distribution & CI/CD（workflow 中的 tool 版本与项目不一致、hardcode secret、tag

v1.2.3

与

1.2.3

不一致、publish 不具备幂等性）。

Severity（提炼自 awesome-skills/code-review-skill）：

[blocking]

= 必须在 merge 前修复 ·

[important]

= 应当修复，如不同意则需要讨论 ·

[nit]

= 小问题，由作者自行决定 ·

[suggestion]

= 值得考虑的其他方案，但不是强制要求。CRITICAL 组偏向

blocking/important

；INFORMATIONAL 组偏向

nit/suggestion

——但 severity 始终依据 finding 的实际影响，不能机械地根据组别决定。

Kết luận (verdict)

结论（verdict）

Một trong hai, kèm lý do:

PASS — không lỗi nặng ở mục nào, sang bước kế được.
CẦN SỬA — liệt kê cụ thể phải sửa gì trước khi pass (ưu tiên security + logic-có-test-đỏ trước naming).

Verdict là ADVISORY — người quyết, không chặn commit. Thứ gác cứng là các test tái hiện (đỏ→xanh). Đừng để user tưởng "qc-code PASS = an toàn tuyệt đối"; nó là một cặp mắt senior, không phải bằng chứng.

以下二者之一，并附理由：

PASS — 没有任何维度存在严重问题，可以进入下一步。
CẦN SỬA — 具体列出通过前必须修改的内容（优先处理 security 和带红色测试的 logic 问题，其次处理 naming）。

Verdict 是 ADVISORY——由用户决定，不会阻止 commit。 真正的硬门禁是复现测试（红→绿）。不要让用户误以为“qc-code PASS = 绝对安全”；它只是一位资深开发者的审查视角，而不是绝对证据。

Verdict JSON + grounding-check

Kèm verdict văn xuôi ở trên, xuất thêm MỘT block JSON có cấu trúc — "nhìn ổn" không phải feedback, nó là schema-invalid và bị chặn tất định:

json

{
  "decision": "revise",
  "claim": "paginate() bỏ sót phần tử cuối khi total % size == 0",
  "reason": "off-by-one ở điều kiện `<` tại api/paginate.py:42",
  "required_evidence": [
    "test qc-off-by-one-pagination chạy ĐỎ trên bản hiện tại",
    "api/paginate.py:42 sau khi sửa dùng `<=`"
  ]
}

```
PASS
```
→
```
decision: "approve"
```
.
```
CẦN SỬA
```
→
```
decision: "revise"
```
+
```
required_evidence
```
là danh sách bằng chứng CỤ THỂ cần bổ sung, mỗi mục trỏ
```
file:line
```
hoặc tên test-case.
```
claim
```
và
```
reason
```
không được rỗng; field lạ chỉ bị cảnh báo, không fail (forward-compat).
Ghi JSON ra harness/out/qc-verdict.json
(trong repo — KHÔNG phải
```
/tmp
```
). Hook
```
PostToolUse
```
thấy tên file kết thúc
```
qc-verdict.json
```
là tự chạy
```
grounding-check
```
ngay lúc ghi; verdict không hợp lệ thì tool-call bị chặn (exit 2) và stderr trả về để sửa tại chỗ.

Không phải nhớ gõ lệnh — cổng nằm ở cấu trúc, không ở lời dặn. Muốn kiểm tay (file ngoài repo, hoặc verdict của người khác):

bash

python3 harness/scripts/grounding-check.py --check <file.json>

exit 0 = hợp lệ; exit 2 = verdict CHƯA hợp lệ, phải viết lại — agent không được nộp verdict mơ hồ hay thiếu bằng chứng.

除上述文字 verdict 外，再输出一个结构化 JSON block——“看起来没问题”不算反馈，它不符合 schema，并会被确定性机制拦截：

json

{
  "decision": "revise",
  "claim": "paginate() bỏ sót phần tử cuối khi total % size == 0",
  "reason": "off-by-one ở điều kiện `<` tại api/paginate.py:42",
  "required_evidence": [
    "test qc-off-by-one-pagination chạy ĐỎ trên bản hiện tại",
    "api/paginate.py:42 sau khi sửa dùng `<=`"
  ]
}

```
PASS
```
→
```
decision: "approve"
```
。
```
CẦN SỬA
```
→
```
decision: "revise"
```
，且
```
required_evidence
```
必须是需要补充的具体证据清单，每项指向
```
file:line
```
或 test-case 名称。
```
claim
```
和
```
reason
```
不得为空；未知字段只会产生警告，不会导致失败（保持 forward-compat）。
将 JSON 写入 harness/out/qc-verdict.json
（位于 repo 内——不是
```
/tmp
```
）。
```
PostToolUse
```
hook 检测到文件名以
```
qc-verdict.json
```
结尾后，会在写入时自动运行
```
grounding-check
```
；verdict 无效时，tool-call 会被阻止（exit 2），并通过 stderr 返回信息以便立即修正。

无需记忆并手动输入命令——门禁存在于结构本身，而不是提示词中。如需手动检查（repo 外的文件，或其他人的 verdict），可运行：

bash

python3 harness/scripts/grounding-check.py --check <file.json>

exit 0 = 有效；exit 2 = verdict 尚无效，必须重写——agent 不得提交含糊不清或缺少证据的 verdict。

Ghi test tái hiện vào dự án

将复现测试写入项目

Mỗi test ở mục logic:

Đặt vào thư mục test chuẩn của dự án — tự phát hiện:
```
tests/
```
·
```
test/
```
·
```
__tests__/
```
· file
```
*_test.py
```
·
```
*.spec.ts
```
·
```
*.test.js
```
cạnh nguồn. Không có → báo rõ và để test cạnh file nguồn, KHÔNG đoán bừa cấu trúc.
Tên
qc-<slug-bug>
(vd
```
qc-off-by-one-pagination
```
) — phân biệt test do qc-code sinh, để
```
qc-regression.py
```
gom được.
Chạy bằng runner có sẵn của dự án (pytest/vitest/jest) — không đẻ framework test mới.
Test PHẢI đỏ trước khi fix (tái hiện), xanh sau khi fix (bằng chứng). Nếu bug quay lại → test đỏ lại (chống tái phát).

logic 维度中的每个测试：

放入项目的标准测试目录——自动检测：
```
tests/
```
·
```
test/
```
·
```
__tests__/
```
· 位于源文件旁的
```
*_test.py
```
·
```
*.spec.ts
```
·
```
*.test.js
```
。若均不存在 → 明确说明并把测试放在源文件旁，不要猜测目录结构。
命名为
qc-<slug-bug>
（例如
```
qc-off-by-one-pagination
```
）——用于区分由 qc-code 生成的测试，以便
```
qc-regression.py
```
收集。
使用项目已有的 runner（pytest/vitest/jest）——不要引入新的 test framework。
测试在修复前必须为红色（成功复现），修复后变为绿色（构成证据）。如果 bug 再次出现，测试应再次变红（防止回归）。

Auto-chạy test (tất định, 0-token)

自动运行测试（确定性，0-token）

python3 harness/scripts/qc-regression.py --run

chạy đúng các test

qc-*

và báo đỏ/xanh — không gọi LLM. Nó auto-chạy ở

verify-before-commit

(trước commit); bật thêm PostToolUse cho phản hồi tức thì nếu muốn. Fail-open nếu chưa có test

qc-*

nào. Đây là phần "tự động hook khi sửa code" — chỉ hook phần rẻ tất định, LLM review (skill này) giữ gọi tay.

python3 harness/scripts/qc-regression.py --run

会准确运行所有

qc-*

测试并报告红/绿状态——不会调用 LLM。它会在

verify-before-commit

阶段自动运行（commit 前）；如需即时反馈，可额外启用 PostToolUse。若尚无

qc-*

测试，则 fail-open。这就是“修改代码时自动触发 hook”的部分——只为低成本、确定性的测试启用 hook；LLM 审查（此 skill）仍保持手动调用。

Branches

ID	Kind	Guard	Hành vi	Skip / failure	Rejoin
B01	user_optional	user chỉ định file/thư mục	soi đúng phạm vi đó thay vì diff	—	W02
B02	conditional_required	mục logic tìm được bug	W03 sinh test đỏ cho từng bug	không có bug → skip W03, W05	W04
B03	user_optional	MÌNH là người nhận finding (từ người, LLM reviewer, kể cả /qc-code)	quy trình "Nhận review — verify trước khi sửa" (mục Reference)	finding sai → phản hồi kỹ thuật kèm bằng chứng	sửa từng mục, test từng mục
B04	capability_optional	muốn phản hồi tức thì	bật thêm PostToolUse chạy `qc-regression.py --run`	mặc định chỉ chạy ở `verify-before-commit`	—

ID	Kind	Guard	行为	Skip / failure	Rejoin
B01	user_optional	用户指定 file/folder	审查该范围，而不是 diff	—	W02
B02	conditional_required	logic 维度找到 bug	W03 为每个 bug 生成红色测试	没有 bug → 跳过 W03、W05	W04
B03	user_optional	自己就是 finding 的接收者（来自人员、LLM reviewer，甚至 /qc-code）	执行“接收审查——修改前验证”流程（见 Reference）	finding 错误 → 给出带证据的技术反馈	逐项修复、逐项测试
B04	capability_optional	需要即时反馈	额外启用 PostToolUse 运行 `qc-regression.py --run`	默认仅在 `verify-before-commit` 时运行	—

Validation và stopping

Validation 与 stopping

Tất định: test

qc-*

đỏ→xanh;

qc-verdict.json

phải qua

python3 harness/scripts/grounding-check.py --check <file.json>

(hook tự chạy khi ghi). Judgment: điểm và verdict (advisory). Dừng khi bốn mục đủ ba phần, mỗi bug có test đỏ, verdict hợp lệ.

确定性：

qc-*

测试必须红→绿；

qc-verdict.json

必须通过

python3 harness/scripts/grounding-check.py --check <file.json>

（hook 会在写入时自动运行）。判断：评分和 verdict（advisory）。当四个维度均具备完整三部分、每个 bug 都有红色测试、verdict 有效时停止。

Examples

Positive: "qc code" trên diff thêm
```
paginate()
```
→ 4 mục có điểm; logic tìm off-by-one
```
<
```
tại
```
api/paginate.py:42
```
→ test
```
qc-off-by-one-pagination
```
ĐỎ; verdict
```
CẦN SỬA
```
+ JSON
```
decision: "revise"
```
có
```
required_evidence
```
trỏ test và
```
file:line
```
; grounding-check exit 0.
Boundary/failure: verdict JSON
```
{"decision":"approve","claim":"","reason":"nhìn ổn"}
```
→
```
claim
```
rỗng → hook chặn exit 2, stderr trả về, phải viết lại; dự án không có
```
tests/
```
→ test đặt cạnh file nguồn và báo rõ.

Positive： 对新增
```
paginate()
```
的 diff 执行“qc code”→ 四个维度均有评分；logic 发现
```
api/paginate.py:42
```
的 off-by-one
```
<
```
→ 测试
```
qc-off-by-one-pagination
```
呈红色；verdict 为
```
CẦN SỬA
```
，且 JSON 的
```
decision: "revise"
```
中
```
required_evidence
```
指向测试和
```
file:line
```
；grounding-check exit 0。
Boundary/failure： verdict JSON 为
```
{"decision":"approve","claim":"","reason":"nhìn ổn"}
```
→
```
claim
```
为空 → hook 以 exit 2 阻止，stderr 返回信息，必须重写；项目没有
```
tests/
```
→ 测试放在源文件旁，并明确说明。

Reference — Nhận review — verify trước khi sửa

Reference — 接收审查 — 修改前验证

Chiều ngược của skill này: khi MÌNH là người nhận finding (từ người, từ LLM reviewer, kể cả từ chính /qc-code). Finding là CLAIM, chưa phải sự thật (distill từ

obra/superpowers

receiving-code-review):

Đọc hết feedback rồi mới phản ứng — restate yêu cầu bằng lời của mình; chỗ nào chưa hiểu thì HỎI trước khi sửa bất kỳ mục nào (các mục có thể liên quan nhau — hiểu một nửa là sửa sai).
Verify claim với code thật — chạy hoặc đọc đúng đoạn được trỏ: claim có đúng với codebase NÀY không, sửa theo có vỡ gì không, code hiện tại có lý do tồn tại không.
Chỉ sửa khi đã tự thấy lỗi — finding sai thì phản hồi bằng lý lẽ kỹ thuật kèm bằng chứng, không lặng lẽ bỏ qua, cũng không lặng lẽ làm theo. Không verify được thì nói thẳng: "chưa kiểm được vì thiếu X".
Sửa từng mục một, test từng mục — không gộp một lượt rồi hy vọng.
Cấm màn diễn đồng thuận — "You're absolutely right!" / khen ngợi feedback thay cho hành động là tín hiệu đang blind-comply. Xác nhận kỹ thuật hoặc bắt tay làm, không diễn.

Blind-comply với review sai tạo ra bug mới mang vẻ mặt "đã được review" — lớp bug khó nghi ngờ nhất.

这是此 skill 的反向流程：当自己接收 finding 时（来自人员、LLM reviewer，甚至来自

/qc-code

本身），finding 只是 CLAIM，并非事实（提炼自

obra/superpowers

的 receiving-code-review）：

读完全部 feedback 后再回应 — 用自己的话复述要求；如果有未理解之处，应在修改任何内容前先询问（各项 finding 可能相互关联——只理解一半就修改，很容易改错）。
使用真实 code 验证 claim — 运行或阅读被指向的具体代码段：claim 在当前这个 codebase 中是否正确、修复后是否会破坏其他内容、当前实现是否具有保留它的合理原因。
只有亲自确认问题后才修改 — 如果 finding 错误，应给出带证据的技术论证，不要默默忽略，也不要默默照做。如果无法验证，应明确说明：“尚未验证，因为缺少 X”。
逐项修复、逐项测试 — 不要把所有内容合并成一次修改，然后寄希望于结果正常。
禁止表演式赞同 — “You're absolutely right!”／用赞美代替行动，是 blind-comply 的信号。应进行技术确认或握手达成共识，不要表演。

Blind-comply 一个错误的 review，可能制造出披着“已经审查过”外衣的新 bug——这是最难发现的 bug 类型。

Origin

Distill từ yêu cầu user 2026-07-15 (qc-code 4 mục + sinh test + auto-hook). Quyết định "nối vào đâu" đã hỏi user → option 3 (LLM thủ công, test auto-hook tất định), phạm vi diff hiện tại.
Absorb qua
```
/propose
```
→
```
150726-qc-code-skill
```
, task
```
T-260715-04
```
.
Absorb 2026-07-17 (adapt_mode: dissolve, T-260717-02): bản đồ 13 nhóm lỗi distill từ
```
garrytan/gstack
```
(
```
review/checklist.md
```
); severity từ
```
awesome-skills/code-review-skill
```
; mục "Nhận review" từ
```
obra/superpowers
```
(
```
receiving-code-review
```
). Clone depth-1 trong scratchpad/, không vendor bytes.
Commit: (verify-before-commit điền)

提炼自用户于 2026-07-15 提出的需求（qc-code 四维评分 + 生成测试 + auto-hook）。关于“接入哪里”的决策已询问用户 → 选择方案 3（手动调用 LLM，测试通过确定性 auto-hook 自动运行），审查范围为当前 diff。
通过
```
/propose
```
接入 →
```
150726-qc-code-skill
```
，task
```
T-260715-04
```
。
2026-07-17 接入（adapt_mode: dissolve，T-260717-02）： 13 组错误映射表提炼自
```
garrytan/gstack
```
（
```
review/checklist.md
```
）；severity 提炼自
```
awesome-skills/code-review-skill
```
；“接收审查”部分提炼自
```
obra/superpowers
```
（
```
receiving-code-review
```
）。在 scratchpad/ 中执行 depth-1 clone，不 vendor bytes。
Commit： （由 verify-before-commit 填写）