BadBeta/archdo
GitHub: BadBeta/archdo
Elixir 架构质量检查器，通过 186 条规则覆盖边界、OTP、模块质量、测试与编译分析，辅助发现结构性问题与 LLM 冗余。
Stars: 0 | Forks: 0
# Archdo
Elixir 的架构质量检查器。捕捉 Credo（风格）、Dialyzer（类型）和 Sobelow（安全）遗漏的问题：结构性问题、SOLID 违规、OTP 反模式、边界约束、某些 LLM 代码冗余等。
**186 条规则**，覆盖 12 个类别。每个发现都包含 `why`、排序后的修复建议，以及结构化上下文。
## LLM 冗余检测
规则 6.33 检测五种典型的 LLM 生成的不必要冗长代码模式：`@doc` 标注在私有函数上、平凡的委托包装器（`defp foo(x), do: Bar.foo(x)`）、冗余的布尔比较（`== true`）、空文档字符串、单步管道（`x |> foo()`）。配合规则 6.34（死私有函数）、4.27（未使用的别名）、6.38（恒等变换）和 6.40（冗长的 ok/error 解包），Archdo 可以系统性地发现并移除代码库中的 AI 生成冗余。
## 检查内容
| 类别 | 规则数 | 示例 |
|------|--------|------|
| **边界** | 31 | 依赖方向、上下文封装、循环依赖、喋喋不休的边界、未验证的参数、编译期跨边界调用检测、内部模块泄露、Repo 绕过、幽灵依赖、未使用的别名 |
| **模块质量** | 42 | 复杂度、内聚性、扇出、Martin 指标、错误处理（7 条规则）、递归（4 条规则）、存根检测、**LLM 冗余检测**、死私有函数、恒等变换、防御性 nil 返回、冗长的 ok 解包、单元子句 with、常量表达式、不可达子句、冗余 guard 重检、长参数列表、嵌套控制流、布尔失明 |
| **OTP 纪律** | 41 | 阻塞回调、未监督进程、GenServer 反模式、重启不匹配、陈旧 PID、死锁检测、顺序化替代并行、回调膨胀 |
| **测试** | 23 | 未使用 Mox 配合行为、覆盖缺口、测试命名、异步资格判定、弱断言、仅测试的公共函数、过度 Mock、空 describe 块、缺失错误路径测试、未测试模块 |
| **编译分析** | 20 | 死代码、传递性死代码、爆炸半径、未使用的导入、弱依赖、API 表面权重、函数循环（Tarjan 强连通分量）、协议完备性、变更风险、循环上下文依赖、孤儿模块 |
| **事件溯源** | 8 | 聚合纯度、投影隔离、事件不可变性、命令/事件命名 |
| **NIF 安全** | 4 | 导致 Panic 的 Rust 模式、调度器误用、缺少行为包装 |
| **状态机** | 3 | 不可达状态、终端状态完整性、隐式布尔状态 |
| **组合** | 2 | 深层 `use` 链、过度命名空间深度 |
## 依赖
- **Jason** — JSON 编码，用于 MCP 和输出格式
- **JSV** — JSON Schema 验证，在 MCP 边界进行工具输入验证
## 快速开始
### 作为 Mix 依赖
```
# mix.exs
def deps do
[{:archdo, github: "BadBeta/archdo", only: [:dev, :test], runtime: false}]
end
```
```
mix archdo # scan lib/
mix archdo --format compact # one-line-per-finding
mix archdo --paths lib/my_app/accounts # scan specific paths
mix archdo --only 4.17,6.12 # run specific rules
mix archdo --boundaries # cross-module dependency analysis
mix archdo --functions # function-level graph analysis
mix archdo --compiled # compiled beam analysis (dead code, blast radius, API checks)
mix archdo --coverage # test coverage gap matrix
mix archdo --metrics # Martin package metrics matrix
```
### 无需安装即可扫描任意项目
你也可以从 Archdo 项目中扫描外部项目：
```
cd /path/to/archdo
mix archdo --paths /path/to/other_project/lib --format compact
```
## 与 Claude Code 配合使用（推荐）
Archdo 在与 Claude Code 和 [Elixir 技能](https://github.com/BadBeta/Elixir_skill) 的**双层评审**中效果最佳：
1. **第一层 — Archdo** 机械地查找结构性问题（快速、全面）
2. **第二层 — Elixir 技能** 提供领域判断，确认发现是否为真实问题或有意的折衷
### 安装设置
**步骤 1：安装 Elixir 技能**（为 Claude Code 提供深入的 Elixir 知识）：
```
cd ~/.claude/skills
git clone https://github.com/BadBeta/Elixir_skill.git elixir
```
**步骤 2：克隆 Archdo**（或将其添加为项目依赖）：
```
git clone https://github.com/BadBeta/archdo.git ~/Projects/Archdo
cd ~/Projects/Archdo && mix deps.get
```
**步骤 3：使用它。** 让 Claude Code 审查任意 Elixir 项目：
Claude 将：
1. 运行 `mix archdo --paths /path/to/my_project/lib` 进行结构性分析
2. 加载 Elixir 技能及相关子技能（OTP、架构、测试、错误处理），用领域知识评估每个发现
3. 展示问题并附带判断哪些重要以及如何以惯用方式修复
Elixir 技能的子技能包含实现第二层所需的专业知识：OTP 进程模式、架构决策框架、Ecto 约定、错误处理惯用法等。审查时请始终使用 `/elixir` 以确保加载该技能。
### MCP 服务器（可选，用于更深层集成）
对于希望将 Archdo 作为 MCP 工具的项目：
```
// .mcp.json in your project root
{
"mcpServers": {
"archdo": {
"command": "mix",
"args": ["archdo.mcp"]
}
}
}
```
这暴露了 5 个工具：`archdo_deep_review`、`archdo_analyze_paths`、`archdo_analyze_file`、`archdo_list_rules`、`archdo_explain_rule`。工具输入会通过 JSV 对照其 JSON Schema 定义进行验证。
## 输出格式
| 格式 | 用途 |
|------|------|
| `text` | 终端审查 — 分组、带颜色编码、完整解释 |
| `compact` | grep/CI — 每条发现一行 |
| `json` | 仪表板、CI 集成 |
| `llm` | NDJSON，带 Markdown，供 LLM 消费 |
## 基线/冻结
接受现有违规并仅标记新增问题：
```
mix archdo --freeze # save baseline
git add .archdo_baseline.exs
mix archdo # only new violations shown
mix archdo --freeze-stats # track progress
```
## 文档
- **[GUIDE.md](GUIDE.md)** — 完整用户指南
- **[ARCHITECTURE_RULES.md](ARCHITECTURE_RULES.md)** — 所有规则文档
- **[DESIGN.md](DESIGN.md)** — 设计哲学与架构
## 许可证
MIT。
标签：Elixir, LLM代码检测, OTP, SEO工具, 代码规范, 依赖管理, 函数式编程, 架构检查, 模块质量, 死代码检测, 测试架构, 结构化修复建议, 编译期分析, 边界检查, 错误基检测, 静态代码分析