Back to Details

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

代码指标

MetricThresholdPenalty
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:
SeverityPenaltyExamples
high-20Security vulnerability, O(n²)+ algorithm, N+1 query
medium-10DRY violation, suboptimal approach, missing config
low-3Naming convention, minor code smell
Score interpretation:
ScoreStatusVerdict
90-100ExcellentPASS
70-89AcceptableCONCERNS
<70Below thresholdISSUES_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

问题前缀

PrefixCategoryDefault SeverityMCP 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:
PrefixCategorySeverity
PERF-ALG-Algorithm complexity (Big O)high if O(n²)+
PERF-CFG-Package/library configurationmedium
PERF-PTN-Architectural pattern performancehigh
PERF-DB-Database queries, indexeshigh
前缀分类默认严重程度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)

工作流程（精简版）

  1. Load Story (full) and Done implementation tasks (full descriptions) via Linear; skip tasks with label "tests".
  2. Collect affected files from tasks (Affected Components/Existing Code Impact) and recent commits/diffs if noted.
  3. 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
  1. 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
  2. Calculate Code Quality Score:
    • Start with 100
    • Subtract metric penalties (see Code Metrics table)
    • Subtract issue penalties (see Issue penalties table)
  3. Output verdict with score and structured issues. Add Linear comment with findings.
  1. 通过Linear加载完整需求故事及已完成的实现任务（完整描述）；跳过带有"tests"标签的任务。
  2. 从任务中收集受影响文件（受影响组件/现有代码影响），若有记录则同时收集近期提交/差异。
  3. 计算代码指标：
    • 每个函数的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查询
  1. 分析代码中的静态问题（分配前缀）：
    • SEC-：硬编码凭证、未验证输入、SQL注入、竞态条件
    • MNT-：违反DRY原则、死代码、复杂条件判断、命名不佳
    • ARCH-：分层违规、循环依赖、不符合指南要求
  2. 计算代码质量分数：
    • 初始分数为100
    • 减去指标扣分项（见代码指标表格）
    • 减去问题扣分项（见问题扣分项表格）
  3. 输出包含分数和结构化问题的结论。在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