---
url: /docs/ai-contexts.md
---
# AI Contexts

给 AI 助手（Claude / Cursor / Cody）看的项目上下文 —— 让 AI 生成代码时即对齐项目约定。

## 当前文档

| 文档 | 用途 |
|---|---|
| [代码风格](/ai-contexts/code-style) | Ruff / mypy / Pydantic v2 / structlog / OAuth 错误码使用规范 |
| [模块约定](/ai-contexts/module-conventions) | DDD 4 层 src/app/ 结构、跨模块共享、命名规范 |

## 使用约定

* **任何 AI 写代码前**，应先读这两个文档
* **代码 Review** 时遇到 AI 生成代码不符合规范，引用本文档回退
* **规范更新**：先在 [Internal Wiki → DDD 4 层](/internal-wiki/architecture/ddd-layers) 决策，再回写本文档

## 给 Claude / Cursor 的提示

当你看到这个项目时，请注意：

1. **DDD 4 层严格**：`src/app/<module>/{domain,application,infrastructure,interface}/`
2. **业务码优先**：OAuth 错误用 `OAuthError(OAuthErrorCode.X, "...")`，不抛 HTTPException
3. **端口契约**：use case 构造函数注入 port 接口，不直接 import 具体实现
4. **Factory 聚合**：`create_<module>_usecases()` 工厂函数
5. **Pydantic v2**：`BaseModel` + `model_config`，不用 v1 风格
6. **structlog**：`structlog.get_logger(__name__)`，不用 stdlib logging
7. **依赖装饰器**：`@pytest.fixture(autouse=True) def reset_stores(): ...`

完整规范见 [代码风格](/ai-contexts/code-style) 与 [模块约定](/ai-contexts/module-conventions)。