MKanhan/archlint
GitHub: MKanhan/archlint
一个轻量级 Claude Code 钩子，通过解析文件导入并与预定义的层级规则比对，在 AI Agent 编码过程中实时捕获和阻断架构偏移。
Stars: 0 | Forks: 0
# archlint
一个轻量级的 Claude Code 钩子，能够通过将编辑内容与您已保存在 `CLAUDE.md` 中的架构蓝图进行比对，在 Agent 编写代码时捕获架构偏移。
无需守护进程。无需新增配置文件。LLM 不在关键路径上。只需一个仅依赖标准库的 Python 脚本。
## 功能说明
在 Claude Code 编辑您的项目时：
- **在每次 `Write`/`Edit`/`MultiEdit` 之后**，archlint 会解析文件，提取其导入项，并根据您的蓝图中声明的层级规则进行检查。如果跨越了被禁止的边界（例如 UI 直接访问数据库），它会向 Claude 反馈一条简短且可执行的建议。
- **在每个回合结束时 (`Stop`)**，archlint 会输出一份关于所有未解决偏移的检查点摘要，这样 Claude 在宣布完成之前还有最后的机会进行修复。
在 `lenient`（宽容）模式（默认）下，偏移会作为 `additionalContext` 报告，Claude 通常会在下一步自行纠正。在 `strict`（严格）模式下，偏移会触发 `decision: block`，这将强制 Claude 继续工作，直到违规行为被消除。
## 蓝图
在您的 `CLAUDE.md`（或 `ARCHITECTURE.md`、`SPEC.md`、`ROADMAP.md` —— 以最先找到的为准）中添加一个 `## Architecture` 部分。在其中，一个带有围栏的 `archlint` 代码块用于声明您的层级和规则：
```
## Architecture
We follow a layered structure: routes → services → repositories → models.
The UI must never reach into the database directly.
```archlint
layer routes = src/routes/**, src/api/**
layer services = src/services/**
layer repos = src/repos/**
layer models = src/models/**
layer ui = src/ui/**, src/components/**
routes -> services
services -> repos
repos -> models
ui -> services
forbid ui -> repos
forbid ui -> models
forbid routes -> repos
forbid * -> src/legacy/**
```
```
语法（每行一条语句，`#` 开头为注释）：
| 语句 | 含义 |
|-------------------------------------|------------------------------------------------|
| `layer NAME = glob, glob, ...` | 通过一个或多个文件 glob 模式定义层级。 |
| `X -> Y` | 允许 `X` 依赖于 `Y`。 |
| `forbid X -> Y` | 显式禁止（优先于允许规则）。 |
| `forbid * -> path/glob/**` | 任何对 `path/...` 的依赖都被禁止。 |
外部导入（npm 包、pip 包、标准库）将被忽略。
## 安装
将脚本放入您的项目中：
```
mkdir -p .claude/hooks
curl -fsSL https://raw.githubusercontent.com/MKanhan/archlint/main/archlint.py \
-o .claude/hooks/archlint.py
chmod +x .claude/hooks/archlint.py
```
然后将以下内容合并到 `.claude/settings.json` 中：
```
{
"hooks": {
"PostToolUse": [{
"matcher": "Write|Edit|MultiEdit",
"hooks": [{
"type": "command",
"command": "python3 $CLAUDE_PROJECT_DIR/.claude/hooks/archlint.py post"
}]
}],
"Stop": [{
"hooks": [{
"type": "command",
"command": "python3 $CLAUDE_PROJECT_DIR/.claude/hooks/archlint.py stop"
}]
}]
}
}
```
将 `.archlint/` 添加到您的 `.gitignore` 中（这是存储每个回合状态和偏移日志的地方）。
## 在 Claude Code 之外使用
```
# Pre-commit / CI: 扫描整个项目，drift 时 exit 1。
python3 .claude/hooks/archlint.py check
```
将其作为 git 的 pre-commit 钩子接入：
```
# .git/hooks/pre-commit
#!/usr/bin/env bash
python3 .claude/hooks/archlint.py check
```
## 模式
| 环境变量 | 值 | 效果 |
|-----------------------|-------------------------|-----------------------------------------------------------------------------------|
| `ARCHLINT_MODE` | `lenient` (默认), `strict` | `strict` 模式会通过 `decision: block` 阻止 Claude 继续；`lenient` 模式仅发出通知。 |
| `ARCHLINT_BLUEPRINT` | 路径 | 覆盖蓝图的存储位置。 |
| `ARCHLINT_QUIET` | `1` | 抑制非阻塞输出（保留供将来使用）。 |
## 支持的语言
导入提取适用于：Python (AST)、TypeScript/JavaScript (regex)、Go (regex)、Rust (regex)。外部导入和未解析的规范会被直接跳过——对第三方包不会产生误报。
添加一种语言大约只需 15 行代码：一个用于导入提取的正则表达式（或 AST），以及在 `_MODULE_SUFFIXES` 中的几个文件后缀名。
## 尚不支持的功能
- **不会自动生成蓝图。** 您只需编写一次规则。一个明显的下一步是开发配套的 `archlint init` 命令，让 Claude 根据现有目录树起草初始蓝图。
- **不进行深层语义分析。** 它基于导入和 glob 模式工作。它不会捕获“此函数名暗示了层级跨越”——那需要 LLM，而我们更希望将其保持为可选项。
- **不会自动修复问题。** 它只负责暴露偏移；由 Claude 决定如何处理。这是有意为之的设计——我们是安全带，而不是方向盘。
## 为什么是钩子而不是静态分析器
静态分析器在 CI 阶段运行，而那时架构已经发生了偏移。钩子在 *Agent 循环内部* 运行，此时还有低成本纠正路线的机会。其核心目的在于防止偏移在单个回合的 40 次工具调用中不断累积——而不仅仅是在事后进行检测。
这两者都很有价值。`archlint check` 适用于 CI/pre-commit 场景；而钩子适用于实时编码场景。相同的代码，相同的规则。
## 许可证
MIT。
标签：AI编程助手, CI/CD钩子, Claude Code插件, CLAUDE.md, CMS安全, Go, IPv6支持, JavaScript, LLM开发工具, Python, Ruby工具, Rust, stdlib-only, TypeScript, 代码规范, 代码静态分析, 分层架构, 可视化界面, 安全插件, 实时代码审查, 数据可视化, 无后门, 无第三方依赖, 日志审计, 架构漂移检测, 网络流量审计, 自动纠错, 软件架构, 逆向工具, 重构