ln-623-code-principles-auditor by levnikolaevich/claude-code-skills
npx skills add https://github.com/levnikolaevich/claude-code-skills --skill ln-623-code-principles-auditor路径说明: 文件路径(
shared/、references/、../ln-*)是相对于技能仓库根目录的。如果在当前工作目录(CWD)下未找到,请定位此 SKILL.md 文件所在的目录,然后向上返回一级以找到仓库根目录。如果缺少shared/目录,请通过 WebFetch 从https://raw.githubusercontent.com/levnikolaevich/claude-code-skills/master/skills/{path}获取文件。
专门审计代码原则(DRY、KISS、YAGNI)和设计模式的工作器。
必读: 加载 shared/references/audit_worker_core_contract.md。
广告位招租
在这里展示您的产品或服务
触达数万 AI 开发者,精准高效
接收包含以下内容的 contextStore:tech_stack、best_practices、principles、codebase_root、output_dir。
领域感知: 支持 domain_mode + current_domain(参见 audit_output_schema.md#domain-aware-worker-output)。
必读: 加载 shared/references/two_layer_detection.md 以了解检测方法。
scan_path(如果指定则为领域感知),提取 output_dirreferences/detection_patterns.md 以获取特定于语言的 Grep/Glob 模式tech_stack 匹配的模式scan_path(而非 codebase_root)detection_patterns.md 中的分步检测说明detection_patterns.md#exclusions 中的排除规则references/refactoring_decision_tree.md 以选择模式domain: domain_name(如果启用了领域感知)pattern_signature 以供 ln-620 进行跨领域匹配shared/templates/audit_worker_report_template.md 在内存中构建完整的 Markdown 报告,通过单次 Write 调用写入 {output_dir}/623-principles-{domain}.md(或全局模式下的 623-principles.md)。包含 <!-- FINDINGS-EXTENDED --> JSON 块,其中包含用于跨领域 DRY 分析的 pattern_signature 字段必读: shared/references/two_layer_detection.md
所有发现结果都需要第 2 层上下文分析。没有第 2 层分析的第 1 层发现 = 无效发现。在报告之前,请自问:"此违规是设计上的有意为之还是合理的?"
| 发现类型 | 第 2 层降级示例 |
|---|---|
| DRY | 具有不同生命周期/所有权的模块 → 跳过。为解耦而有意进行的重复 → 跳过 |
| KISS | 框架要求的抽象(例如 Spring 中的依赖注入)→ 降级。当前单一实现但为测试而保留的接口 → 跳过 |
| YAGNI | 用于 A/B 测试的功能标志 → 跳过。运维团队使用的配置选项 → 跳过 |
| 错误处理 | 50 行脚本中缺少集中式处理器 → 降级为 LOW |
| 依赖注入 | 可通过参数/闭包替换的依赖项 → 跳过 ARCH-DI |
必读: 加载 references/detection_patterns.md 以获取每种类型的检测步骤。
| 类型 | 内容 | 严重性 | 例外情况(跳过/降级) | 默认建议 | 工作量 |
|---|---|---|---|---|---|
| 1.1 相同代码 | 多个文件中相同的函数/常量/代码块(>10 行) | HIGH:业务关键(认证、支付)。MEDIUM:工具函数。LOW:简单常量 <5 次 | 不同生命周期/所有权的模块 → 跳过。有意解耦 → 跳过 | 提取函数 → 根据重复范围决定位置 | M |
| 1.2 重复验证 | 跨文件的相同验证模式(邮箱、密码、电话、URL) | HIGH:认证/支付。MEDIUM:用户输入 3+ 次。LOW:格式检查 <3 次 | 不同的安全上下文(认证 vs 公开)→ 跳过 | 提取到共享验证器模块 | M |
| 1.3 重复错误消息 | 硬编码的错误字符串而非集中式目录 | MEDIUM:关键消息硬编码或无错误目录。LOW:<3 处 | 需要根据上下文调整措辞的用户界面字符串 → 降级 | 创建常量/错误消息文件 | M |
| 1.4 相似模式 | 具有相同调用顺序/控制流但名称/实体不同的函数 | MEDIUM:关键路径中的业务逻辑。LOW:工具函数 <3 次 | 预期会分叉演化的模块 → 跳过 | 提取通用逻辑(参见决策树中的模式) | M |
| 1.5 重复的 SQL/ORM | 不同服务中的相同查询 | HIGH:支付/认证查询。MEDIUM:常见 3+ 次。LOW:简单 <3 次 | 不同的有界上下文;共享数据库比重复更糟糕 → 跳过 | 提取到 Repository 层 | M |
| 1.6 复制粘贴的测试 | 跨测试文件的相同设置/拆卸/夹具 | MEDIUM:5+ 个文件中的设置。LOW:<5 个文件 | 为清晰/独立而有意隔离的测试 → 降级 | 提取到测试辅助函数 | M |
| 1.7 重复的 API 响应 | 没有 DTO 的相同响应对象结构 | MEDIUM:在 5+ 个端点中。LOW:<5 个端点 | 具有不同版本生命周期的响应 → 跳过 | 创建 DTO/响应类 | M |
| 1.8 重复的中间件链 | 多个路由上相同的中间件/装饰器栈 | MEDIUM:5+ 个路由上的相同链。LOW:<5 个路由 | 具有不同认证/限流要求的路由 → 跳过 | 创建命名的中间件组,在路由器级别应用 | M |
| 1.9 重复的类型定义 | 字段 80%+ 相同的接口/结构体/类型 | MEDIUM:在 5+ 个文件中。LOW:2-4 个文件 | 具有不同所有权/演化路径的类型 → 跳过 | 创建共享基础类型,在需要时扩展 | M |
| 1.10 重复的映射逻辑 | 多个位置中相同的实体→DTO / DTO→实体转换 | MEDIUM:在 3+ 个位置。LOW:2 个位置 | 具有不同验证/丰富规则的映射 → 跳过 | 创建专用的 Mapper 类/函数 | M |
建议选择: 使用 references/refactoring_decision_tree.md 根据重复位置(第 1 层)和逻辑类型(第 2 层)选择正确的重构模式。
| 违规 | 检测方法 | 严重性 | 例外情况(跳过/降级) | 建议 | 工作量 |
|---|---|---|---|---|---|
| 只有 1 个实现的抽象类 | Grep abstract class → 统计子类数量 | HIGH:妨碍理解核心逻辑 | 用于依赖注入/测试的接口 → 跳过。框架要求(Spring、ASP.NET)→ 跳过 | 移除抽象,内联 | L |
| 少于 3 种类型的工厂 | Grep 工厂模式 → 统计分支数量 | MEDIUM:不必要的模式 | 用于依赖注入/测试交换的工厂 → 降级 | 替换为直接构造 | M |
| 深度继承 >3 层 | 跟踪继承链 | HIGH:脆弱的层次结构 | 框架强制的层次结构(UI 组件、ORM 模型)→ 降级 | 使用组合扁平化 | L |
| 过多的泛型约束 | Grep <T extends ... & ...> | LOW:可接受的权衡 | 公共 API 边界的类型安全 → 跳过 | 简化约束 | M |
| 仅包装类 | 读取:所有方法都委托给内部对象 | MEDIUM:不必要的间接层 | 用于外部 API 隔离的适配器模式 → 跳过 | 移除包装器,直接使用内部对象 | M |
| 违规 | 检测方法 | 严重性 | 例外情况(跳过/降级) | 建议 | 工作量 |
|---|---|---|---|---|---|
| 死亡功能标志(始终为真/假) | Grep 标志 → 验证从未切换 | LOW:需要清理 | A/B 测试标志 → 跳过。运维控制的开关 → 跳过 | 移除标志,保留活动代码路径 | M |
| 从未被重写的抽象方法 | Grep abstract → 搜索实现 | MEDIUM:未使用的可扩展性 | 公共库中的插件/扩展点 → 降级 | 移除抽象,使其具体化 | M |
| 未使用的配置选项 | Grep 配置键 → 0 个引用 | LOW:死亡配置 | 环境特定配置(预发/生产)→ 在标记前验证 | 移除选项 | S |
| 只有 1 个实现的接口 | Grep interface → 统计实现者数量 | MEDIUM:过早的抽象 | 用于依赖注入/测试模拟的接口 → 跳过 | 移除接口,直接使用类 | M |
| 过早的泛型(仅用于 1 种类型) | Grep 泛型使用 → 统计类型参数数量 | LOW:过度设计 | 为消费者设计的公共库 API → 跳过 | 将泛型替换为具体类型 | S |
| 严重性 | 标准 |
|---|---|
| CRITICAL | 支付/认证操作没有错误处理 |
| HIGH | 面向用户的操作没有错误处理 |
| MEDIUM | 内部操作没有错误处理 |
工作量: M
ErrorHandler、errorHandler、error-handler.*process.on("uncaughtException") 的使用| 严重性 | 标准 |
|---|---|
| HIGH | 没有集中式错误处理器 |
| HIGH | 使用 uncaughtException 监听器(Express 反模式) |
| MEDIUM | 中间件直接处理错误(未委托) |
| MEDIUM | 异步路由没有正确的错误处理 |
| LOW | 生产环境中暴露堆栈跟踪 |
目标结果: 所有错误都附带上下文被记录,并返回清晰的面向用户的消息。没有错误被静默吞没。堆栈跟踪永远不会泄露到生产响应中。实现选择(ErrorHandler 类、中间件、装饰器)取决于项目技术栈和规模。
工作量: M-L
inversify、awilix、tsyringe(Node)、dependency_injector(Python)、Spring @Autowired(Java)、ASP.NET IServiceCollection(C#)new SomeService()(直接实例化)bootstrap.ts、init.py、Startup.cs、app.module.ts| 严重性 | 标准 |
|---|---|
| MEDIUM | 没有依赖注入容器(紧耦合) |
| MEDIUM | 业务逻辑中的直接实例化 |
| LOW | 混合使用依赖注入和直接导入 |
目标结果: 依赖项可替换以进行测试,而无需修改生产代码。服务实例化与业务逻辑之间没有紧耦合。实现选择(依赖注入容器、工厂函数、参数注入、闭包)取决于项目规模和堆栈。
工作量: L
docs/architecture.md、docs/best-practices.md、ARCHITECTURE.md、CONTRIBUTING.md| 严重性 | 标准 |
|---|---|
| LOW | 没有架构/最佳实践指南 |
建议: 创建包含分层规则、错误处理模式、依赖注入使用、编码规范的 docs/architecture.md。
工作量: S
必读: 加载 shared/references/audit_worker_core_contract.md 和 shared/references/audit_scoring.md。
必读: 加载 shared/references/audit_worker_core_contract.md 和 shared/templates/audit_worker_report_template.md。
将报告写入 {output_dir}/623-principles-{domain}.md(或全局模式下的 623-principles.md),并设置 category: "Architecture & Design"。
FINDINGS-EXTENDED 块(此工作器必需): 在发现结果表格之后,包含一个 <!-- FINDINGS-EXTENDED --> JSON 块,其中包含所有带有 pattern_signature 的 DRY 发现结果,以供 ln-620 协调器进行跨领域匹配。遵循 shared/templates/audit_worker_report_template.md。
pattern_id: DRY 类型标识符(dry_1.1 到 dry_1.10)。非 DRY 发现结果省略。
pattern_signature: 检测到的模式的规范化键(例如 validation_email、sql_users_findByEmail、middleware_auth_validate_ratelimit)。多个领域中相同的签名会触发跨领域 DRY 发现。格式在 references/detection_patterns.md 中定义。
返回给协调器的摘要:
Report written: docs/project/.audit/ln-620/{YYYY-MM-DD}/623-principles-users.md
Score: X.X/10 | Issues: N (C:N H:N M:N L:N)
必读: 加载 shared/references/audit_worker_core_contract.md。
domain_mode="domain-aware",则仅扫描 scan_pathdomain 字段pattern_id + pattern_signatureprinciples.md 来定义可接受的内容detection_patterns.md#exclusions)必读: 加载 shared/references/audit_worker_core_contract.md。
references/detection_patterns.md 加载检测模式references/refactoring_decision_tree.md 选择建议shared/references/audit_scoring.md 计算得分{output_dir}/623-principles-{domain}.md,并包含 FINDINGS-EXTENDED 块(原子性的单次 Write 调用)版本: 5.0.0 最后更新: 2026-02-08
每周安装数
164
仓库
GitHub 星标数
253
首次出现
2026年2月2日
安全审计
安装于
claude-code152
cursor151
codex148
gemini-cli148
opencode148
github-copilot145
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. Ifshared/is missing, fetch files via WebFetch fromhttps://raw.githubusercontent.com/levnikolaevich/claude-code-skills/master/skills/{path}.
Specialized worker auditing code principles (DRY, KISS, YAGNI) and design patterns.
MANDATORY READ: Load shared/references/audit_worker_core_contract.md.
Receives contextStore with: tech_stack, best_practices, principles, codebase_root, output_dir.
Domain-aware: Supports domain_mode + current_domain (see audit_output_schema.md#domain-aware-worker-output).
MANDATORY READ: Load shared/references/two_layer_detection.md for detection methodology.
scan_path (domain-aware if specified), extract output_dirreferences/detection_patterns.md for language-specific Grep/Glob patternstech_stackscan_path (not codebase_root)detection_patterns.mddetection_patterns.md#exclusionsMANDATORY READ: shared/references/two_layer_detection.md
All findings require Layer 2 context analysis. Layer 1 finding without Layer 2 = NOT a valid finding. Before reporting, ask: "Is this violation intentional or justified by design?"
| Finding Type | Layer 2 Downgrade Examples |
|---|---|
| DRY | Modules with different lifecycle/ownership → skip. Intentional duplication for decoupling → skip |
| KISS | Framework-required abstraction (e.g., DI in Spring) → downgrade. Single implementation today but interface for testing → skip |
| YAGNI | Feature flag used in A/B testing → skip. Config option used by ops team → skip |
| Error Handling | Centralized handler absent in 50-line script → downgrade to LOW |
| DI | Dependencies replaceable via params/closures → skip ARCH-DI |
MANDATORY READ: Load references/detection_patterns.md for detection steps per type.
| Type | What | Severity | Exception (skip/downgrade) | Default Recommendation | Effort |
|---|---|---|---|---|---|
| 1.1 Identical Code | Same functions/constants/blocks (>10 lines) in multiple files | HIGH: business-critical (auth, payment). MEDIUM: utilities. LOW: simple constants <5x | Different lifecycle/ownership modules → skip. Intentional decoupling → skip | Extract function → decide location by duplication scope | M |
| 1.2 Duplicated Validation | Same validation patterns (email, password, phone, URL) across files | HIGH: auth/payment. MEDIUM: user input 3+x. LOW: format checks <3x | Different security contexts (auth vs public) → skip | Extract to shared validators module | M |
| 1.3 Repeated Error Messages | Hardcoded error strings instead of centralized catalog | MEDIUM: critical messages hardcoded or no error catalog. LOW: <3 places | User-facing strings requiring per-context wording → downgrade | Create constants/error-messages file |
Recommendation selection: Use references/refactoring_decision_tree.md to choose the right refactoring pattern based on duplication location (Level 1) and logic type (Level 2).
| Violation | Detection | Severity | Exception (skip/downgrade) | Recommendation | Effort |
|---|---|---|---|---|---|
| Abstract class with 1 implementation | Grep abstract class → count subclasses | HIGH: prevents understanding core logic | Interface for DI/testing → skip. Framework-required (Spring, ASP.NET) → skip | Remove abstraction, inline | L |
| Factory for <3 types | Grep factory patterns → count branches | MEDIUM: unnecessary pattern | Factory used for DI/testing swap → downgrade | Replace with direct construction | M |
| Deep inheritance >3 levels | Trace extends chain | HIGH: fragile hierarchy | Framework-mandated hierarchy (UI widgets, ORM models) → downgrade | Flatten with composition | L |
| Excessive generic constraints |
| Violation | Detection | Severity | Exception (skip/downgrade) | Recommendation | Effort |
|---|---|---|---|---|---|
| Dead feature flags (always true/false) | Grep flags → verify never toggled | LOW: cleanup needed | A/B testing flags → skip. Ops-controlled toggles → skip | Remove flag, keep active code path | M |
| Abstract methods never overridden | Grep abstract → search implementations | MEDIUM: unused extensibility | Plugin/extension point in public library → downgrade | Remove abstract, make concrete | M |
| Unused config options | Grep config key → 0 references | LOW: dead config | Env-specific configs (staging/prod) → verify before flagging | Remove option | S |
| Interface with 1 implementation | Grep interface → count implementors | MEDIUM: premature abstraction | Interface for DI/testing mock → skip |
| Severity | Criteria |
|---|---|
| CRITICAL | Payment/auth without error handling |
| HIGH | User-facing operations without error handling |
| MEDIUM | Internal operations without error handling |
Effort: M
ErrorHandler, errorHandler, error-handler.*process.on("uncaughtException") usage| Severity | Criteria |
|---|---|
| HIGH | No centralized error handler |
| HIGH | Using uncaughtException listener (Express anti-pattern) |
| MEDIUM | Middleware handles errors directly (no delegation) |
| MEDIUM | Async routes without proper error handling |
| LOW | Stack traces exposed in production |
Outcome Goal: All errors are logged with context and return clear user-facing messages. No error is silently swallowed. Stack traces never leak to production responses. Implementation choice (ErrorHandler class, middleware, decorator) depends on project stack and size.
Effort: M-L
inversify, awilix, tsyringe (Node), dependency_injector (Python), Spring @Autowired (Java), ASP.NET IServiceCollection (C#)new SomeService() in business logic (direct instantiation)bootstrap.ts, init.py, Startup.cs, app.module.ts| Severity | Criteria |
|---|---|
| MEDIUM | No DI container (tight coupling) |
| MEDIUM | Direct instantiation in business logic |
| LOW | Mixed DI and direct imports |
Outcome Goal: Dependencies are replaceable for testing without modifying production code. No tight coupling between service instantiation and business logic. Implementation choice (DI container, factory functions, parameter injection, closures) depends on project size and stack.
Effort: L
docs/architecture.md, docs/best-practices.md, ARCHITECTURE.md, CONTRIBUTING.md| Severity | Criteria |
|---|---|
| LOW | No architecture/best practices guide |
Recommendation: Create docs/architecture.md with layering rules, error handling patterns, DI usage, coding conventions.
Effort: S
MANDATORY READ: Load shared/references/audit_worker_core_contract.md and shared/references/audit_scoring.md.
MANDATORY READ: Load shared/references/audit_worker_core_contract.md and shared/templates/audit_worker_report_template.md.
Write report to {output_dir}/623-principles-{domain}.md (or 623-principles.md in global mode) with category: "Architecture & Design".
FINDINGS-EXTENDED block (required for this worker): After the Findings table, include a <!-- FINDINGS-EXTENDED --> JSON block containing all DRY findings with pattern_signature for cross-domain matching by ln-620 coordinator. Follow shared/templates/audit_worker_report_template.md.
pattern_id: DRY type identifier (dry_1.1 through dry_1.10). Omit for non-DRY findings.
pattern_signature: Normalized key for the detected pattern (e.g., validation_email, sql_users_findByEmail, middleware_auth_validate_ratelimit). Same signature in multiple domains triggers cross-domain DRY finding. Format is defined in references/detection_patterns.md.
Return summary to coordinator:
Report written: docs/project/.audit/ln-620/{YYYY-MM-DD}/623-principles-users.md
Score: X.X/10 | Issues: N (C:N H:N M:N L:N)
MANDATORY READ: Load shared/references/audit_worker_core_contract.md.
domain_mode="domain-aware", scan ONLY scan_pathdomain field in each finding when domain-awarepattern_id + pattern_signature for every DRY findingprinciples.md to define what's acceptabledetection_patterns.md#exclusions)MANDATORY READ: Load shared/references/audit_worker_core_contract.md.
references/detection_patterns.mdreferences/refactoring_decision_tree.mdshared/references/audit_scoring.md{output_dir}/623-principles-{domain}.md with FINDINGS-EXTENDED block (atomic single Write call)Version: 5.0.0 Last Updated: 2026-02-08
Weekly Installs
164
Repository
GitHub Stars
253
First Seen
Feb 2, 2026
Security Audits
Gen Agent Trust HubPassSocketPassSnykWarn
Installed on
claude-code152
cursor151
codex148
gemini-cli148
opencode148
github-copilot145
Skills CLI 使用指南:AI Agent 技能包管理器安装与管理教程
33,600 周安装
references/refactoring_decision_tree.md for pattern selectiondomain: domain_name (if domain-aware)pattern_signature for cross-domain matching by ln-620shared/templates/audit_worker_report_template.md, write to {output_dir}/623-principles-{domain}.md (or 623-principles.md in global mode) in single Write call. Include<!-- FINDINGS-EXTENDED --> JSON block with pattern_signature fields for cross-domain DRY analysis| M |
| 1.4 Similar Patterns | Functions with same call sequence/control flow but different names/entities | MEDIUM: business logic in critical paths. LOW: utilities <3x | Modules with divergent evolution expected → skip | Extract common logic (see decision tree for pattern) | M |
| 1.5 Duplicated SQL/ORM | Same queries in different services | HIGH: payment/auth queries. MEDIUM: common 3+x. LOW: simple <3x | Different bounded contexts; shared DB is worse than duplication → skip | Extract to Repository layer | M |
| 1.6 Copy-Pasted Tests | Identical setup/teardown/fixtures across test files | MEDIUM: setup in 5+ files. LOW: <5 files | Tests intentionally isolated for clarity/independence → downgrade | Extract to test helpers | M |
| 1.7 Repeated API Responses | Same response object shapes without DTOs | MEDIUM: in 5+ endpoints. LOW: <5 endpoints | Responses with different versioning lifecycle → skip | Create DTO/Response classes | M |
| 1.8 Duplicated Middleware Chains | Identical middleware/decorator stacks on multiple routes | MEDIUM: same chain on 5+ routes. LOW: <5 routes | Routes with different auth/rate-limit requirements → skip | Create named middleware group, apply at router level | M |
| 1.9 Duplicated Type Definitions | Interfaces/structs/types with 80%+ same fields | MEDIUM: in 5+ files. LOW: 2-4 files | Types with different ownership/evolution paths → skip | Create shared base type, extend where needed | M |
| 1.10 Duplicated Mapping Logic | Same entity→DTO / DTO→entity transformations in multiple locations | MEDIUM: in 3+ locations. LOW: 2 locations | Mappings with different validation/enrichment rules → skip | Create dedicated Mapper class/function | M |
Grep <T extends ... & ...> |
| LOW: acceptable tradeoff |
| Type safety for public API boundary → skip |
| Simplify constraints |
| M |
| Wrapper-only classes | Read: all methods delegate to inner | MEDIUM: unnecessary indirection | Adapter pattern for external API isolation → skip | Remove wrapper, use inner directly | M |
| Remove interface, use class directly |
| M |
| Premature generics (used with 1 type) | Grep generic usage → count type params | LOW: over-engineering | Public library API designed for consumers → skip | Replace generic with concrete type | S |