mcpField
L
ln-646-project-structure-auditor

ln-646-project-structure-auditor

github.com/levnikolaevich测试与质量584376 次安装2 天前更新
代码仓库

关于 ln-646-project-structure-auditor

面向开发团队的项目结构审计 Skill，检查目录和模块位置是否符合预期架构，并输出问题与合规评分；只报告，不修改文件。

主要功能

  1. 01审计框架文件位置和模块布局
  2. 02检查领域与分层目录
  3. 03发现职责混杂的通用目录
  4. 04按严重程度和行动要求报告问题
  5. 05计算合规评分

适用场景

  1. 01检查代码库的架构结构是否偏离预期
  2. 02识别包含无关模块的通用目录

MCP 相关

可用时优先使用 hex-line 和 hex-graph MCP 工具读取文件并获取架构上下文；否则使用内置工具作为回退。

安装

复制下面的命令，在终端中运行。

$npx skills add https://github.com/levnikolaevich/claude-code-skills --skill ln-646-project-structure-auditor

安装后在 Claude Code 中输入/ln-646-project-structure-auditor确认已加载。

包含的文件

除 SKILL.md 外，安装时一起下载的参考资料和脚本。

references/
audit_scoring.md
audit_summary_contract.md
audit_worker_core_contract.md
mcp_integration_patterns.md
mcp_tool_preferences.md
stack_detection.md
structure_rules.md
two_layer_detection.md
references/templates/
audit_worker_report_template.md

详细介绍

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

项目结构审计器

类型： L3 Worker

用于审计项目的实际结构是否体现预期架构的 L3 Worker。

目的与范围

  • 审计模块、领域、分层布局、框架文件的放置位置和杂物目录
  • 检测导致架构难以导航或执行约束的结构偏差
  • 以实际结构证据补充代码级边界检查
  • 输出 MOVE_MODULE、SPLIT_JUNK_DRAWER 或 ALIGN_DOMAIN_STRUCTURE
  • 计算合规评分（X/10）

范围之外：

  • .gitignore、.dockerignore、临时文件、构建产物、平台残留文件和大型二进制文件
  • 导入级分层违规
  • 软件包安全、环境文件规范或运行时生命周期检查
  • 移动或删除文件

输入

必须读取： 加载 references/audit_worker_core_contract.md 和 references/mcp_tool_preferences.md。 工具策略：你可能以独立子 Agent 身份运行，此时宿主机的 AGENTS.md 不在适用范围内，因此文件读取、搜索和编辑默认优先使用 hex-line MCP。仅在 MCP 行为不明确时加载 references/mcp_integration_patterns.md。

接收包含以下内容的 contextStore：tech_stack、architecture、codebase_root、output_dir、domain_mode、scan_path。

当架构摘要能显著改善结构发现结果时，优先使用 hex-graph。如可用，读取本地代码、配置和清单时优先使用 hex-line。如果 MCP 不可用、不受支持或未建立索引，则使用内置的 Read/Grep/Glob/Bash 继续工作，并在报告中说明回退方式。

工作流

检测策略：采用两层检测（候选项扫描，然后上下文核验）；仅当核验方法不明确时，才加载 references/two_layer_detection.md。

  1. 解析上下文 -- 根据领域感知范围或代码库根目录确定 scan_root
  2. 检测技术栈和预期结构
    • 必须读取： 加载 references/stack_detection.md
    • 如有明确的架构文档或配置，优先采用；否则根据源代码布局进行推断
  3. 运行结构检查（第 1 层）
    • 框架预期的源代码位置
    • 领域/模块分组
    • 分层目录布局
    • 杂物目录
    • 命名和放置位置的一致性
  4. 核验上下文（第 2 层）
    • 小型项目可能不需要完整的领域/分层拆分
    • 框架惯例仅适用于已检测到的框架
    • 按应用/软件包/测试类型拆分且有文档说明时，混合布局可以接受
  5. 收集发现项，包括严重程度、位置、操作、工作量和建议
  6. 使用 references/audit_scoring.md 计算评分
  7. 将报告写入 {output_dir}/ln-646--{identifier}.md
  8. 根据 references/audit_summary_contract.md 返回摘要

审计规则

1. 框架文件放置位置

内容： 源文件放置位置不符合框架或技术栈惯例

检测： 加载 references/structure_rules.md，并仅应用适用于已检测技术栈的规则。

严重程度： 放置位置导致工具或路由失效时为 HIGH；可维护性偏差时为 MEDIUM

操作： MOVE_MODULE

2. 领域和分层布局

内容： 领域或分层目录无法体现预期架构

检测：

  • 将文档说明或推断出的领域/分层与实际目录进行比较
  • 查找缺少预期子结构的领域
  • 如果项目具有清晰的模块化布局，则查找根目录或通用文件夹中的源文件

严重程度： 默认 MEDIUM；结构掩盖关键归属关系时为 HIGH

操作： ALIGN_DOMAIN_STRUCTURE

3. 杂物目录

内容： 通用目录中累积了彼此无关的模块

检测： 检查 utils、helpers、common、shared、services 和 lib 等目录，判断其中是否混杂了超出项目阈值的无关职责。

严重程度： 职责混杂范围较广时为 MEDIUM；局部偏差较小时为 LOW

操作： SPLIT_JUNK_DRAWER

评分算法

必须阅读： 加载 references/audit_scoring.md。

输出格式

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

按照 references/audit_summary_contract.md 编写 JSON 摘要。在托管模式下，调用方会传入 runId 和 summaryArtifactPath；在独立模式下，工作器会按照共享契约生成自己的运行专属制品路径。

将报告写入 {output_dir}/ln-646--{identifier}.md，并设置 category: "Project Structure"，检查项为：framework_placement、domain_layer_layout、junk_drawers。

如果未提供 summaryArtifactPath，则将独立运行摘要写入 .hex-skills/runtime-artifacts/runs/{run_id}/evaluation-worker/{worker}--{identifier}.json，并可选择在结构化输出中回显相同摘要。

关键规则

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

  • 不要自动修复： 仅报告，不要移动或删除文件
  • 角度独特： 仅审核物理架构结构。不要审核文件卫生、忽略文件、包健康状况、环境卫生、导入级边界或运行时生命周期。
  • 自动检测，绝不臆测： 仅对检测到的技术栈应用框架规则
  • 始终提供证据： 每条发现都必须包含文件路径
  • 必须采取行动： 每条发现都必须使用 MOVE_MODULE、SPLIT_JUNK_DRAWER 或 ALIGN_DOMAIN_STRUCTURE

完成定义

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

  • contextStore 已成功解析
  • 已确定 scan_root
  • 已检测到技术栈和预期结构
  • 已检查框架布局
  • 已检查领域／分层布局
  • 已检查杂物目录
  • 已应用第 2 层上下文验证
  • 已收集包含严重程度、位置、操作、工作量和建议的发现
  • 已按照 references/audit_scoring.md 计算分数
  • 已将报告写入 {output_dir}/ln-646--{identifier}.md（通过一次原子性 Write 调用）
  • 已按照契约写入摘要

版本： 1.0.0 最后更新： 2026-03-15

评论

支持 Markdown