review-llm-artifacts

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

LLM Artifacts Review

LLM编码不良产物评审

Detect common artifacts left behind by LLM coding agents: over-abstraction, dead code, DRY violations in tests, verbose comments, and defensive overkill.

检测LLM编码Agent留下的常见不良产物：过度抽象、死代码、测试中的DRY原则违反、冗余注释以及过度防御性代码。

Arguments

参数

```
--all
```
: Scan entire codebase (default: changed files from main)
```
--parallel
```
: Force parallel execution (default when 4+ files)
Path: Target directory (default: current working directory)

```
--all
```
: 扫描整个代码库（默认：从main分支变更的文件）
```
--parallel
```
: 强制并行执行（当文件数≥4时默认启用）
路径：目标目录（默认：当前工作目录）

Step 1: Determine Scope

步骤1：确定扫描范围

Parse

$ARGUMENTS

for flags and path:

bash

undefined

解析

$ARGUMENTS

获取标志和路径：

bash

undefined

Default: changed files from main

默认：从main分支变更的文件

git diff --name-only $(git merge-base HEAD main)..HEAD | grep -E '.(py|ts|tsx|js|jsx|go|rs|java|rb|swift|kt)$'

If --all flag: scan entire codebase

如果使用--all标志：扫描整个代码库

find . -type f ( -name ".py" -o -name ".ts" -o -name ".tsx" -o -name ".js" -o -name ".jsx" -o -name ".go" -o -name ".rs" -o -name ".java" -o -name ".rb" -o -name ".swift" -o -name ".kt" ) ! -path "/node_modules/" ! -path "/.git/" ! -path "/vendor/" ! -path "/pycache/*"


If no files found, exit with: "No files to scan. Check your branch has changes or use --all to scan the entire codebase."


如果未找到文件，退出并提示："无文件可扫描。请检查你的分支是否有变更，或使用--all扫描整个代码库。"

Step 2: Detect Languages

步骤2：检测编程语言

Extract unique file extensions from the file list:

bash

undefined

从文件列表中提取唯一的文件扩展名：

bash

undefined

Get unique extensions

获取唯一扩展名

echo "$FILES" | sed 's/.*.//' | sort -u


Map extensions to language names for the report:
- `.py` -> Python
- `.ts`, `.tsx` -> TypeScript
- `.js`, `.jsx` -> JavaScript
- `.go` -> Go
- `.rs` -> Rust
- `.java` -> Java
- `.rb` -> Ruby
- `.swift` -> Swift
- `.kt` -> Kotlin

echo "$FILES" | sed 's/.*.//' | sort -u


将扩展名映射为报告中的语言名称：
- `.py` -> Python
- `.ts`, `.tsx` -> TypeScript
- `.js`, `.jsx` -> JavaScript
- `.go` -> Go
- `.rs` -> Rust
- `.java` -> Java
- `.rb` -> Ruby
- `.swift` -> Swift
- `.kt` -> Kotlin

Step 3: Spawn Parallel Subagents

步骤3：启动并行子Agent

If file count >= 4 OR

--parallel

flag is set, spawn 4 subagents via

Task

tool.

Each subagent MUST:

Load the skill:

Skill(skill: "beagle-core:llm-artifacts-detection")

Review only its assigned category
Return findings in the structured format below

如果文件数≥4或设置了

--parallel

标志，通过

Task

工具启动4个子Agent。

每个子Agent必须：

加载技能：

Skill(skill: "beagle-core:llm-artifacts-detection")

仅评审其分配的类别
按以下结构化格式返回检测结果

Subagent 1: Tests Agent

子Agent 1：测试Agent

Focus: Testing anti-patterns from LLM generation

DRY violations (repeated setup code, duplicate assertions)
Testing library/framework code instead of application logic
Wrong mock boundaries (mocking too much or too little)
Overly verbose test names that describe implementation
Tests that just mirror the implementation

关注点： LLM生成代码中的测试反模式

DRY原则违反（重复的初始化代码、重复断言）
测试库/框架代码而非应用逻辑
错误的Mock边界（Mock过多或过少）
过于冗长的测试名称（描述实现细节）
完全镜像实现逻辑的测试

Subagent 2: Dead Code Agent

子Agent 2：死代码Agent

Focus: Unused or obsolete code

Unused imports, variables, functions, classes
TODO/FIXME comments that should have been resolved
Backwards compatibility code for removed features
Orphaned test files for deleted code
Commented-out code blocks
Feature flags that are always on/off

关注点： 未使用或过时的代码

未使用的导入、变量、函数、类
应已解决的TODO/FIXME注释
针对已移除功能的向后兼容代码
对应已删除代码的孤立测试文件
被注释掉的代码块
始终开启/关闭的功能标志

Subagent 3: Abstraction Agent

子Agent 3：抽象Agent

Focus: Over-engineering patterns

Unnecessary abstraction layers (interfaces for single implementations)
Copy-paste drift (similar code that diverged slightly)
Over-configuration (configurable things that never change)
Premature generalization
Factory/Builder patterns for simple object creation
Deep inheritance hierarchies

关注点： 过度工程模式

不必要的抽象层（单一实现对应的接口）
复制粘贴漂移（相似代码出现细微差异）
过度配置（从未变更的可配置项）
过早泛化
用于简单对象创建的Factory/Builder模式
深层继承层级

Subagent 4: Style Agent

子Agent 4：风格Agent

Focus: Verbose or defensive patterns

Verbose comments explaining obvious code
Defensive overkill (null checks on non-nullable values)
Unnecessary type hints (dynamic languages with obvious types)
Overly explicit error messages
Redundant logging
Self-documenting code with documentation

关注点： 冗余或防御性模式

解释明显代码的冗余注释
过度防御（对非空值进行空检查）
不必要的类型提示（类型明显的动态语言）
过于详细的错误信息
冗余日志
带有文档的自解释代码

Step 4: Consolidate Findings

步骤4：整合检测结果

Wait for all subagents to complete, then:

Merge all findings into a single list
Assign unique IDs (1, 2, 3...)
Group by category for display

等待所有子Agent完成后：

将所有检测结果合并为单个列表
分配唯一ID（1、2、3...）
按类别分组展示

Step 5: Write JSON Report

步骤5：生成JSON报告

Create

.beagle

directory if it doesn't exist:

bash

mkdir -p .beagle

Write findings to

.beagle/llm-artifacts-review.json

json

{
  "version": "1.0.0",
  "created_at": "2024-01-15T10:30:00Z",
  "git_head": "abc1234",
  "scope": "changed" | "all",
  "files_scanned": 42,
  "languages": ["Python", "TypeScript", "Go"],
  "findings": [
    {
      "id": 1,
      "category": "tests" | "dead_code" | "abstraction" | "style",
      "type": "dry_violation" | "unused_import" | "over_abstraction" | "verbose_comment" | ...,
      "file": "src/utils/helper.py",
      "line": 42,
      "description": "Repeated setup code in 5 test functions",
      "suggestion": "Extract to a pytest fixture",
      "risk": "Low" | "Medium" | "High",
      "fix_safety": "Safe" | "Needs review",
      "fix_action": "refactor" | "delete" | "simplify" | "extract"
    }
  ],
  "summary": {
    "total": 15,
    "by_category": {
      "tests": 4,
      "dead_code": 5,
      "abstraction": 3,
      "style": 3
    },
    "by_risk": {
      "High": 2,
      "Medium": 8,
      "Low": 5
    },
    "by_fix_safety": {
      "Safe": 10,
      "Needs review": 5
    }
  }
}

如果

.beagle

目录不存在则创建：

bash

mkdir -p .beagle

将检测结果写入

.beagle/llm-artifacts-review.json

：

json

{
  "version": "1.0.0",
  "created_at": "2024-01-15T10:30:00Z",
  "git_head": "abc1234",
  "scope": "changed" | "all",
  "files_scanned": 42,
  "languages": ["Python", "TypeScript", "Go"],
  "findings": [
    {
      "id": 1,
      "category": "tests" | "dead_code" | "abstraction" | "style",
      "type": "dry_violation" | "unused_import" | "over_abstraction" | "verbose_comment" | ...,
      "file": "src/utils/helper.py",
      "line": 42,
      "description": "Repeated setup code in 5 test functions",
      "suggestion": "Extract to a pytest fixture",
      "risk": "Low" | "Medium" | "High",
      "fix_safety": "Safe" | "Needs review",
      "fix_action": "refactor" | "delete" | "simplify" | "extract"
    }
  ],
  "summary": {
    "total": 15,
    "by_category": {
      "tests": 4,
      "dead_code": 5,
      "abstraction": 3,
      "style": 3
    },
    "by_risk": {
      "High": 2,
      "Medium": 8,
      "Low": 5
    },
    "by_fix_safety": {
      "Safe": 10,
      "Needs review": 5
    }
  }
}

Step 6: Display Summary

步骤6：展示摘要

markdown

undefined

markdown

undefined

LLM Artifacts Review

LLM编码不良产物评审

Scope: Changed files from main | Entire codebase Files scanned: 42 Languages: Python, TypeScript, Go

范围： 从main分支变更的文件 | 整个代码库 扫描文件数： 42 涉及语言： Python, TypeScript, Go

Findings by Category

按类别划分的检测结果

Tests (4 issues)

测试（4个问题）

[src/tests/test_api.py:15] DRY violation (Medium, Safe)
- Repeated setup code in 5 test functions
- Suggestion: Extract to a pytest fixture
[src/tests/test_utils.py:42] Wrong mock boundary (High, Needs review)
- Mocking internal implementation details
- Suggestion: Mock at the adapter boundary instead

[src/tests/test_api.py:15] DRY原则违反（中等风险，安全修复）
- 5个测试函数中存在重复的初始化代码
- 建议：提取为pytest fixture
[src/tests/test_utils.py:42] 错误的Mock边界（高风险，需评审）
- Mock了内部实现细节
- 建议：改为在适配器边界进行Mock

Dead Code (5 issues)

死代码（5个问题）

[src/utils/legacy.py:1] Unused module (Low, Safe)
- Module imported nowhere in codebase
- Suggestion: Delete file

...

[src/utils/legacy.py:1] 未使用的模块（低风险，安全修复）
- 该模块未在代码库中任何地方被导入
- 建议：删除文件

...

Abstraction (3 issues)

抽象（3个问题）

...

Style (3 issues)

风格（3个问题）

...

Summary Table

摘要表格

Category	Safe Fixes	Needs Review	Total
Tests	3	1	4
Dead Code	4	1	5
Abstraction	2	1	3
Style	1	2	3
Total	10	5	15

类别	安全修复	需评审	总计
测试	3	1	4
死代码	4	1	5
抽象	2	1	3
风格	1	2	3
总计	10	5	15

Next Steps

后续步骤

Run
```
/beagle-core:review-llm-artifacts --fix
```
to auto-fix Safe issues (coming soon)
Review the JSON report at
```
.beagle/llm-artifacts-review.json
```

undefined

运行
```
/beagle-core:review-llm-artifacts --fix
```
自动修复安全问题（即将推出）
查看
```
.beagle/llm-artifacts-review.json
```
中的JSON报告

undefined

Step 7: Verification

步骤7：验证

Before completing, verify the review executed correctly:

JSON validity: Confirm
```
.beagle/llm-artifacts-review.json
```
exists and is parseable
Subagent success: All 4 subagents completed without errors
Git HEAD captured: The
```
git_head
```
field is non-empty in the report
Staleness check: If a previous report exists, compare stored
```
git_head
```
to current HEAD and warn if different

bash

undefined

完成前，验证评审是否正确执行：

JSON有效性： 确认
```
.beagle/llm-artifacts-review.json
```
存在且可解析
子Agent执行成功： 所有4个子Agent均无错误完成
Git HEAD已捕获： 报告中的
```
git_head
```
字段非空
陈旧性检查： 如果存在之前的报告，比较存储的
```
git_head
```
与当前HEAD，若不同则发出警告

bash

undefined

Verify JSON is valid

验证JSON有效性

python3 -c "import json; json.load(open('.beagle/llm-artifacts-review.json'))" 2>/dev/null && echo "✓ Valid JSON" || echo "✗ Invalid JSON"

Check for staleness (if previous report exists)

检查陈旧性（如果存在之前的报告）

STORED_HEAD=$(jq -r '.git_head' .beagle/llm-artifacts-review.json 2>/dev/null) CURRENT_HEAD=$(git rev-parse --short HEAD) if [ "$STORED_HEAD" != "$CURRENT_HEAD" ]; then echo "⚠️ Report was generated on $STORED_HEAD, current HEAD is $CURRENT_HEAD" fi


If any verification fails, report the error and do not proceed.


如果任何验证失败，报告错误并不继续执行。

Output Format for Each Finding

单个检测结果的输出格式

text

[FILE:LINE] **ISSUE_TYPE** (Risk, Fix Safety)
- Description
- Suggestion: Specific fix recommendation

text

[FILE:LINE] **ISSUE_TYPE** (Risk, Fix Safety)
- Description
- Suggestion: Specific fix recommendation

Rules

规则

Always load the
```
beagle-core:llm-artifacts-detection
```
skill first
Use
```
Task
```
tool for parallel subagents when >= 4 files
Every finding MUST have file:line reference
Categorize risk honestly (don't inflate or deflate)
Mark fix safety as "Safe" only if change is mechanical and reversible
Create
```
.beagle
```
directory if needed
Write JSON report before displaying summary

始终先加载
```
beagle-core:llm-artifacts-detection
```
技能
当文件数≥4时，使用
```
Task
```
工具启动并行子Agent
每个检测结果必须包含file:line引用
如实分类风险（不夸大或缩小）
仅当变更为机械且可逆时，标记修复安全性为"Safe"
必要时创建
```
.beagle
```
目录
展示摘要前先写入JSON报告