audit

Audit v1.0.0

Cross-subsystem architecture consistency review -- multi-perspective parallel analysis of architecture health, identifying inconsistencies and technical debt

Purpose

Conduct a comprehensive architecture health review of the codebase, identifying:

• Dependency direction violations (lower layers depending on upper layers)
• Naming inconsistencies
• Inconsistent error handling patterns
• Missing cross-cutting concerns (logging, metrics, error handling)
• Code duplication and DRY violations
• Test coverage gaps

Usage

/audit [目標路徑或模組]
/audit src/api/              # 審查 API 模組
/audit src/                  # 審查 src 整體
/audit --full                # 全面審查（整個 codebase）

Flags: --full | --focus deps|patterns|tests|docs | --quick | --deep

Default 4 perspectives

ID	Name	Model	Focus
dependency-auditor	Dependency Analyst	sonnet	import/require scanning, circular dependencies, direction violations
pattern-checker	Pattern Consistency Checker	haiku	Error handling, naming conventions, API interface style
coverage-auditor	Test Coverage Analyst	haiku	Modules lacking tests, test quality, mock abuse
doc-sync-checker	Documentation Sync Checker	haiku	Code-to-documentation comparison, outdated documentation, API documentation completeness

-> Model routing configuration:shared/config/model-routing.yaml

Execution Flow

Phase 0: 收集目標 -> 確定審查範圍、掃描目標路徑
    |
Phase 1: MAP（並行審查）
    +-------------+----------------+----------------+----------------+
    | 依賴分析師  | 模式一致性     | 測試覆蓋       | 文檔同步       |
    | (sonnet)    | 檢查員 (haiku) | 分析師 (haiku) | 檢查員 (haiku) |
    +-------------+----------------+----------------+----------------+

    ** 並行執行關鍵 **：
       在單一訊息中發送 4 個 Task 工具呼叫：
       - Task({description: "依賴方向審查", ...})
       - Task({description: "模式一致性檢查", ...})
       - Task({description: "測試覆蓋分析", ...})
       - Task({description: "文檔同步檢查", ...})

    ** 強制 **：每個 Agent 完成前必須執行：
       1. mkdir -p .claude/memory/audit/{audit-id}/perspectives/
       2. Write -> .claude/memory/audit/{audit-id}/perspectives/{perspective_id}.md
       未執行 Write = 任務失敗
    |
Phase 2: REDUCE（問題匯總）
    +-- 問題分類（CRITICAL/HIGH/MEDIUM/LOW）
    +-- 按嚴重度排序
    +-- 修復建議
    |
Phase 3: 產出審查報告

Issue Classification

Level	Definition	Handling
CRITICAL	Architectural defect, may cause system failure	Fix immediately
HIGH	Consistency violation, affects maintainability	Fix within a time limit
MEDIUM	Suggested improvement, enhances quality	Record and track
LOW	Style suggestion or minor improvement	Optional

Output Structure

.claude/memory/audit/{audit-id}/
+-- meta.yaml               # 元數據（審查範圍、時間、配置）
+-- perspectives/            # 完整視角報告（MAP 產出）
|   +-- dependency-auditor.md
|   +-- pattern-checker.md
|   +-- coverage-auditor.md
|   +-- doc-sync-checker.md
+-- issues.yaml              # 問題清單（按嚴重度排序）
+-- audit-summary.md         # 審查摘要 + 建議（主輸出）

perspectives/ stores the complete analysis report for each perspective, and issues.yaml aggregates all issues.

Agent Capability Limitations

Review Agents should not open Tasks：

Allowed Operations	Description
Read	Read code and configuration
Glob/Grep	Search files and content patterns
Bash	Run analysis commands (such as dependency graph)
Write	Write review reports
Task	Not allowed to spawn sub-Agents

Perspective Prompt Guidelines

Perspective 1: Dependency Analyst (dependency-auditor)

Goal: Scan import/require statements, map dependency relationships, and identify issues.

Check Items：

1. Scan all import/require/from...import statements
2. Identify dependency directions between modules (upper layers should not depend on lower layers' concrete implementations)
3. Detect circular dependencies
4. Identify overly coupled modules (dependency count exceeds threshold)
5. Check for cross-layer dependency violations

Output Format：

• Dependency graph summary (text description)
• Issue list (including file paths, line numbers, severity)
• Suggested refactoring directions

Perspective 2: Pattern Consistency Checker (pattern-checker)

Goal: Check pattern consistency in the codebase.

Check Items：

1. Error handling patterns (unified try-catch style, use of custom error types)
2. Naming conventions (variable, function, class, file naming)
3. API interface style (REST route naming, request/response format)
4. Logging patterns (consistency of logger usage)
5. Configuration access patterns (environment variables vs configuration files)

Output format：

• Consistency score for each pattern
• Specific cases of inconsistency (including file paths and line numbers)
• Recommended unified standards

Perspective 3: Test Coverage Analyst (coverage-auditor)

Goal: Identify test coverage gaps and evaluate test quality.

Check items：

1. Identify modules without corresponding tests
2. Evaluate the quality of existing tests (whether they only test the happy path)
3. Identify mock/stub abuse (excessive mocking that makes tests meaningless)
4. Check boundary condition test coverage
5. Evaluate the ratio of integration tests to unit tests

Output format：

• List of uncovered modules
• Test quality assessment
• Recommended additional test cases

Perspective 4: Documentation Sync Checker (doc-sync-checker)

Goal: Ensure documentation and code are in sync.

Check items：

1. Compare the features described in README/CLAUDE.md with the actual code
2. Check whether the API documentation is consistent with the actual endpoints
3. Identify outdated documentation (mentions deleted modules/functions)
4. Check configuration documentation completeness (whether all environment variables are documented)
5. Confirm that command documentation is consistent with the actually available commands

Output format：

• List of documentation vs code differences
• List of outdated documentation
• Suggestions for missing documentation

CP4: Task Commit

After the review is complete, execute Task Commit:

Phase 3: 審查報告產出
    |
CP4: Task Commit
    +-- git add .claude/memory/audit/{audit-id}/
    +-- git commit -m "docs(audit): complete architecture audit for {target}"

-> Protocol:shared/git/commit-protocol.md

Shared modules

Module	Purpose
coordination/map-phase.md	Parallel coordination
coordination/reduce-phase.md	Aggregation and integration
perspectives/catalog.yaml	Perspective definition

Workflow position

RESEARCH -> PLAN -> TASKS -> IMPLEMENT -> REVIEW -> VERIFY
                                                        |
                                              AUDIT <---+
                                         (獨立工具，隨時可用)

• Input: Target path or module name
• Output: Architecture review report, which can be referenced by PLAN or IMPLEMENT
• Positioning: An independent architecture health check tool that does not belong to a fixed workflow stage and can be run at any time