NathanKrupa/gaudi
GitHub: NathanKrupa/gaudi
Gaudi 是一个为 AI 辅助开发设计的 Python 项目架构代码检查工具，通过结构化错误提前发现设计缺陷并降低技术债务。
Stars: 1 | Forks: 0
# Gaudi
**不只是结构稳固，更要美。**
Gaudi 是一个 Python 项目的架构代码检查工具。它会检查项目的结构设计，并生成机器可读的错误代码，供 AI 编码代理（如 Claude、GitHub Copilot 等）理解和执行。
风格检查器捕捉语法错误。安全扫描器捕捉漏洞。**Gaudi 捕捉架构错误**——这些错误会在你达到 1 万用户时导致数月的重构成本。
## 它能做什么
```
$ gaudi check .
ARCH-001 [ERROR] models.py:14 - Multi-tenant table 'donors' has no tenant isolation column
-> Add a `tenant_id` ForeignKey and enforce row-level filtering on all queries.
IDX-001 [WARN] models.py:28 - Column 'email' is used in filter queries but has no db_index
-> Add db_index=True or create a composite index.
SCHEMA-001 [INFO] models.py:45 - Model 'Donor' has no timestamp fields (created_at, updated_at)
-> Add created_at and updated_at DateTimeField columns for debugging and auditing.
Found 1 error, 1 warning, 1 info across 3 files.
```
## 为何存在 Gaudi
AI 编码代理正在编写越来越多的代码。它们擅长实现功能，但不擅长问：“*这样设计合理吗？*”
Gaudi 是纪律层。它将架构最佳实践编码为结构化的错误代码，任何 AI 代理都能解析、理解并解决——没有歧义，没有幻觉。
**对人类：** 在变成技术债务之前发现设计错误。
**对 AI 代理：** 获取结构化的、可操作的架构指导，而不是模糊的“最佳实践”提示。
## 安装
```
pip install gaudi-linter
```
## 快速开始
```
# 检查项目目录
gaudi check .
# 输出为 JSON（供 AI 代理使用）
gaudi check . --format json
# 输出为 GitHub Actions 注释（在 PR 中内联）
gaudi check . --format github
# 仅错误
gaudi check . --severity error --exit-code
# 检查特定文件
gaudi check models.py
# 生成可粘贴到与 LLM 聊天中的 Markdown 报告
gaudi report . --output gaudi-report.md
```
## LLM 协作式工作流
Gaudi 被设计为开发者 ↔ LLM 对话的开局步骤，
而不是一堆机械的自动修复。大多数规则都是判断性决策——
*正确的*处理方式取决于周围代码和项目优先级。
两个输出让这种对话更容易开始：
- **`gaudi check --format github`** 会输出
[GitHub Actions 工作流命令](https://docs.github.com/en/actions/using-workflows/workflow-commands-for-github-actions#setting-an-error-message)
让结果在拉取请求中内联显示，精确地呈现在
审查者（以及 Copilot/Claude PR 审查者）期望看到的位置。参见
[docs/llm-workflow.md](docs/llm-workflow.md) 了解示例工作流。
- **`gaudi report .`** 会生成一个按文件分组的 Markdown 报告。每个发现都包含代码片段、规则建议，以及一段预先写好的
“与 LLM 讨论”提示，开发者可以直接粘贴到 Claude、ChatGPT 或其他助手中使用。
## 它检查什么
Gaudi 使用深度 AST 分析来检查 Django 模型、SQLAlchemy 表、FastAPI 端点、Flask 应用、Celery 任务、Pandas 操作、Pydantic 模型、pytest 固件以及 DRF 视图。
### 规则类别
| 前缀 | 类别 | 示例 |
|--------|----------|----------|
| `ARCH` | 架构 | 租户隔离、神模型、可空外键蔓延 |
| `IDX` | 索引 | 查找/过滤字段缺少索引 |
| `SCHEMA` | 架构设计 | 缺少时间戳、列膨胀、类型选择 |
| `SEC` | 安全 | 硬编码密钥、缺少权限、不安全默认值 |
| `SCALE` | 可扩展性 | N+1 查询、缺少超时、iterrows() |
| `STRUCT` | 结构 | 文件臃肿、缺少应用工厂 |
### 库特定规则
| 前缀 | 库 | 规则 |
|--------|---------|-------|
| `DJ` | Django | 密钥泄露、DEBUG=True、臃肿的视图 |
| `FAPI` | FastAPI | 缺少 response_model、同步端点 |
| `SA` | SQLAlchemy | 会话泄漏、默认延迟加载 |
| `FLASK` | Flask | 模块级应用创建 |
| `CELERY` | Celery |缺少重试、缺少超时限制 |
| `PD` | Pandas | inplace=True、iterrows() |
| `HTTP` | Requests/HTTPX | 缺少超时、无重试逻辑 |
| `PYD` | Pydantic | 可变默认值 |
| `TEST` | pytest | 复杂的断言、昂贵的固件 |
| `DRF` | Django REST Framework | 缺少权限、无节流 |
| `PY314` | Python 3.14 | 移除的 API、已弃用的模块 |
## 错误代码格式
每个发现都遵循一致的架构：
```
{
"code": "ARCH-001",
"severity": "error",
"category": "architecture",
"file": "models.py",
"line": 14,
"message": "Multi-tenant table 'donors' has no tenant isolation column",
"recommendation": "Add a `tenant_id` ForeignKey and enforce row-level filtering."
}
```
## 编写自定义规则
```
from gaudi import Rule, Severity, Category
class CheckTenantIsolation(Rule):
code = "ARCH-001"
severity = Severity.ERROR
category = Category.ARCHITECTURE
message_template = "Multi-tenant table '{table}' has no tenant isolation column"
def check(self, context):
for model in context.models:
if not model.has_column("tenant_id"):
yield self.finding(
file=model.source_file,
line=model.source_line,
table=model.name,
)
```
## AI 代理集成
Gaudi 的 JSON 输出专为 AI 编码代理设计。你可以将其集成到 Claude Code 工作流、CI 流水线或自定义代理循环中。
```
# 在 CI 中使用
gaudi check . --format json --severity error --exit-code
# 在 pre-commit 钩子中使用
gaudi check . --severity error --exit-code
```
### AI 代理的提示片段
在你的系统提示或项目说明中包含以下内容：
```
Before implementing any database schema changes, run `gaudi check .` and resolve
all ERROR-level findings. WARN-level findings should be addressed unless you can
document a specific reason to override them.
```
## 配置
在项目根目录创建 `gaudi.toml`：
```
[gaudi]
severity = "warn" # minimum severity to report
exclude = ["migrations/"] # paths to skip
[gaudi.rules]
"ARCH-001" = "error" # override severity
"IDX-003" = "off" # disable a rule entirely
[philosophy]
school = "convention" # infer with: gaudi philosophy .
```
### 行内抑制
使用 `# noqa` 在单行抑制发现：
```
SECRET_KEY = "test-only" # noqa: DJ-SEC-001
urlpatterns = [...] # noqa
```
`# noqa`（单独使用）会抑制该行所有发现。`# noqa: CODE1, CODE2` 仅抑制列出的规则。
### 规则速查表
从实时注册表生成每行一条规则的 Markdown 文件，适合
用于 `@` 引用 `CLAUDE.md` 或任何其他 AI 代理说明文件：
```
# 打印到标准输出
gaudi cheat-sheet
# 写入文件（已提交的工件）
gaudi cheat-sheet -o docs/gaudi-rules.md
# CI 漂移防护：如果文件过期则退出 1
gaudi cheat-sheet --check -o docs/gaudi-rules.md
```
已提交的文档 [`docs/gaudi-rules.md`](docs/gaudi-rules.md)
由规则 `recommendation_template` 字段生成，不会漂移。
### 哲学推断
Gaudi 可以推荐最适合你项目的架构学派：
```
gaudi philosophy .
```
它会分析你的依赖和项目结构，建议一个学派（例如：Django 项目推荐 `convention`，NumPy 流水线推荐 `data-oriented`）。
## 已知限制（v0.1 Alpha）
- 某些库特定规则使用原始文本正则表达式而非完整 AST 分析，可能产生误报。
这些记录在 [问题追踪器](https://github.com/NathanKrupa/gaudi/issues)。
## 哲学
Gaudi 以建筑师 Antoni Gaudi 命名，他是圣家堂的建筑师。他使用悬挂链模型——倒置的悬链线拱——在铺设第一块石头之前测试结构完整性。他的杰作于 1882 年开工，至今仍在遵循他的结构原则。
这个工具体现了同样的哲学：**在构建之前验证架构**。越早发现结构缺陷，修复成本越低。而且随着 AI 代理编写越来越多的大型代码库，我们比以往更需要自动化的架构纪律。
首先由三项支柱（真实性、经济性、成本诚实）中的十四条声明所约束的 Gaudi——详见 [docs/principles.md](https://github.com/NathanKrupa/gaudi/blob/main/docs/principles.md)。它们旨在是可移植的：任何项目都可以将其作为设计决策所依赖的教义采用。
## 贡献
欢迎贡献。目前最高影响力的贡献包括：
1. **新规则**——尤其是 Django、FastAPI 和 SQLAlchemy 模式。
2. **代码异味检测**——以编程方式实现 Fowler 的 24 种代码异味。
3. **CI/CD 集成示例**——GitHub Actions、GitLab CI 等。
参见 [CONTRIBUTING.md](https://github.com/NathanKrupa/gaudi/blob/main/CONTRIBUTING.md) 获取详情。
## 许可证
MIT 许可证。参见 [LICENSE](https://github.com/NathanKrupa/gaudi/blob/main/LICENSE) 获取详细信息。
*由 [Nathan Krupa](https://thealmoner.com) 构建——筹款人、作家和勉强的建筑师。*
标签：AI, AI 辅助开发, GitHub Actions, Homebrew安装, Linter, LNA, pptx, Python 静态分析, SEO: AI 编码助手, SEO: Python 架构, SEO: 代码质量工具, SEO: 架构检查器, 代码审查工具, 安全规则引擎, 技术债务, 数据库设计, 时间戳字段, 机器学习辅助编程, 架构最佳实践, 架构检查, 架构规范, 索引优化, 结构化错误码, 自动化代码审查, 自动笔记, 逆向工具