ln-636-manual-test-auditor

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Paths: File paths (
shared/
,
references/
,
../ln-*
) are relative to skills repo root. If not found at CWD, locate this SKILL.md directory and go up one level for repo root. If
shared/
is missing, fetch files via WebFetch from
https://raw.githubusercontent.com/levnikolaevich/claude-code-skills/master/skills/{path}
.

路径： 文件路径（
shared/
、
references/
、
../ln-*
）是相对于技能仓库根目录的。如果在当前工作目录（CWD）中未找到，请定位到本SKILL.md所在目录，然后向上一级找到仓库根目录。如果
shared/
目录缺失，请通过WebFetch从
https://raw.githubusercontent.com/levnikolaevich/claude-code-skills/master/skills/{path}
获取文件。

Manual Test Quality Auditor (L3 Worker)

手动测试质量审核器（L3 Worker）

Specialized worker auditing manual test scripts for quality and best-practice compliance.

专门用于审核手动测试脚本质量与最佳实践合规性的Worker。

Purpose & Scope

目标与范围

Worker in ln-630 coordinator pipeline
Audit Manual Test Quality (Category 7: Medium Priority)
Evaluate bash test scripts in
```
tests/manual/
```
against quality dimensions
Calculate compliance score (X/10)

ln-630协调器流水线中的Worker
审核手动测试质量（类别7：中等优先级）
评估
```
tests/manual/
```
目录下的bash测试脚本是否符合质量维度要求
计算合规分数（X/10）

Inputs (from Coordinator)

输入（来自协调器）

MANDATORY READ: Load

shared/references/audit_worker_core_contract.md

Receives

contextStore

with:

tech_stack

testFilesMetadata

(filtered to

type: "manual"

codebase_root

output_dir

Manual test metadata includes:

suite_dir

has_expected_dir

harness_sourced

必读： 加载

shared/references/audit_worker_core_contract.md

文件。

接收包含以下内容的

contextStore

：

tech_stack

、

testFilesMetadata

（已过滤为

type: "manual"

）、

codebase_root

、

output_dir

。

手动测试元数据包括：

suite_dir

、

has_expected_dir

、

harness_sourced

。

Workflow

工作流程

MANDATORY READ: Load

shared/references/two_layer_detection.md

for detection methodology.

Parse Context: Extract manual test file list, output_dir, codebase_root from contextStore
Discover Infrastructure: Detect shared infrastructure files:
- ```
tests/manual/config.sh
```
  — shared configuration
- ```
tests/manual/test_harness.sh
```
  — shared test framework (if exists)
- ```
tests/manual/test-all.sh
```
  — master runner
- ```
tests/manual/TEMPLATE-*.sh
```
  — test templates (if exist)
- ```
tests/manual/regenerate-golden.sh
```
  — golden file regeneration (if exists)
Scan Scripts (Layer 1): For each manual test script, check 7 quality dimensions (see Audit Rules) 3b) Context Analysis (Layer 2 -- MANDATORY): For each candidate finding, ask:
- Is this a setup/utility script (e.g.,
```
00-setup/*.sh
```
  ,
```
tools/*.sh
```
  )? Setup scripts have different requirements -- skip harness/golden checks
- Is this a master runner (
```
test-all.sh
```
  )? Master runners orchestrate, not test -- skip all checks except fail-fast
- Does the project not use a shared harness at all? If no
```
test_harness.sh
```
  exists, harness adoption check is N/A
Collect Findings: Record violations with severity, location (file:line), effort, recommendation
Calculate Score: Count violations by severity, calculate compliance score (X/10)

Write Report: Build full markdown report in memory per

shared/templates/audit_worker_report_template.md

, write to

{output_dir}/636-manual-test-quality.md

in single Write call

Return Summary: Return minimal summary to coordinator (see Output Format)

必读： 加载

shared/references/two_layer_detection.md

以了解检测方法。

解析上下文： 从contextStore中提取手动测试文件列表、output_dir和codebase_root
发现基础设施： 检测共享基础设施文件：
- ```
tests/manual/config.sh
```
  —— 共享配置文件
- ```
tests/manual/test_harness.sh
```
  —— 共享测试框架（如果存在）
- ```
tests/manual/test-all.sh
```
  —— 主运行脚本
- ```
tests/manual/TEMPLATE-*.sh
```
  —— 测试模板（如果存在）
- ```
tests/manual/regenerate-golden.sh
```
  —— 黄金文件重新生成脚本（如果存在）
扫描脚本（第一层）： 对每个手动测试脚本，检查7个质量维度（见审核规则） 3b) 上下文分析（第二层——必填）： 对每个候选问题，确认：
- 这是否是设置/实用工具脚本（例如
```
00-setup/*.sh
```
  、
```
tools/*.sh
```
  ）？设置脚本有不同的要求——跳过框架/黄金文件检查
- 这是否是主运行脚本（
```
test-all.sh
```
  ）？主运行脚本用于编排而非测试——除快速失败机制外，跳过所有检查
- 项目是否完全未使用共享框架？如果项目中不存在
```
test_harness.sh
```
  ，则框架采用情况检查不适用
收集问题： 记录问题的严重程度、位置（文件:行号）、修复工作量和建议
计算分数： 按严重程度统计问题数量，计算合规分数（X/10）
生成报告： 根据
```
shared/templates/audit_worker_report_template.md
```
在内存中构建完整的Markdown报告，通过单次写入操作保存到
```
{output_dir}/636-manual-test-quality.md
```
返回摘要： 向协调器返回极简摘要（见输出格式）

Audit Rules

审核规则

1. Harness Adoption

1. 测试框架采用情况

What: Test script uses shared framework (

run_test

init_test_state

) instead of custom assertion logic

Detection:

Grep for
```
run_test
```
,
```
init_test_state
```
in script
If absent AND script contains custom test loops/assertions → custom logic
If
```
test_harness.sh
```
does not exist in project → skip this check entirely

Severity: HIGH (custom logic = maintenance burden, inconsistent reporting)

Recommendation: Refactor to use shared

run_test

from test_harness.sh

Effort: M

检查内容： 测试脚本是否使用共享框架（

run_test

、

init_test_state

）而非自定义断言逻辑

检测方式：

在脚本中搜索
```
run_test
```
、
```
init_test_state
```
如果未找到，且脚本包含自定义测试循环/断言逻辑 → 存在自定义逻辑
如果项目中不存在
```
test_harness.sh
```
→ 完全跳过此检查

严重程度： 高（自定义逻辑会增加维护负担，导致报告不一致）

建议： 重构为使用

test_harness.sh

中的共享

run_test

方法

修复工作量： M

2. Golden File Completeness

2. 黄金文件完整性

What: Test suite has

expected/

directory with reference files matching test scenarios

Detection:

Check if suite directory has
```
expected/
```
subdirectory
Compare: number of test scenarios (grep
```
run_test
```
calls) vs number of expected files
If test uses
```
diff
```
against expected files but expected dir is missing → finding

Layer 2: Not all tests need golden files. Tests validating HTTP status codes, timing, or dynamic data may legitimately skip golden comparison → skip if test has no

diff

or comparison against files

Severity: HIGH (no golden files = no regression detection for output correctness)

Recommendation: Add expected/ directory with reference output files

Effort: M

检查内容： 测试套件是否包含

expected/

目录，且其中的参考文件与测试场景匹配

检测方式：

检查套件目录是否包含
```
expected/
```
子目录
对比：测试场景数量（搜索
```
run_test
```
调用次数）与预期文件数量
如果测试使用
```
diff
```
对比预期文件，但预期目录缺失 → 记录问题

第二层分析： 并非所有测试都需要黄金文件。验证HTTP状态码、计时或动态数据的测试可合理跳过黄金文件对比 → 如果测试中没有

diff

或文件对比逻辑，则跳过此检查

严重程度： 高（无黄金文件则无法检测输出正确性的回归问题）

建议： 添加

expected/

目录及参考输出文件

修复工作量： M

3. Config Sourcing

3. 配置来源

What: Script sources shared

config.sh

for consistent configuration

Detection:

Grep for
```
source.*config.sh
```
or
```
. .*config.sh
```
If absent → script manages its own BASE_URL, tokens, etc.

Layer 2: If script is self-contained utility (e.g.,

tools/*.sh

) → skip

Severity: MEDIUM

Recommendation: Add

source "$THIS_DIR/../config.sh"

for shared configuration

Effort: S

检查内容： 脚本是否通过共享

config.sh

获取一致的配置

检测方式：

搜索
```
source.*config.sh
```
或
```
. .*config.sh
```
如果未找到 → 脚本自行管理BASE_URL、令牌等配置

第二层分析： 如果脚本是独立的实用工具（例如

tools/*.sh

） → 跳过此检查

严重程度： 中

建议： 添加

source "$THIS_DIR/../config.sh"

以使用共享配置

修复工作量： S

4. Fail-Fast Compliance

4. 快速失败合规性

What: Script uses

set -e

and returns exit code 1 on failure

Detection:

Grep for
```
set -e
```
(or
```
set -eo pipefail
```
)
Check that failure paths lead to non-zero exit (not swallowed by
```
|| true
```
everywhere)

Severity: HIGH (silent failures mask broken tests)

Recommendation: Add

set -e

at script start, ensure test failures propagate

Effort: S

检查内容： 脚本是否使用

set -e

，并在失败时返回退出码1

检测方式：

搜索
```
set -e
```
（或
```
set -eo pipefail
```
）
检查失败路径是否返回非零退出码（未被
```
|| true
```
普遍屏蔽）

严重程度： 高（静默失败会掩盖测试故障）

建议： 在脚本开头添加

set -e

，确保测试失败能正确传播

修复工作量： S

5. Template Compliance

5. 模板合规性

What: Script follows project test templates (TEMPLATE-api-endpoint.sh, TEMPLATE-document-format.sh)

Detection:

If TEMPLATE files exist in
```
tests/manual/
```
, check structural alignment:
- Header comment block with description, ACs tested, prerequisites
- Standard variable naming (
```
THIS_DIR
```
  ,
```
EXPECTED_DIR
```
  )
- Standard setup pattern (
```
source config.sh
```
  ,
```
check_jq
```
  ,
```
setup_auth
```
  )
If NO templates exist in project → skip this check entirely

Layer 2: Older scripts written before templates may diverge. Flag as MEDIUM, not HIGH

Severity: MEDIUM

Recommendation: Align script structure with project TEMPLATE files

Effort: M

检查内容： 脚本是否遵循项目测试模板（TEMPLATE-api-endpoint.sh、TEMPLATE-document-format.sh等）

检测方式：

如果
```
tests/manual/
```
目录下存在TEMPLATE文件，检查结构是否一致：
- 包含描述、测试验收标准、前置条件的头部注释块
- 标准变量命名（
```
THIS_DIR
```
  、
```
EXPECTED_DIR
```
  ）
- 标准设置模式（
```
source config.sh
```
  、
```
check_jq
```
  、
```
setup_auth
```
  ）
如果项目中不存在模板文件 → 完全跳过此检查

第二层分析： 模板出现前编写的旧脚本可能存在差异，标记为中等严重程度，而非高

严重程度： 中

建议： 调整脚本结构以匹配项目TEMPLATE文件

修复工作量： M

6. Idempotency

6. 幂等性

What: Script can be rerun safely without side effects from previous runs

Detection:

Grep for cleanup patterns:
```
trap.*EXIT
```
,
```
rm -f
```
,
```
cleanup
```
functions
Check for temp file creation without cleanup
Check for hardcoded resource names that would conflict on rerun (e.g., creating user with fixed email without checking existence)

Layer 2: Scripts that only READ data (GET requests, queries) are inherently idempotent → skip

Severity: MEDIUM

Recommendation: Add cleanup trap or use unique identifiers per run

Effort: S-M

检查内容： 脚本可安全重复运行，不会因前次运行产生副作用

检测方式：

搜索清理模式：
```
trap.*EXIT
```
、
```
rm -f
```
、
```
cleanup
```
函数
检查是否存在未清理的临时文件创建操作
检查是否存在硬编码资源名称，导致重复运行时冲突（例如，创建固定邮箱的用户但未检查是否已存在）

第二层分析： 仅读取数据的脚本（GET请求、查询）本身具有幂等性 → 跳过此检查

严重程度： 中

建议： 添加清理陷阱或每次运行使用唯一标识符

修复工作量： S-M

7. Documentation

7. 文档

What: Test suite directory has README.md explaining purpose and prerequisites

Detection:

Check if suite directory (
```
NN-feature/
```
) contains README.md
If missing → finding

Layer 2: Setup directories (

00-setup/

) and utility directories (

tools/

) may not need README → skip

Severity: LOW

Recommendation: Add README.md with test purpose, prerequisites, usage

Effort: S

检查内容： 测试套件目录是否包含README.md，说明测试目标和前置条件

检测方式：

检查套件目录（
```
NN-feature/
```
）是否包含README.md
如果缺失 → 记录问题

第二层分析： 设置目录（

00-setup/

）和实用工具目录（

tools/

）可能不需要README → 跳过此检查

严重程度： 低

建议： 添加README.md，包含测试目标、前置条件和使用方法

修复工作量： S

Scoring Algorithm

评分算法

MANDATORY READ: Load

shared/references/audit_worker_core_contract.md

and

shared/references/audit_scoring.md

Severity mapping:

Missing harness adoption (when harness exists), No golden files (when expected-based), No fail-fast → HIGH
Missing config sourcing, Template divergence, No idempotency → MEDIUM
Missing README → LOW

必读： 加载

shared/references/audit_worker_core_contract.md

和

shared/references/audit_scoring.md

。

严重程度映射：

未采用测试框架（当框架存在时）、无黄金文件（当基于预期结果测试时）、无快速失败机制 → 高
未使用共享配置、与模板不符、无幂等性 → 中
缺少README → 低

Output Format

输出格式

MANDATORY READ: Load

shared/references/audit_worker_core_contract.md

and

shared/templates/audit_worker_report_template.md

Write report to

{output_dir}/636-manual-test-quality.md

with

category: "Manual Test Quality"

and checks: harness_adoption, golden_file_completeness, config_sourcing, fail_fast_compliance, template_compliance, idempotency, documentation.

Return summary to coordinator:

Report written: docs/project/.audit/ln-630/{YYYY-MM-DD}/636-manual-test-quality.md
Score: X.X/10 | Issues: N (C:N H:N M:N L:N)

必读： 加载

shared/references/audit_worker_core_contract.md

和

shared/templates/audit_worker_report_template.md

。

将报告写入

{output_dir}/636-manual-test-quality.md

，设置

category: "Manual Test Quality"

，并包含以下检查项：harness_adoption、golden_file_completeness、config_sourcing、fail_fast_compliance、template_compliance、idempotency、documentation。

向协调器返回摘要：

Report written: docs/project/.audit/ln-630/{YYYY-MM-DD}/636-manual-test-quality.md
Score: X.X/10 | Issues: N (C:N H:N M:N L:N)

Critical Rules

关键规则

MANDATORY READ: Load

shared/references/audit_worker_core_contract.md

Do not auto-fix: Report only
Effort realism: S = <1h, M = 1-4h, L = >4h
Skip when empty: If no
```
tests/manual/
```
directory exists, return score 10/10 with zero findings

Exclude non-test files: Skip

config.sh

test_harness.sh

test-all.sh

regenerate-golden.sh

TEMPLATE-*.sh

, files in

tools/

results/

test-runs/

Context-aware: Setup scripts (
```
00-setup/
```
) have relaxed requirements (no golden files, no harness needed)

必读： 加载

shared/references/audit_worker_core_contract.md

。

请勿自动修复： 仅生成报告
工作量定义： S = <1小时，M = 1-4小时，L = >4小时
无文件时跳过： 如果
```
tests/manual/
```
目录不存在，返回10/10的分数，且无问题记录

排除非测试文件： 跳过

config.sh

、

test_harness.sh

、

test-all.sh

、

regenerate-golden.sh

、

TEMPLATE-*.sh

，以及

tools/

、

results/

、

test-runs/

目录下的文件

上下文感知： 设置目录（
```
00-setup/
```
）下的脚本要求更宽松（无需黄金文件、无需框架）

Definition of Done

完成标准

MANDATORY READ: Load

shared/references/audit_worker_core_contract.md

contextStore parsed successfully (including output_dir)
Manual test infrastructure discovered (config.sh, harness, templates)
All 7 checks completed per test script
Layer 2 context analysis applied (setup/utility exclusions)
Findings collected with severity, location, effort, recommendation
Score calculated using penalty algorithm
Report written to
```
{output_dir}/636-manual-test-quality.md
```
(atomic single Write call)
Summary returned to coordinator

必读： 加载

shared/references/audit_worker_core_contract.md

。

成功解析contextStore（包括output_dir）
发现了手动测试基础设施（config.sh、测试框架、模板）
完成了所有7项针对测试脚本的检查
应用了第二层上下文分析（排除设置/实用工具脚本）
收集了包含严重程度、位置、工作量和建议的问题记录
使用惩罚算法计算了分数
将报告写入
```
{output_dir}/636-manual-test-quality.md
```
（原子单次写入操作）
向协调器返回了摘要

Reference Files

参考文件

Audit output schema:

shared/references/audit_output_schema.md

Version: 1.0.0 Last Updated: 2026-03-13

审核输出 schema：

shared/references/audit_output_schema.md

版本： 1.0.0 最后更新： 2026-03-13