ln-641-pattern-fitness-auditor

路径： 文件路径（references/、../ln-*）均相对于此技能目录。

模式适用性审计员

类型： L3 Worker

L3 Worker，用于根据最佳实践和项目需求分析单个架构模式。

目的与范围

• 每次调用分析一个模式（接收模式名称、位置和最佳实践）
• 在代码库中查找所有实现（Glob/Grep）
• 验证实现是否存在且可正常运行
• 计算 4 项分数：合规性、完整性、质量、实现情况
• 识别差距和问题，并估算严重程度与工作量
• 返回结构化分析结果
• 发出 KEEP_PATTERN、SIMPLIFY_PATTERN、COMPLETE_PATTERN 或 REPLACE_PATTERN

范围之外：

• 圈复杂度阈值（>10、>20）
• 方法/类长度阈值（>50、>100、>500 行）
• 质量分侧重于模式特定质量（模式内部的 SOLID、模式级代码异味），而非通用代码指标

输入

- pattern: string          # Pattern name (e.g., "Job Processing")
- locations: string[]      # Known file paths/directories
- bestPractices: object    # Best practices from MCP Ref/Context7/WebSearch
- output_dir: string       # e.g., ".hex-skills/runtime-artifacts/runs/{run_id}/audit-report"

注意： 如果托管运行提供了模式证据，请使用这些证据，而不是从头重新发现同一模式。

工作流

必须读取： 加载 references/mcp_tool_preferences.md。

检测策略：采用两层检测（候选扫描，然后上下文验证）；仅在验证方法不明确时加载 references/two_layer_detection.md。 工具策略：你可能会作为独立子 Agent 运行，宿主的 AGENTS.md 不在适用范围内，因此读取、搜索和编辑文件时默认优先使用 hex-line MCP。仅在 MCP 行为不明确时加载 references/mcp_integration_patterns.md。

当实现发现能显著提高置信度时，优先使用 hex-graph。本地代码读取时，若 hex-line 可用则优先使用。如果 MCP 不可用、不受支持或未建立索引，请继续使用内置的 Read/Grep/Glob/Bash，并在报告中说明回退情况。

阶段 1：查找实现

必须读取： 加载 references/pattern_library.md —— 使用“模式检测（Grep）”表格中各模式对应的检测关键词。

IF pattern.source == "adaptive":
  # Pattern evidence was already provided by the caller
  files = pattern.evidence.files
  SKIP detection keyword search (already done in Phase 1b)
ELSE:
  # Baseline pattern -- use library detection keywords
  files = Glob(locations)
  additional = Grep("{pattern_keywords}", "**/*.{ts,js,py,rb,cs,java}")
  files = deduplicate(files + additional)

阶段 2：读取并分析代码

FOR EACH file IN files (limit: 10 key files):
  Read(file)
  Extract: components, patterns, error handling, logging, tests

阶段 3：计算 4 项分数

必须读取： 加载 references/scoring_rules.md —— 按照每项标准的“检测”列执行。

分数	scoring_rules.md 中的来源	最高分
合规性	“合规性分数”部分——行业标准、命名、惯例、反模式	100
完整性	“完整性分数”部分——必需组件表（按模式）、错误处理、测试	100
质量	“质量分数”部分——方法长度、复杂度、代码异味、SOLID	100
实现情况	“实现分数”部分——是否可编译、生产环境使用、集成、监控	100

每项标准的评分流程：

1. 运行 scoring_rules.md 中的检测 Grep/Glob
2. 如果找到匹配项 -> 按每项标准加分
3. 如果检测到反模式/代码异味 -> 按扣分表减分
4. 记录证据：为每项分数说明提供文件路径和行号

阶段 4：识别问题和差距

FOR EACH bestPractice NOT implemented:
  issues.append({
    severity: "HIGH" | "MEDIUM" | "LOW",
    category: "compliance" | "completeness" | "quality" | "implementation",
    issue: description,
    suggestion: how to fix,
    effort: "S" | "M" | "L"
  })

# Layer 2 context check (MANDATORY):
# Deviation documented in code comment or ADR? -> downgrade to LOW
# Pattern intentionally simplified for project scale? -> skip


gaps = {
  missingComponents: required components not found in code,
  inconsistencies: conflicting or incomplete implementations
}

阶段 5：计算分数

必须读取： 加载 references/audit_worker_core_contract.md 和 references/audit_scoring.md。

诊断子分数（每项 0-100）单独计算，并仅为诊断用途报告在 AUDIT-META 中：

• 合规性、完整性、质量、实现情况

阶段 6：编写报告

必须读取： 加载 references/templates/audit_worker_report_template.md。

根据 references/audit_summary_contract.md 编写 JSON 摘要。在托管模式下，调用方会同时传入 runId 和 summaryArtifactPath；在独立模式下，Worker 会按照共享契约生成自己的运行级工件路径。

# Build pattern name slug: "Job Processing" -> "job-processing"
slug = pattern.name.lower().replace(" ", "-")

# Build markdown report in memory with:
# - AUDIT-META (extended: score [penalty-based] + diagnostic score_compliance/completeness/quality/implementation)
# - Checks table (compliance_check, completeness_check, quality_check, implementation_check)
# - Findings table (issues sorted by severity)
# - DATA-EXTENDED: {pattern, codeReferences, gaps, recommendations}

Write to {output_dir}/ln-641--{slug}.md (atomic single Write call)

阶段 7：返回摘要

Report written: .hex-skills/runtime-artifacts/runs/{run_id}/audit-report/ln-641--job-processing.md
Score: 7.9/10 (C:72 K:85 Q:68 I:90) | Issues: 3 (H:1 M:2 L:0)

关键规则

应用已加载的 references/audit_worker_core_contract.md。

• 仅分析一种模式： 只分析输入中提供的模式
• 先阅读，再评分： 未阅读实际代码时，绝不评分
• 基于检测结果评分： 使用 scoring_rules.md 中的 Grep/Glob 模式，不要凭假设判断
• 工作量估算： 每个问题都必须提供 S/M/L 估算
• 代码引用： 所有发现都必须包含文件路径
• 独特视角： 只审核一种模式在架构上的适用性。不要审核通用代码质量、依赖拓扑、软件包健康状况或运行时操作。
• 必须采取行动： 每项发现都必须使用 KEEP_PATTERN、SIMPLIFY_PATTERN、COMPLETE_PATTERN 或 REPLACE_PATTERN

完成定义

应用已加载的 references/audit_worker_core_contract.md。

• 使用 pattern_library.md 中的关键词或自适应证据，通过 Glob/Grep 找出所有实现
• 阅读并分析关键文件
• 使用 scoring_rules.md 中的 Detection 模式计算 4 项评分
• 找出问题，并标明严重程度、类别、建议和工作量
• 记录缺口（缺失组件、不一致之处）
• 提供建议
• 将报告写入 {output_dir}/ln-641--{slug}.md（通过一次 Write 原子写入）
• 按照契约撰写摘要

参考文件

• 评分规则：references/scoring_rules.md
• 模式库：references/pattern_library.md

---

版本： 2.0.0 最后更新： 2026-02-08