ln-501-code-quality-checker

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Code Quality Checker

代码质量检查器

Analyzes Done implementation tasks with quantitative Code Quality Score based on metrics, MCP Ref validation, and issue penalties.

基于指标、MCP Ref验证及问题扣分项，对已完成的实现任务进行分析并生成量化的代码质量分数。

Purpose & Scope

目的与范围

Load Story and Done implementation tasks (exclude test tasks)
Calculate Code Quality Score using metrics and issue penalties
MCP Ref validation: Verify optimality, best practices, and performance via external sources
Check for DRY/KISS/YAGNI violations, architecture boundary breaks, security issues
Produce quantitative verdict with structured issue list; never edits Linear or kanban

加载需求故事（Story）及已完成（Done）的实现任务（排除测试任务）
利用指标和问题扣分项计算代码质量分数
MCP Ref验证：通过外部来源验证方案的最优性、最佳实践符合性及性能表现
检查是否违反DRY/KISS/YAGNI原则、是否突破架构边界、是否存在安全问题
生成带有结构化问题列表的量化结论；绝不修改Linear或看板内容

Code Metrics

代码指标

Metric	Threshold	Penalty
Cyclomatic Complexity	≤10 OK, 11-20 warning, >20 fail	-5 (warning), -10 (fail) per function
Function size	≤50 lines OK, >50 warning	-3 per function
File size	≤500 lines OK, >500 warning	-5 per file
Nesting depth	≤3 OK, >3 warning	-3 per instance
Parameter count	≤4 OK, >4 warning	-2 per function

指标	阈值	扣分项
Cyclomatic Complexity（圈复杂度）	≤10 合格，11-20 警告，>20 不合格	每个函数扣5分（警告）、扣10分（不合格）
函数大小	≤50行合格，>50行警告	每个函数扣3分
文件大小	≤500行合格，>500行警告	每个文件扣5分
嵌套深度	≤3 合格，>3 警告	每处扣3分
参数数量	≤4 合格，>4 警告	每个函数扣2分

Code Quality Score

代码质量分数

Formula:

Code Quality Score = 100 - metric_penalties - issue_penalties

Issue penalties by severity:

Severity	Penalty	Examples
high	-20	Security vulnerability, O(n²)+ algorithm, N+1 query
medium	-10	DRY violation, suboptimal approach, missing config
low	-3	Naming convention, minor code smell

Score interpretation:

Score	Status	Verdict
90-100	Excellent	PASS
70-89	Acceptable	CONCERNS
<70	Below threshold	ISSUES_FOUND

计算公式：

Code Quality Score = 100 - metric_penalties - issue_penalties

按严重程度划分的问题扣分项：

严重程度	扣分项	示例
高	-20	安全漏洞、O(n²)+级算法、N+1查询
中	-10	违反DRY原则、方案非最优、缺少配置
低	-3	命名规范问题、轻微代码异味

分数解读：

分数	状态	结论
90-100	优秀	PASS
70-89	可接受	CONCERNS
<70	低于阈值	ISSUES_FOUND

Issue Prefixes

问题前缀

Prefix	Category	Default Severity	MCP Ref
SEC-	Security (auth, validation, secrets)	high	—
PERF-	Performance (algorithms, configs, bottlenecks)	medium/high	✓ Required
MNT-	Maintainability (DRY, SOLID, complexity)	medium	—
ARCH-	Architecture (layers, boundaries, patterns)	medium	—
BP-	Best Practices (implementation differs from recommended)	medium	✓ Required
OPT-	Optimality (better approach exists for this goal)	medium	✓ Required

PERF- subcategories:

Prefix	Category	Severity
PERF-ALG-	Algorithm complexity (Big O)	high if O(n²)+
PERF-CFG-	Package/library configuration	medium
PERF-PTN-	Architectural pattern performance	high
PERF-DB-	Database queries, indexes	high

前缀	分类	默认严重程度	MCP Ref
SEC-	安全（认证、验证、密钥）	高	—
PERF-	性能（算法、配置、瓶颈）	中/高	✓ 必需
MNT-	可维护性（DRY、SOLID、复杂度）	中	—
ARCH-	架构（分层、边界、模式）	中	—
BP-	最佳实践（实现方式与推荐不符）	中	✓ 必需
OPT-	最优性（存在更适合该目标的方案）	中	✓ 必需

PERF-子分类：

前缀	分类	严重程度
PERF-ALG-	算法复杂度（大O表示法）	若为O(n²)+则为高
PERF-CFG-	包/库配置	中
PERF-PTN-	架构模式性能	高
PERF-DB-	数据库查询、索引	高

When to Use

使用场景

Invoked by ln-500-story-quality-gate Pass 1 (first gate)
All implementation tasks in Story status = Done
Before regression testing (ln-502) and test planning (ln-510)

由ln-500-story-quality-gate触发 第一阶段（第一道关卡）
需求故事状态为Done的所有实现任务
在回归测试（ln-502）和测试计划（ln-510）之前执行

Workflow (concise)

工作流程（精简版）

Load Story (full) and Done implementation tasks (full descriptions) via Linear; skip tasks with label "tests".
Collect affected files from tasks (Affected Components/Existing Code Impact) and recent commits/diffs if noted.
Calculate code metrics:
- Cyclomatic Complexity per function (target ≤10)
- Function size (target ≤50 lines)
- File size (target ≤500 lines)
- Nesting depth (target ≤3)
- Parameter count (target ≤4)

3.5) MCP Ref Validation (MANDATORY for code changes):

Level 1 — OPTIMALITY (OPT-):

Extract goal from task (e.g., "user authentication", "caching", "API rate limiting")

Research alternatives:

ref_search_documentation("{goal} approaches comparison {tech_stack} 2026")

Compare chosen approach vs alternatives for project context
Flag suboptimal choices as OPT- issues

Level 2 — BEST PRACTICES (BP-):

Research:

ref_search_documentation("{chosen_approach} best practices {tech_stack} 2026")

For libraries:

query-docs(library_id, "best practices implementation patterns")

Flag deviations from recommended patterns as BP- issues

Level 3 — PERFORMANCE (PERF-):

PERF-ALG: Analyze algorithm complexity (detect O(n²)+, research optimal via MCP Ref)
PERF-CFG: Check library configs (connection pooling, batch sizes, timeouts) via
```
query-docs
```

PERF-PTN: Research pattern pitfalls:

ref_search_documentation("{pattern} performance bottlenecks")

PERF-DB: Check for N+1, missing indexes via

query-docs(orm_library_id, "query optimization")

Triggers for MCP Ref validation:

New dependency added (package.json/requirements.txt changed)
New pattern/library used
API/database changes
Loops/recursion in critical paths
ORM queries added

Analyze code for static issues (assign prefixes):
- SEC-: hardcoded creds, unvalidated input, SQL injection, race conditions
- MNT-: DRY violations, dead code, complex conditionals, poor naming
- ARCH-: layer violations, circular dependencies, guide non-compliance
Calculate Code Quality Score:
- Start with 100
- Subtract metric penalties (see Code Metrics table)
- Subtract issue penalties (see Issue penalties table)
Output verdict with score and structured issues. Add Linear comment with findings.

通过Linear加载完整需求故事及已完成的实现任务（完整描述）；跳过带有"tests"标签的任务。
从任务中收集受影响文件（受影响组件/现有代码影响），若有记录则同时收集近期提交/差异。
计算代码指标：
- 每个函数的Cyclomatic Complexity（目标≤10）
- 函数大小（目标≤50行）
- 文件大小（目标≤500行）
- 嵌套深度（目标≤3）
- 参数数量（目标≤4）

3.5) MCP Ref验证（代码变更时强制要求）：

第一级——最优性（OPT-）：

从任务中提取目标（例如："用户认证"、"缓存"、"API速率限制"）

研究替代方案：

ref_search_documentation("{goal} approaches comparison {tech_stack} 2026")

对比所选方案与替代方案在项目语境下的适用性
将非最优选择标记为OPT-类问题

第二级——最佳实践（BP-）：

研究：

ref_search_documentation("{chosen_approach} best practices {tech_stack} 2026")

针对库：

query-docs(library_id, "best practices implementation patterns")

将偏离推荐模式的实现标记为BP-类问题

第三级——性能（PERF-）：

PERF-ALG： 分析算法复杂度（检测O(n²)+级，通过MCP Ref研究最优方案）
PERF-CFG： 通过
```
query-docs
```
检查库配置（连接池、批量大小、超时时间）

PERF-PTN： 研究模式缺陷：

ref_search_documentation("{pattern} performance bottlenecks")

PERF-DB： 通过
```
query-docs(orm_library_id, "query optimization")
```
检查是否存在N+1查询、缺少索引等问题

MCP Ref验证触发条件：

添加了新依赖（package.json/requirements.txt发生变更）
使用了新模式/库
API/数据库发生变更
关键路径中存在循环/递归
添加了ORM查询

分析代码中的静态问题（分配前缀）：
- SEC-：硬编码凭证、未验证输入、SQL注入、竞态条件
- MNT-：违反DRY原则、死代码、复杂条件判断、命名不佳
- ARCH-：分层违规、循环依赖、不符合指南要求
计算代码质量分数：
- 初始分数为100
- 减去指标扣分项（见代码指标表格）
- 减去问题扣分项（见问题扣分项表格）
输出包含分数和结构化问题的结论。在Linear中添加包含检查结果的评论。

Critical Rules

关键规则

Read guides mentioned in Story/Tasks before judging compliance.
MCP Ref validation: For ANY architectural change, MUST verify via ref_search_documentation before judging.
Context7 for libraries: When reviewing library usage, query-docs to verify correct patterns.
Language preservation in comments (EN/RU).
Do not create tasks or change statuses; caller decides next actions.

在判断合规性之前，阅读需求故事/任务中提及的指南。
MCP Ref验证： 对于任何架构变更，必须先通过ref_search_documentation验证后再进行判断。
库的Context7： 审查库的使用方式时，通过query-docs验证模式是否正确。
注释保留原语言（英文/俄文）。
不得创建任务或修改状态；由调用方决定后续操作。

Definition of Done

完成定义

Story and Done implementation tasks loaded (test tasks excluded).
Code metrics calculated (Cyclomatic Complexity, function/file sizes).
MCP Ref validation completed:
- OPT-: Optimality checked (is chosen approach the best for the goal?)
- BP-: Best practices verified (correct implementation of chosen approach?)
- PERF-: Performance analyzed (algorithms, configs, patterns, DB)
Issues identified with prefixes and severity, sources from MCP Ref/Context7.
Code Quality Score calculated.

Output format:

yaml

verdict: PASS | CONCERNS | ISSUES_FOUND
code_quality_score: {0-100}
metrics:
  avg_cyclomatic_complexity: {value}
  functions_over_50_lines: {count}
  files_over_500_lines: {count}
issues:
  # OPTIMALITY
  - id: "OPT-001"
    severity: medium
    file: "src/auth/index.ts"
    goal: "User session management"
    finding: "Suboptimal approach for session management"
    chosen: "Custom JWT with localStorage"
    recommended: "httpOnly cookies + refresh token rotation"
    reason: "httpOnly cookies prevent XSS token theft"
    source: "ref://owasp-session-management"

  # BEST PRACTICES
  - id: "BP-001"
    severity: medium
    file: "src/api/routes.ts"
    finding: "POST for idempotent operation"
    best_practice: "Use PUT for idempotent updates (RFC 7231)"
    source: "ref://api-design-guide#idempotency"

  # PERFORMANCE - Algorithm
  - id: "PERF-ALG-001"
    severity: high
    file: "src/utils/search.ts:42"
    finding: "Nested loops cause O(n²) complexity"
    current: "O(n²) - nested filter().find()"
    optimal: "O(n) - use Map/Set for lookup"
    source: "ref://javascript-performance#data-structures"

  # PERFORMANCE - Config
  - id: "PERF-CFG-001"
    severity: medium
    file: "src/db/connection.ts"
    finding: "Missing connection pool config"
    current_config: "default (pool: undefined)"
    recommended: "pool: { min: 2, max: 10 }"
    source: "context7://pg#connection-pooling"

  # PERFORMANCE - Database
  - id: "PERF-DB-001"
    severity: high
    file: "src/repositories/user.ts:89"
    finding: "N+1 query pattern detected"
    issue: "users.map(u => u.posts) triggers N queries"
    solution: "Use eager loading: include: { posts: true }"
    source: "context7://prisma#eager-loading"

  # MAINTAINABILITY
  - id: "MNT-001"
    severity: medium
    file: "src/service.ts:42"
    finding: "DRY violation: duplicate validation logic"
    suggested_action: "Extract to shared validator"

Linear comment posted with findings.

已加载需求故事及已完成的实现任务（排除测试任务）。
已计算代码指标（Cyclomatic Complexity、函数/文件大小）。
已完成MCP Ref验证：
- OPT-：已检查最优性（所选方案是否为实现目标的最佳选择？）
- BP-：已验证最佳实践（所选方案的实现是否正确？）
- PERF-：已分析性能（算法、配置、模式、数据库）
已识别带有前缀和严重程度的问题，来源为MCP Ref/Context7。
已计算代码质量分数。

输出格式：

yaml

verdict: PASS | CONCERNS | ISSUES_FOUND
code_quality_score: {0-100}
metrics:
  avg_cyclomatic_complexity: {value}
  functions_over_50_lines: {count}
  files_over_500_lines: {count}
issues:
  # OPTIMALITY
  - id: "OPT-001"
    severity: medium
    file: "src/auth/index.ts"
    goal: "User session management"
    finding: "Suboptimal approach for session management"
    chosen: "Custom JWT with localStorage"
    recommended: "httpOnly cookies + refresh token rotation"
    reason: "httpOnly cookies prevent XSS token theft"
    source: "ref://owasp-session-management"

  # BEST PRACTICES
  - id: "BP-001"
    severity: medium
    file: "src/api/routes.ts"
    finding: "POST for idempotent operation"
    best_practice: "Use PUT for idempotent updates (RFC 7231)"
    source: "ref://api-design-guide#idempotency"

  # PERFORMANCE - Algorithm
  - id: "PERF-ALG-001"
    severity: high
    file: "src/utils/search.ts:42"
    finding: "Nested loops cause O(n²) complexity"
    current: "O(n²) - nested filter().find()"
    optimal: "O(n) - use Map/Set for lookup"
    source: "ref://javascript-performance#data-structures"

  # PERFORMANCE - Config
  - id: "PERF-CFG-001"
    severity: medium
    file: "src/db/connection.ts"
    finding: "Missing connection pool config"
    current_config: "default (pool: undefined)"
    recommended: "pool: { min: 2, max: 10 }"
    source: "context7://pg#connection-pooling"

  # PERFORMANCE - Database
  - id: "PERF-DB-001"
    severity: high
    file: "src/repositories/user.ts:89"
    finding: "N+1 query pattern detected"
    issue: "users.map(u => u.posts) triggers N queries"
    solution: "Use eager loading: include: { posts: true }"
    source: "context7://prisma#eager-loading"

  # MAINTAINABILITY
  - id: "MNT-001"
    severity: medium
    file: "src/service.ts:42"
    finding: "DRY violation: duplicate validation logic"
    suggested_action: "Extract to shared validator"

已在Linear中发布包含检查结果的评论。

Reference Files

参考文件

Code metrics:
```
references/code_metrics.md
```
(thresholds and penalties)
Guides:
```
docs/guides/
```

Templates for context:

shared/templates/task_template_implementation.md

Version: 5.0.0 (Added 3-level MCP Ref validation: Optimality, Best Practices, Performance with PERF-ALG/CFG/PTN/DB subcategories) Last Updated: 2026-01-29

代码指标：
```
references/code_metrics.md
```
（阈值和扣分项）
指南：
```
docs/guides/
```

语境模板：

shared/templates/task_template_implementation.md

版本： 5.0.0（新增三级MCP Ref验证：最优性、最佳实践、性能，包含PERF-ALG/CFG/PTN/DB子分类） 最后更新： 2026-01-29