ln-623-code-principles-auditor

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Code Principles Auditor (L3 Worker)

代码原则审计器（L3工作器）

Specialized worker auditing code principles (DRY, KISS, YAGNI) and design patterns.

专注于审计代码原则（DRY、KISS、YAGNI）和设计模式的工作器。

Purpose & Scope

目的与范围

Worker in ln-620 coordinator pipeline - invoked by ln-620-codebase-auditor
Audit code principles (DRY/KISS/YAGNI, error handling, DI)
Check DRY/KISS/YAGNI violations, TODO/FIXME, workarounds, error handling
Return structured findings with severity, location, effort, recommendations
Calculate compliance score (X/10) for Code Principles category

ln-620协调器流水线中的工作器 - 由ln-620-codebase-auditor调用
审计代码原则（DRY/KISS/YAGNI、错误处理、DI）
检查DRY/KISS/YAGNI违规、TODO/FIXME注释、临时解决方案、错误处理情况
返回包含严重程度、位置、修复工作量和建议的结构化检测结果
计算代码原则类别的合规得分（X/10）

Inputs (from Coordinator)

输入（来自协调器）

MANDATORY READ: Load

shared/references/task_delegation_pattern.md#audit-coordinator--worker-contract

for contextStore structure.

Receives

contextStore

with:

tech_stack

best_practices

principles

codebase_root

Domain-aware: Supports

domain_mode

current_domain

(see

audit_output_schema.md#domain-aware-worker-output

必读： 加载

shared/references/task_delegation_pattern.md#audit-coordinator--worker-contract

以了解contextStore结构。

接收包含以下字段的

contextStore

：

tech_stack

、

best_practices

、

principles

、

codebase_root

。

领域感知： 支持

domain_mode

current_domain

（详见

audit_output_schema.md#domain-aware-worker-output

）。

Workflow

工作流程

Parse context — extract fields, determine
```
scan_path
```
(domain-aware if specified)
Scan codebase for violations
- All Grep/Glob patterns use
```
scan_path
```
  (not codebase_root)
- Example:
```
Grep(pattern="TODO", path=scan_path)
```
Collect findings with severity, location, effort, recommendation
- Tag each finding with
```
domain: domain_name
```
  (if domain-aware)
Calculate score using penalty algorithm
Return JSON result to coordinator
- Include
```
domain
```
  and
```
scan_path
```
  fields (if domain-aware)

解析上下文 — 提取字段，确定
```
scan_path
```
（若指定则启用领域感知）
扫描代码库查找违规项
- 所有Grep/Glob模式均使用
```
scan_path
```
  （而非codebase_root）
- 示例：
```
Grep(pattern="TODO", path=scan_path)
```
收集包含严重程度、位置、修复工作量和建议的检测结果
- 若启用领域感知，为每个检测结果添加
```
domain: domain_name
```
  标签
使用惩罚算法计算得分
向协调器返回JSON结果
- 若启用领域感知，包含
```
domain
```
  和
```
scan_path
```
  字段

Audit Rules (Priority: HIGH)

审计规则（优先级：高）

1. DRY Violations (Don't Repeat Yourself)

1. DRY违规（Don't Repeat Yourself - 不要重复自己）

What: Duplicated logic, constants, or code blocks across files

Detection Categories:

定义： 跨文件重复的逻辑、常量或代码块

检测类别：

1.1. Identical Code Duplication

1.1. 完全相同的代码重复

Search for identical functions (use AST comparison or text similarity)
Find repeated constants: same value defined in multiple files
Detect copy-pasted code blocks (>10 lines identical)

Severity:

HIGH: Critical business logic duplicated (payment, auth)
MEDIUM: Utility functions duplicated
LOW: Simple constants duplicated (<5 occurrences)

搜索完全相同的函数（使用AST对比或文本相似度匹配）
查找重复定义的常量：同一值在多个文件中定义
检测复制粘贴的代码块（超过10行完全相同）

严重程度：

高：关键业务逻辑重复（支付、认证）
中：工具函数重复
低：简单常量重复（出现次数<5次）

1.2. Duplicated Validation Logic

1.2. 重复的验证逻辑

What: Same validation patterns repeated across validators/controllers

Detection:

Email validation:
```
/@.*\./
```
regex patterns in multiple files
Password validation:
```
/.{8,}/
```
, strength checks repeated
Phone validation: phone number regex duplicated
Common patterns:
```
isValid*
```
,
```
validate*
```
,
```
check*
```
functions with similar logic

Severity:

HIGH: Auth/payment validation duplicated (inconsistency risk)
MEDIUM: User input validation duplicated (3+ occurrences)
LOW: Simple format checks duplicated (<3 occurrences)

Recommendation: Extract to shared validators module (

validators/common.ts

)

Effort: M (extract validators, update imports)

定义： 验证器/控制器中重复的相同验证模式

检测方式：

邮箱验证：在多个文件中查找
```
/@.*\./
```
正则表达式
密码验证：重复出现的
```
/.{8,}/
```
、强度检查逻辑
手机号验证：重复的手机号正则表达式
常见模式：包含相似逻辑的
```
isValid*
```
、
```
validate*
```
、
```
check*
```
函数

严重程度：

高：认证/支付验证逻辑重复（存在不一致风险）
中：用户输入验证逻辑重复（出现次数≥3次）
低：简单格式检查重复（出现次数<3次）

建议： 提取到共享验证器模块（如

validators/common.ts

）

修复工作量： 中（提取验证器，更新导入）

1.3. Repeated Error Messages

1.3. 重复的错误消息

What: Hardcoded error messages instead of centralized error catalog

Detection:

Grep for hardcoded strings in

throw new Error("...")

res.status(400).json({ error: "..." })

Find repeated messages: "User not found", "Invalid credentials", "Unauthorized access"

Check for missing error constants file:

errors.ts

error-messages.ts

constants/errors.ts

Severity:

MEDIUM: Critical error messages hardcoded (auth, payment) - inconsistency risk
MEDIUM: No centralized error messages file
LOW: Same error message in <3 places

Recommendation:

Create central error messages file (
```
constants/error-messages.ts
```
)

Define error catalog:

const ERRORS = { USER_NOT_FOUND: "User not found", ... }

Replace hardcoded strings with constants:
```
throw new Error(ERRORS.USER_NOT_FOUND)
```

Effort: M (create error catalog, replace hardcoded strings)

定义： 使用硬编码错误消息而非集中式错误目录

检测方式：

查找

throw new Error("...")

、

res.status(400).json({ error: "..." })

中的硬编码字符串

查找重复消息：如"User not found"、"Invalid credentials"、"Unauthorized access"
检查是否缺少错误常量文件：如
```
errors.ts
```
、
```
error-messages.ts
```
、
```
constants/errors.ts
```

严重程度：

中：关键错误消息硬编码（认证、支付）- 存在不一致风险
中：无集中式错误消息文件
低：同一错误消息出现次数<3次

建议：

创建集中式错误消息文件（如
```
constants/error-messages.ts
```
）

定义错误目录：

const ERRORS = { USER_NOT_FOUND: "User not found", ... }

用常量替换硬编码字符串：
```
throw new Error(ERRORS.USER_NOT_FOUND)
```

修复工作量： 中（创建错误目录，替换硬编码字符串）

1.4. Similar Code Patterns (>80% Similarity)

1.4. 相似代码模式（相似度>80%）

What: Code with similar logic but different variable names/structure

Detection:

Use fuzzy matching/similarity algorithms (Levenshtein distance, Jaccard similarity)
Compare function bodies ignoring variable names
Threshold: >80% similarity = potential duplication

Example:

typescript

// File 1
function processUser(user) { return user.name.toUpperCase(); }

// File 2
function formatUserName(u) { return u.name.toUpperCase(); }
// ✅ Same logic, different names - DETECTED

Severity:

MEDIUM: Similar business logic (>80% similarity) in critical paths
LOW: Similar utility functions (<3 occurrences)

Recommendation: Extract common logic, create shared helper function

Effort: M (refactor to shared module)

定义： 逻辑相似但变量名/结构不同的代码

检测方式：

使用模糊匹配/相似度算法（Levenshtein距离、Jaccard相似度）
忽略变量名对比函数体
阈值：相似度>80% = 潜在重复

示例：

typescript

// 文件1
function processUser(user) { return user.name.toUpperCase(); }

// 文件2
function formatUserName(u) { return u.name.toUpperCase(); }
// ✅ 逻辑相同，名称不同 - 已检测

严重程度：

中：关键路径中存在相似业务逻辑（相似度>80%）
低：相似工具函数重复（出现次数<3次）

建议： 提取通用逻辑，创建共享辅助函数

修复工作量： 中（重构为共享模块）

1.5. Duplicated SQL Queries

1.5. 重复的SQL查询

What: Same SQL queries/ORM calls in different controllers/services

Detection:

Find repeated raw SQL strings:
```
SELECT * FROM users WHERE id = ?
```
ORM duplicates:
```
User.findOne({ where: { email } })
```
in multiple files
Grep for common patterns:
```
SELECT
```
,
```
INSERT
```
,
```
UPDATE
```
,
```
DELETE
```
with similar structure

Severity:

HIGH: Critical queries duplicated (payment, auth)
MEDIUM: Common queries duplicated (3+ occurrences)
LOW: Simple queries duplicated (<3 occurrences)

Recommendation: Extract to Repository layer, create query methods

Effort: M (create repository methods, update callers)

定义： 不同控制器/服务中重复的SQL查询/ORM调用

检测方式：

查找重复的原生SQL字符串：如
```
SELECT * FROM users WHERE id = ?
```
ORM重复：多个文件中出现的
```
User.findOne({ where: { email } })
```
查找常见模式：结构相似的
```
SELECT
```
、
```
INSERT
```
、
```
UPDATE
```
、
```
DELETE
```
语句

严重程度：

高：关键查询重复（支付、认证）
中：通用查询重复（出现次数≥3次）
低：简单查询重复（出现次数<3次）

建议： 提取到Repository层，创建查询方法

修复工作量： 中（创建仓库方法，更新调用方）

1.6. Copy-Pasted Tests

1.6. 复制粘贴的测试用例

What: Test files with identical structure (arrange-act-assert duplicated)

Detection:

Find tests with >80% similar setup/teardown
Repeated test data: same fixtures defined in multiple test files
Pattern:
```
beforeEach
```
,
```
afterEach
```
with identical code

Severity:

MEDIUM: Test setup duplicated in 5+ files
LOW: Similar test utilities duplicated (<5 files)

Recommendation: Extract to test helpers (

tests/helpers/*

), use shared fixtures

Effort: M (create test utilities, refactor tests)

定义： 结构完全相同的测试文件（Arrange-Act-Assert流程重复）

检测方式：

查找设置/清理逻辑相似度>80%的测试用例
重复的测试数据：多个测试文件中定义的相同测试夹具
模式：
```
beforeEach
```
、
```
afterEach
```
中包含完全相同的代码

严重程度：

中：测试设置在5个以上文件中重复
低：相似测试工具重复（出现文件数<5个）

建议： 提取到测试辅助工具（如

tests/helpers/*

），使用共享夹具

修复工作量： 中（创建测试工具，重构测试用例）

1.7. Repeated API Response Structures

1.7. 重复的API响应结构

What: Duplicated response objects instead of shared DTOs

Detection:

Find repeated object structures in API responses:

typescript

return { id: user.id, name: user.name, email: user.email }

Check for missing DTOs folder:
```
dtos/
```
,
```
responses/
```
,
```
models/
```
Grep for common patterns:
```
return { ... }
```
in controllers

Severity:

MEDIUM: Response structures duplicated in 5+ endpoints (inconsistency risk)
LOW: Simple response objects duplicated (<5 endpoints)

Recommendation: Create DTOs/Response classes, use serializers

Effort: M (create DTOs, update endpoints)

Overall Recommendation for DRY: Extract to shared module, create utility function, centralize constants/messages/validators/DTOs

Overall Effort: M (refactor + update imports, typically 1-4 hours per duplication type)

定义： 使用重复的响应对象而非共享DTO

检测方式：

查找API响应中重复的对象结构：

typescript

return { id: user.id, name: user.name, email: user.email }

检查是否缺少DTO文件夹：如
```
dtos/
```
、
```
responses/
```
、
```
models/
```
查找控制器中常见的
```
return { ... }
```
模式

严重程度：

中：响应结构在5个以上端点中重复（存在不一致风险）
低：简单响应对象重复（涉及端点<5个）

建议： 创建DTO/响应类，使用序列化器

修复工作量： 中（创建DTO，更新端点）

DRY整体建议： 提取到共享模块，创建工具函数，集中管理常量/消息/验证器/DTO

整体修复工作量： 中（重构+更新导入，每种重复类型通常需1-4小时）

2. KISS Violations (Keep It Simple, Stupid)

2. KISS违规（Keep It Simple, Stupid - 保持简单）

What: Over-engineered abstractions, unnecessary complexity

Detection:

Abstract classes with single implementation
Factory patterns for 2 objects
Deep inheritance (>3 levels)
Generic types with excessive constraints

Severity:

HIGH: Abstraction prevents understanding core logic
MEDIUM: Unnecessary pattern (factory for 2 types)
LOW: Over-generic types (acceptable tradeoff)

Recommendation: Remove abstraction, inline implementation, flatten hierarchy

Effort: L (requires careful refactoring)

定义： 过度设计的抽象、不必要的复杂度

检测方式：

仅有单一实现的抽象类
针对2个对象使用工厂模式
深度继承（超过3层）
带有过多约束的泛型类型

严重程度：

高：抽象导致核心逻辑难以理解
中：不必要的设计模式（为2种类型使用工厂）
低：过度泛化的类型（可接受的权衡）

建议： 移除抽象，内联实现，扁平化继承层级

修复工作量： 高（需谨慎重构）

3. YAGNI Violations (You Aren't Gonna Need It)

3. YAGNI违规（You Aren't Gonna Need It - 你不会需要它）

What: Unused extensibility, dead feature flags, premature optimization

Detection:

Feature flags that are always true/false
Abstract methods never overridden
Config options never used
Interfaces with single implementation (no plans for more)

Severity:

MEDIUM: Unused extensibility points adding complexity
LOW: Dead feature flags (cleanup needed)

Recommendation: Remove unused code, simplify interfaces

Effort: M (verify no future use, then delete)

定义： 未使用的扩展性、废弃的功能标志、过早优化

检测方式：

始终为true/false的功能标志
从未被重写的抽象方法
从未使用的配置选项
仅有单一实现的接口（无扩展计划）

严重程度：

中：未使用的扩展点增加了复杂度
低：废弃的功能标志（需要清理）

建议： 移除未使用的代码，简化接口

修复工作量： 中（确认无未来使用场景后删除）

4. TODO/FIXME/HACK Comments

4. TODO/FIXME/HACK注释

What: Unfinished work, temporary solutions

Detection:

Grep for
```
TODO
```
,
```
FIXME
```
,
```
HACK
```
,
```
XXX
```
,
```
OPTIMIZE
```
Check age (git blame) - old TODOs are higher severity

Severity:

HIGH: TODO in critical path (auth, payment) >6 months old
MEDIUM: FIXME/HACK with explanation
LOW: Recent TODO (<1 month) with plan

Recommendation: Complete TODO, remove HACK, refactor workaround

Effort: Varies (S for simple TODO, L for architectural HACK)

定义： 未完成的工作、临时解决方案

检测方式：

查找
```
TODO
```
、
```
FIXME
```
、
```
HACK
```
、
```
XXX
```
、
```
OPTIMIZE
```
注释
检查注释时长（通过git blame）- 存在时间久的TODO严重程度更高

严重程度：

高：关键路径（认证、支付）中存在超过6个月的TODO
中：带有说明的FIXME/HACK注释
低：近期的TODO（<1个月）且有明确计划

建议： 完成TODO，移除HACK，重构临时解决方案

修复工作量： 不定（简单TODO为小工作量，架构级HACK为大工作量）

5. Missing Error Handling

5. 缺失错误处理

What: Critical paths without try-catch, error propagation

Detection:

Find async functions without error handling
Check API routes without error middleware
Verify database calls have error handling

Severity:

CRITICAL: Payment/auth without error handling
HIGH: User-facing operations without error handling
MEDIUM: Internal operations without error handling

Recommendation: Add try-catch, implement error middleware, propagate errors properly

Effort: M (add error handling logic)

定义： 关键路径中缺少try-catch、错误传播机制

检测方式：

查找未处理错误的异步函数
检查未使用错误中间件的API路由
验证数据库调用是否有错误处理

严重程度：

严重： 支付/认证逻辑无错误处理
高：用户面向的操作无错误处理
中：内部操作无错误处理

建议： 添加try-catch，实现错误中间件，正确传播错误

修复工作量： 中（添加错误处理逻辑）

6. Centralized Error Handling

6. 集中式错误处理

What: Errors handled inconsistently across different contexts (web requests, cron jobs, background tasks)

Detection:

Search for centralized error handler class/module:
```
ErrorHandler
```
,
```
errorHandler
```
,
```
error-handler.ts/js/py
```
Check if error middleware delegates to handler:
```
errorHandler.handleError(err)
```
or similar
Verify all async routes use promises or async/await (Express 5+ auto-catches rejections)
Check for error transformation (sanitize stack traces for users in production)
Anti-pattern check: Look for
```
process.on("uncaughtException")
```
usage (BAD PRACTICE per Express docs)

Severity:

HIGH: No centralized error handler (errors handled inconsistently in multiple places)
HIGH: Using
```
uncaughtException
```
listener instead of proper error propagation (Express anti-pattern)
MEDIUM: Error middleware handles errors directly (doesn't delegate to central handler)
MEDIUM: Async routes without proper error handling (not using promises/async-await)
LOW: Stack traces exposed in production responses (security/UX issue)

Recommendation:

Create single ErrorHandler class/module for ALL error contexts
Middleware should only catch and forward to ErrorHandler (delegate pattern)
Use async/await for async routes (framework auto-forwards errors)
Transform errors for users: hide sensitive details (stack traces, internal paths) in production
DO NOT use uncaughtException listeners - use process managers (PM2, systemd) for restart instead
For unhandled rejections: log and restart process (use supervisor, not inline handler)

Effort: M-L (create error handler, refactor existing middleware)

定义： 不同上下文（Web请求、定时任务、后台任务）中错误处理不一致

检测方式：

查找集中式错误处理类/模块：如
```
ErrorHandler
```
、
```
errorHandler
```
、
```
error-handler.ts/js/py
```
检查错误中间件是否委托给处理程序：如
```
errorHandler.handleError(err)
```
或类似调用
验证所有异步路由是否使用Promise或async/await（Express 5+会自动捕获拒绝）
检查错误转换（生产环境中清理堆栈跟踪）
反模式检查： 查找
```
process.on("uncaughtException")
```
的使用（根据Express文档，这是不良实践）

严重程度：

高：无集中式错误处理程序（错误在多个位置处理不一致）
高：使用
```
uncaughtException
```
监听器而非正确的错误传播（Express反模式）
中：错误中间件直接处理错误（未委托给集中式处理程序）
中：异步路由未正确处理错误（未使用Promise/async-await）
低：生产环境响应中暴露堆栈跟踪（安全/用户体验问题）

建议：

为所有错误上下文创建单一的ErrorHandler类/模块
中间件应仅捕获并转发给ErrorHandler（委托模式）
异步路由使用async/await（框架会自动转发错误）
为用户转换错误：生产环境中隐藏敏感细节（堆栈跟踪、内部路径）
请勿使用uncaughtException监听器 - 改用进程管理器（PM2、systemd）重启进程
对于未处理的拒绝：记录日志并重启进程（使用监控程序，而非内联处理程序）

修复工作量： 中-高（创建错误处理程序，重构现有中间件）

7. Dependency Injection / Centralized Init

7. 依赖注入 / 集中式初始化

What: Direct imports/instantiation instead of dependency injection, scattered initialization

Detection:

Check for DI container usage:
- Node.js:
```
inversify
```
  ,
```
awilix
```
  ,
```
tsyringe
```
  ,
```
typedi
```
  packages
- Python:
```
dependency_injector
```
  ,
```
injector
```
  packages
- Java: Spring
```
@Autowired
```
  ,
```
@Inject
```
  annotations
- .NET: Built-in DI in ASP.NET Core,
```
IServiceCollection
```
Grep for direct instantiations in business logic:
```
new SomeService()
```
,
```
new SomeRepository()
```
Check for centralized Init/Bootstrap module:
```
bootstrap.ts
```
,
```
init.py
```
,
```
Startup.cs
```
,
```
app.module.ts
```
Verify controllers/services receive dependencies via constructor/parameters, not direct imports

Severity:

MEDIUM: No DI container (hard to test, tight coupling, difficult to swap implementations)
MEDIUM: Direct instantiation in business logic (
```
new Service()
```
in controllers/services)
LOW: Mixed DI and direct imports (inconsistent pattern)

Recommendation:

Use DI container for dependency management (Inversify, Awilix, Spring, built-in .NET DI)
Centralize initialization in Init/Bootstrap module
Inject dependencies via constructor/parameters (dependency injection pattern)
Never use direct instantiation for business logic classes (only for DTOs, value objects)

Effort: L (refactor to DI pattern, add container, update all instantiations)

定义： 使用直接导入/实例化而非依赖注入，初始化逻辑分散

检测方式：

检查DI容器的使用：
- Node.js：
```
inversify
```
  、
```
awilix
```
  、
```
tsyringe
```
  、
```
typedi
```
  包
- Python：
```
dependency_injector
```
  、
```
injector
```
  包
- Java：Spring的
```
@Autowired
```
  、
```
@Inject
```
  注解
- .NET：ASP.NET Core内置DI、
```
IServiceCollection
```
查找业务逻辑中的直接实例化：如
```
new SomeService()
```
、
```
new SomeRepository()
```
检查是否存在集中式Init/Bootstrap模块：如
```
bootstrap.ts
```
、
```
init.py
```
、
```
Startup.cs
```
、
```
app.module.ts
```
验证控制器/服务是否通过构造函数/参数接收依赖，而非直接导入

严重程度：

中：无DI容器（测试困难、耦合紧密、难以替换实现）
中：业务逻辑中直接实例化（控制器/服务中使用
```
new Service()
```
）
低： DI与直接导入混合使用（模式不一致）

建议：

使用DI容器管理依赖（如Inversify、Awilix、Spring、.NET内置DI）
在Init/Bootstrap模块中集中初始化
通过构造函数/参数注入依赖（依赖注入模式）
业务逻辑类绝不要使用直接实例化（仅DTO、值对象可使用）

修复工作量： 高（重构为DI模式，添加容器，更新所有实例化代码）

8. Missing Best Practices Guide

8. 缺失最佳实践指南

What: No architecture/design best practices documentation for developers

Detection:

Check for architecture guide files:

docs/architecture.md

docs/best-practices.md

docs/design-patterns.md

```
ARCHITECTURE.md
```
,
```
CONTRIBUTING.md
```
(architecture section)

Verify content includes: layering rules, error handling patterns, DI usage, coding conventions

Severity:

LOW: No architecture guide (harder for new developers to understand patterns and conventions)

Recommendation:

Create
```
docs/architecture.md
```
with project-specific patterns:
- Document layering: Controller→Service→Repository→DB
- Error handling: centralized ErrorHandler pattern
- Dependency Injection: how to add new services/repositories
- Coding conventions: naming, file organization, imports
Include examples from existing codebase
Keep framework-agnostic (principles, not specific implementations)

Effort: S (create markdown file, ~1-2 hours documentation)

定义： 无面向开发者的架构/设计最佳实践文档

检测方式：

查找架构指南文件：

docs/architecture.md

、

docs/best-practices.md

、

docs/design-patterns.md

```
ARCHITECTURE.md
```
、
```
CONTRIBUTING.md
```
（架构章节）

验证内容是否包含：分层规则、错误处理模式、DI使用、编码规范

严重程度：

低：无架构指南（新开发者难以理解模式和规范）

建议：

创建
```
docs/architecture.md
```
，包含项目特定模式：
- 文档分层：Controller→Service→Repository→DB
- 错误处理：集中式ErrorHandler模式
- 依赖注入：如何添加新服务/仓库
- 编码规范：命名、文件组织、导入规则
包含现有代码库中的示例
保持框架无关（聚焦原则，而非具体实现）

修复工作量： 小（创建Markdown文件，约1-2小时文档编写）

Scoring Algorithm

评分算法

See

shared/references/audit_scoring.md

for unified formula and score interpretation.

统一公式和得分解释详见

shared/references/audit_scoring.md

。

Output Format

输出格式

Return JSON to coordinator:

Global mode output:

json

{
  "category": "Architecture & Design",
  "score": 6,
  "total_issues": 12,
  "critical": 2,
  "high": 4,
  "medium": 4,
  "low": 2,
  "checks": [
    {"id": "dry_violations", "name": "DRY Violations", "status": "failed", "details": "4 duplications found"},
    {"id": "kiss_violations", "name": "KISS Violations", "status": "warning", "details": "1 over-engineered abstraction"},
    {"id": "yagni_violations", "name": "YAGNI Violations", "status": "passed", "details": "No unused code"},
    {"id": "solid_violations", "name": "SOLID Violations", "status": "failed", "details": "2 SRP violations"}
  ],
  "findings": [...]
}

Domain-aware mode output (NEW):

json

{
  "category": "Architecture & Design",
  "score": 6,
  "domain": "users",
  "scan_path": "src/users",
  "total_issues": 12,
  "critical": 2,
  "high": 4,
  "medium": 4,
  "low": 2,
  "checks": [
    {"id": "dry_violations", "name": "DRY Violations", "status": "failed", "details": "4 duplications found"},
    {"id": "kiss_violations", "name": "KISS Violations", "status": "warning", "details": "1 over-engineered abstraction"},
    {"id": "yagni_violations", "name": "YAGNI Violations", "status": "passed", "details": "No unused code"},
    {"id": "solid_violations", "name": "SOLID Violations", "status": "failed", "details": "2 SRP violations"}
  ],
  "findings": [
    {
      "severity": "CRITICAL",
      "location": "src/users/controllers/UserController.ts:45",
      "issue": "Controller directly uses Repository (layer boundary break)",
      "principle": "Layer Separation (Clean Architecture)",
      "recommendation": "Create UserService, inject into controller",
      "effort": "L",
      "domain": "users"
    },
    {
      "severity": "HIGH",
      "location": "src/users/services/UserService.ts:45",
      "issue": "DRY violation - duplicate validation logic",
      "principle": "DRY Principle",
      "recommendation": "Extract to shared validators module",
      "effort": "M",
      "domain": "users"
    }
  ]
}

向协调器返回JSON：

全局模式输出：

json

{
  "category": "Architecture & Design",
  "score": 6,
  "total_issues": 12,
  "critical": 2,
  "high": 4,
  "medium": 4,
  "low": 2,
  "checks": [
    {"id": "dry_violations", "name": "DRY Violations", "status": "failed", "details": "4 duplications found"},
    {"id": "kiss_violations", "name": "KISS Violations", "status": "warning", "details": "1 over-engineered abstraction"},
    {"id": "yagni_violations", "name": "YAGNI Violations", "status": "passed", "details": "No unused code"},
    {"id": "solid_violations", "name": "SOLID Violations", "status": "failed", "details": "2 SRP violations"}
  ],
  "findings": [...]
}

领域感知模式输出（新增）：

json

{
  "category": "Architecture & Design",
  "score": 6,
  "domain": "users",
  "scan_path": "src/users",
  "total_issues": 12,
  "critical": 2,
  "high": 4,
  "medium": 4,
  "low": 2,
  "checks": [
    {"id": "dry_violations", "name": "DRY Violations", "status": "failed", "details": "4 duplications found"},
    {"id": "kiss_violations", "name": "KISS Violations", "status": "warning", "details": "1 over-engineered abstraction"},
    {"id": "yagni_violations", "name": "YAGNI Violations", "status": "passed", "details": "No unused code"},
    {"id": "solid_violations", "name": "SOLID Violations", "status": "failed", "details": "2 SRP violations"}
  ],
  "findings": [
    {
      "severity": "CRITICAL",
      "location": "src/users/controllers/UserController.ts:45",
      "issue": "Controller directly uses Repository (layer boundary break)",
      "principle": "Layer Separation (Clean Architecture)",
      "recommendation": "Create UserService, inject into controller",
      "effort": "L",
      "domain": "users"
    },
    {
      "severity": "HIGH",
      "location": "src/users/services/UserService.ts:45",
      "issue": "DRY violation - duplicate validation logic",
      "principle": "DRY Principle",
      "recommendation": "Extract to shared validators module",
      "effort": "M",
      "domain": "users"
    }
  ]
}

Critical Rules

关键规则

Do not auto-fix: Report only
Domain-aware scanning: If
```
domain_mode="domain-aware"
```
, scan ONLY
```
scan_path
```
(not entire codebase)
Tag findings: Include
```
domain
```
field in each finding when domain-aware
Context-aware: Use project's
```
principles.md
```
to define what's acceptable
Age matters: Old TODOs are higher severity than recent ones
Effort realism: S = <1h, M = 1-4h, L = >4h

请勿自动修复： 仅报告问题
领域感知扫描： 若
```
domain_mode="domain-aware"
```
，仅扫描
```
scan_path
```
（而非整个代码库）
标记检测结果： 启用领域感知时，为每个检测结果添加
```
domain
```
字段
上下文感知： 使用项目的
```
principles.md
```
定义可接受的标准
时长重要： 存在时间久的TODO比近期的TODO严重程度更高
修复工作量需真实： S = <1小时, M = 1-4小时, L = >4小时

Definition of Done

完成标准

contextStore parsed (including domain_mode and current_domain)
scan_path determined (domain path or codebase root)
All 8 checks completed (scoped to scan_path):
- DRY (7 subcategories), KISS, YAGNI, TODOs, Error Handling, Centralized Errors, DI/Init, Best Practices Guide
Findings collected with severity, location, effort, recommendation, domain
Score calculated
JSON returned to coordinator with domain metadata

已解析contextStore（包括domain_mode和current_domain）
已确定scan_path（领域路径或代码库根目录）
已完成全部8项检查（限定在scan_path范围内）：
- DRY（7个子类别）、KISS、YAGNI、TODO注释、错误处理、集中式错误处理、DI/初始化、最佳实践指南
已收集包含严重程度、位置、修复工作量、建议、领域的检测结果
已计算得分
已向协调器返回包含领域元数据的JSON

Reference Files

参考文件

Audit scoring formula:
```
shared/references/audit_scoring.md
```

Audit output schema:

shared/references/audit_output_schema.md

Architecture rules: references/architecture_rules.md

Version: 4.1.0 Last Updated: 2026-01-29

审计评分公式：
```
shared/references/audit_scoring.md
```

审计输出 schema：

shared/references/audit_output_schema.md

架构规则：references/architecture_rules.md

版本： 4.1.0 最后更新： 2026-01-29