ln-637-test-structure-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-*
）都是相对于技能仓库根目录的相对路径。如果在当前工作目录找不到，请定位到该SKILL.md所在目录，向上一级即为仓库根目录。如果
shared/
目录缺失，请通过WebFetch从
https://raw.githubusercontent.com/levnikolaevich/claude-code-skills/master/skills/{path}
拉取文件。

Test Structure Auditor (L3 Worker)

测试结构审计器（L3 Worker）

Type: L3 Worker

Specialized worker auditing test file organization and directory structure for maintainability as the test suite grows.

类型： L3 Worker

专门用于审计测试文件组织和目录结构，保障测试套件规模增长时的可维护性。

Purpose & Scope

用途与范围

Audit Test Structure (Category 8: Medium Priority)
Detect layout pattern (flat / mirrored / co-located / hybrid)
Flag flat directories exceeding growth thresholds with domain grouping recommendations
Verify test-to-source mapping consistency and orphaned tests
Calculate compliance score (X/10)

审计 测试结构（类别8：中等优先级）
识别布局模式（扁平/镜像/同置/混合）
标记超过增长阈值的扁平目录，并给出领域分组建议
校验测试与源码映射一致性，识别孤立测试
计算合规得分（X/10）

Inputs (from Coordinator)

输入（来自协调器）

MANDATORY READ: Load

shared/references/audit_worker_core_contract.md

Receives

contextStore

with:

tech_stack

testFilesMetadata

(ALL types -- both automated and manual),

codebase_root

output_dir

domain_mode

all_domains

Note: Unlike other workers that receive type-filtered metadata, this worker receives ALL test files because directory structure analysis requires the full picture of where both automated and manual tests are placed.

强制阅读： 加载

shared/references/audit_worker_core_contract.md

。

接收的

contextStore

包含：

tech_stack

、

testFilesMetadata

（所有类型——包括自动化和手动测试）、

codebase_root

、

output_dir

、

domain_mode

、

all_domains

。

注意： 与其他接收按类型过滤元数据的Worker不同，该Worker接收所有测试文件，因为目录结构分析需要完整了解自动化和手动测试的存放位置。

Workflow

工作流

MANDATORY READ: Load

shared/references/two_layer_detection.md

for detection methodology.

Parse Context: Extract test file list, output_dir, codebase_root, domain info from contextStore
Map Source Structure: Glob source directories (
```
src/
```
,
```
app/
```
,
```
lib/
```
) to build source domain/module tree
Map Test Structure: Group test files by parent directory, count files per directory, classify locations
Scan Checks (Layer 1): Run 5 audit checks (see Audit Rules) using Glob/Grep patterns
Context Analysis (Layer 2 -- MANDATORY): For each candidate finding, apply Layer 2 filters (see each check)
Collect Findings: Record violations with severity, location, 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}/637-test-structure.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、领域信息
映射源码结构： 遍历源码目录（
```
src/
```
、
```
app/
```
、
```
lib/
```
）构建源码领域/模块树
映射测试结构： 按父目录对测试文件分组，统计每个目录的文件数量，对存放位置分类
扫描检查（第一层）： 采用Glob/Grep模式运行5项审计检查（见审计规则）
上下文分析（第二层——强制）： 对每个候选发现，应用第二层过滤器（见各检查项说明）
收集发现结果： 记录违规项，包含严重级别、位置、工作量、整改建议
计算得分： 按严重级别统计违规项，计算合规得分（X/10）

编写报告： 按照

shared/templates/audit_worker_report_template.md

在内存中构建完整的markdown报告，单次写入到

{output_dir}/637-test-structure.md

返回摘要： 向协调器返回精简摘要（见输出格式）

Audit Rules

审计规则

1. Layout Pattern Detection

1. 布局模式识别

What: Detect which test organization pattern the project uses and check for unintentional mixing

Detection:

Classify each test file location:
- Co-located: test file in same directory as source file (e.g.,
```
src/users/users.test.ts
```
  )
- Mirrored: test file in parallel hierarchy (e.g.,
```
tests/users/users.test.ts
```
  mirrors
```
src/users/
```
  )
- Centralized-flat: all tests in single directory (e.g.,
```
tests/
```
  or
```
__tests__/
```
  )
- Manual: files in
```
tests/manual/
```
  (informational, not flagged)
Calculate distribution percentages across patterns
If >70% files follow one pattern -> that is the dominant pattern
If no pattern reaches 70% -> hybrid

Layer 2:

Hybrid is acceptable if different test TYPES use different patterns (e.g., unit tests co-located + integration tests in
```
tests/automated/integration/
```
). Check if deviation correlates with test type
Projects with <5 test files -> skip (too small to establish pattern)

Severity: MEDIUM if hybrid without clear type-based rule (>30% of same-type tests deviate from dominant pattern)

Recommendation: Standardize test placement -- choose one pattern per test type and document in testing guidelines

Effort: L

内容： 识别项目使用的测试组织模式，检查是否存在非预期的模式混用

检测逻辑：

对每个测试文件的存放位置分类：
- Co-located（同置）： 测试文件与源码文件存放在同一目录（例如
```
src/users/users.test.ts
```
  ）
- Mirrored（镜像）： 测试文件存放在平行的层级结构中（例如
```
tests/users/users.test.ts
```
  对应镜像
```
src/users/
```
  ）
- Centralized-flat（集中扁平）： 所有测试存放在单个目录（例如
```
tests/
```
  或
```
__tests__/
```
  ）
- Manual（手动）： 存放在
```
tests/manual/
```
  的文件（仅作信息展示，不标记违规）
计算各模式的分布占比
如果>70%的文件遵循同一模式 -> 该模式为核心模式
没有模式占比达到70% -> 混合模式

第二层过滤：

如果不同测试类型使用不同模式，混合模式是可接受的（例如单元测试同置+集成测试存放在
```
tests/automated/integration/
```
）。检查偏差是否与测试类型相关
测试文件少于5个的项目 -> 跳过（样本太少无法确定模式）

严重级别： MEDIUM 如果混合模式没有明确的基于类型的规则（同类型测试中>30%偏离核心模式）

整改建议： 标准化测试存放规则——每种测试类型选择一种模式，并在测试指南中归档说明

工作量： L

2. Test-to-Source Mapping

2. 测试与源码映射校验

What: Detect orphaned test files (source file deleted but test remains) and mismatched paths

Detection:

For each test file, extract the implied source module:

```
users.test.ts
```
->
```
users.ts
```
or
```
users/index.ts
```
```
test_payments.py
```
->
```
payments.py
```

Check if the implied source file exists in the expected location
If source file not found -> orphaned test candidate

Layer 2:

Skip integration/e2e tests (test multiple modules, no 1:1 source mapping)
Skip tests in centralized-flat layout (no path-based mapping expected)
Skip test files that import from multiple source modules (integration tests by nature)
Skip utility/helper test files (
```
test_utils.ts
```
,
```
test_helpers.py
```
)

Severity: MEDIUM for orphaned tests (dead code), LOW for path mismatches

Recommendation: Delete orphaned tests or update to match current source structure

Effort: S

内容： 识别孤立测试文件（源码文件已删除但测试文件留存）和路径不匹配问题

检测逻辑：

对每个测试文件，推导其对应的源码模块：
- ```
users.test.ts
```
  ->
```
users.ts
```
  或
```
users/index.ts
```
- ```
test_payments.py
```
  ->
```
payments.py
```
检查推导的源码文件是否存在于预期位置
源码文件不存在 -> 标记为孤立测试候选

第二层过滤：

跳过集成/端到端测试（测试多个模块，无1:1源码映射）
跳过集中扁平布局下的测试（无基于路径的映射要求）
跳过从多个源码模块导入的测试文件（本质为集成测试）
跳过工具/辅助测试文件（
```
test_utils.ts
```
、
```
test_helpers.py
```
）

严重级别： 孤立测试为MEDIUM（死代码），路径不匹配为LOW

整改建议： 删除孤立测试，或更新测试匹配当前源码结构

工作量： S

3. Flat Directory Growth

3. 扁平目录增长检查

What: Detect test directories with excessive file count that would benefit from subdirectory grouping

Detection:

Count test files per directory (excluding
```
node_modules
```
,
```
dist
```
,
```
build
```
)
Thresholds:
- 15-20 files in one flat directory -> LOW (approaching limit)
- >20 files in one flat directory -> MEDIUM (restructure recommended)
For MEDIUM findings, suggest domain-based grouping by analyzing file name prefixes:
- Group by common prefix (e.g.,
```
test_auth_*.py
```
  ->
```
auth/
```
  subdirectory)
- Cross-reference with source domain structure if available

Layer 2:

Skip if directory already has subdirectories (partially organized)
Skip if files use clear naming prefixes that provide sufficient organization without subdirectories
Skip
```
tests/manual/
```
(manual test structure has separate conventions)

Severity: MEDIUM (>20 files), LOW (15-20 files)

Recommendation: Group tests into subdirectories by domain/feature. Suggest specific grouping based on file name analysis:

undefined

内容： 识别文件数量过多、适合通过子目录分组优化的测试目录

检测逻辑：

统计每个目录下的测试文件数量（排除
```
node_modules
```
、
```
dist
```
、
```
build
```
）
阈值规则：
- 单个扁平目录下有15-20个文件 -> LOW（接近阈值）
- 单个扁平目录下>20个文件 -> MEDIUM（建议重构）
针对MEDIUM级别的发现，通过分析文件名前缀给出基于领域的分组建议：
- 按通用前缀分组（例如
```
test_auth_*.py
```
  -> 归到
```
auth/
```
  子目录）
- 如有源码领域结构可交叉参考

第二层过滤：

目录已有子目录（已部分组织）-> 跳过
文件使用清晰的命名前缀，无需子目录即可实现足够组织性 -> 跳过
跳过
```
tests/manual/
```
（手动测试结构有独立规范）

严重级别： MEDIUM（>20个文件）、LOW（15-20个文件）

整改建议： 按领域/功能将测试分组到子目录中。基于文件名分析给出具体分组建议：

undefined

Before (flat):

整改前（扁平结构）:

tests/test_auth_login.py, tests/test_auth_tokens.py, tests/test_users_crud.py, ...

After (grouped):

整改后（分组结构）:

tests/auth/test_login.py, tests/auth/test_tokens.py, tests/users/test_crud.py, ...


**Effort:** M

tests/auth/test_login.py, tests/auth/test_tokens.py, tests/users/test_crud.py, ...


**工作量：** M

4. Domain Grouping Alignment

4. 领域分组对齐校验

What: Check whether test directory grouping mirrors source domain structure

Detection:

Compare source domain directories (from
```
all_domains
```
or scanned
```
src/
```
) with test directory names
For each source domain, check if a corresponding test group exists:
- Mirrored layout:
```
tests/{domain}/
```
  directory exists
- Co-located: test files exist in
```
src/{domain}/
```
Flag source domains with zero corresponding test groups

Layer 2:

Skip if project has no clear domain structure (
```
domain_mode="global"
```
or <2 source domains)
Skip shared/common/utils domains (cross-cutting, may not need dedicated test group)
Skip if project uses centralized-flat layout (no grouping expected)

Severity: MEDIUM for domains with >5 source files but no test group, LOW otherwise

Recommendation: Create test directory/group for domain to maintain structural alignment

Effort: M

内容： 检查测试目录分组是否与源码领域结构镜像对齐

检测逻辑：

对比源码领域目录（来自
```
all_domains
```
或扫描的
```
src/
```
目录）与测试目录名称
对每个源码领域，检查是否存在对应的测试分组：
- 镜像布局：存在
```
tests/{domain}/
```
  目录
- 同置布局：
```
src/{domain}/
```
  目录下存在测试文件
标记没有对应测试分组的源码领域

第二层过滤：

项目无清晰领域结构（
```
domain_mode="global"
```
或源码领域少于2个）-> 跳过
跳过共享/通用/工具类领域（跨领域使用，无需独立测试分组）
项目使用集中扁平布局（无分组要求）-> 跳过

严重级别： 源码文件>5个但无对应测试分组的领域为MEDIUM，其余为LOW

整改建议： 为对应领域创建测试目录/分组，保持结构对齐

工作量： M

5. Co-location Consistency

5. 同置规则一致性校验

What: Detect which co-location pattern the project uses and flag inconsistencies

Detection:

Count test files placed next to source files vs. in dedicated test directories
Calculate ratio: co-located / (co-located + centralized)
If ratio 0.0-0.2 -> centralized pattern
If ratio 0.8-1.0 -> co-located pattern
If ratio 0.2-0.8 -> mixed (potential inconsistency)
For mixed: identify which modules deviate from the dominant pattern

Layer 2:

Mixed is acceptable if different test types use different placement:
- Unit tests co-located + integration/e2e tests centralized -> valid hybrid
- Check test file naming/location correlation with type
Projects with <5 test files -> skip

Severity: MEDIUM if >20% of same-type tests deviate from dominant placement pattern

Recommendation: Consolidate test placement -- move deviating tests to follow the project's dominant pattern

Effort: M-L

内容： 识别项目使用的同置模式，标记不一致的配置

检测逻辑：

统计存放在源码旁的测试文件数量，对比存放在专用测试目录的数量
计算占比：同置测试数量 /（同置测试数量 + 集中存放测试数量）
占比0.0-0.2 -> 集中模式
占比0.8-1.0 -> 同置模式
占比0.2-0.8 -> 混合模式（可能存在不一致）
针对混合模式：识别偏离核心模式的模块

第二层过滤：

不同测试类型使用不同存放规则的混合模式是可接受的：
- 单元测试同置 + 集成/端到端测试集中存放 -> 合法混合模式
- 检查测试文件命名/位置与测试类型的相关性
测试文件少于5个的项目 -> 跳过

严重级别： 同类型测试中>20%偏离核心存放模式则为MEDIUM

整改建议： 统一测试存放规则——将偏离的测试迁移到符合项目核心模式的位置

工作量： M-L

Scoring Algorithm

评分算法

MANDATORY READ: Load

shared/references/audit_worker_core_contract.md

and

shared/references/audit_scoring.md

Severity mapping:

Orphaned tests, Excessive flat directory (>20), Inconsistent layout, Inconsistent co-location -> MEDIUM
Approaching flat directory limit (15-20), Missing domain test group (small domain), Path mismatch -> LOW

强制阅读： 加载

shared/references/audit_worker_core_contract.md

和

shared/references/audit_scoring.md

。

严重级别映射：

孤立测试、扁平目录文件过多（>20）、布局不一致、同置规则不一致 -> MEDIUM
接近扁平目录阈值（15-20）、小型领域缺失测试分组、路径不匹配 -> LOW

Output Format

输出格式

MANDATORY READ: Load

shared/references/audit_worker_core_contract.md

and

shared/templates/audit_worker_report_template.md

If summaryArtifactPath is present, write JSON summary per shared/references/audit_summary_contract.md. Compact text output is fallback only.

Write report to

{output_dir}/637-test-structure.md

with

category: "Test Structure"

and checks: layout_pattern, test_source_mapping, flat_dir_growth, domain_grouping, colocation_consistency.

Return summary per

shared/references/audit_summary_contract.md

Legacy compact text output is allowed only when

summaryArtifactPath

is absent:

Report written: .hex-skills/runtime-artifacts/runs/{run_id}/audit-report/637-test-structure.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

。

如果存在summaryArtifactPath，按照shared/references/audit_summary_contract.md要求写入JSON摘要。仅在无其他选项时使用精简文本输出作为兜底。

将报告写入

{output_dir}/637-test-structure.md

，包含

category: "Test Structure"

和检查项：layout_pattern, test_source_mapping, flat_dir_growth, domain_grouping, colocation_consistency。

按照

shared/references/audit_summary_contract.md

要求返回摘要。

仅当

summaryArtifactPath

不存在时允许使用旧版精简文本输出：

Report written: .hex-skills/runtime-artifacts/runs/{run_id}/audit-report/637-test-structure.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, suggest restructuring
Effort realism: S = <1h, M = 1-4h, L = >4h
Skip when trivial: If <5 test files total, return score 10/10 with zero findings
No naming check: Test naming consistency (
```
.test.
```
vs
```
.spec.
```
) is out of scope -- do not duplicate
Both types: Analyze both automated and manual test file locations for complete layout picture
Concrete suggestions: For flat directory growth findings, always suggest specific subdirectory grouping based on file name prefix analysis

强制阅读： 加载

shared/references/audit_worker_core_contract.md

。

禁止自动修复： 仅做报告输出，给出重构建议即可
工作量写实： S = <1小时, M = 1-4小时, L = >4小时
** trivial场景跳过：** 如果总测试文件少于5个，直接返回10/10分，无任何问题发现
不做命名检查： 测试命名一致性（
```
.test.
```
与
```
.spec.
```
对比）不在范围内，不要重复校验
覆盖两种测试类型： 同时分析自动化和手动测试文件位置，得到完整的布局视图
给出具体建议： 针对扁平目录增长的发现，始终基于文件名前缀分析给出具体的子目录分组建议

Definition of Done

完成定义

MANDATORY READ: Load

shared/references/audit_worker_core_contract.md

contextStore parsed successfully (including output_dir, domain info)
Source structure mapped (domain/module tree)
Test structure mapped (files grouped by directory, counts calculated)
All 5 checks completed
Layer 2 context analysis applied (type-based hybrid, small project exclusions)
Layout pattern detected and documented in report
Flat directory growth signals identified with specific grouping suggestions
Findings collected with severity, location, effort, recommendation
Score calculated using penalty algorithm
Report written to
```
{output_dir}/637-test-structure.md
```
(atomic single Write call)
Summary written per contract

Version: 1.0.0 Last Updated: 2026-03-15

强制阅读： 加载

shared/references/audit_worker_core_contract.md

。

contextStore解析成功（包含output_dir、领域信息）
源码结构映射完成（领域/模块树）
测试结构映射完成（按目录分组的文件、统计数量）
所有5项检查完成
已应用第二层上下文分析（基于类型的混合模式、小型项目排除规则）
布局模式已识别并写入报告
扁平目录增长信号已识别，并给出具体分组建议
问题发现已收集，包含严重级别、位置、工作量、整改建议
已通过扣减算法计算得分
报告已写入
```
{output_dir}/637-test-structure.md
```
（原子单次写入）
摘要已按合约要求写入

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