python-vibe-coding-rules 是一份面向 Python 项目的智能体规则文件（AGENTS.md），用于在 Vibe Coding 场景下约束 AI 编码助手的代码生成、修改、测试与交付行为。规则默认基于 FastAPI + Tortoise ORM + LangChain 技术栈，可直接放入项目根目录，供 Cursor、Claude Code 等支持 AGENTS.md 规范的编码助手读取并遵循。
AGENTS.md 是一个约定文件——放在项目根目录后，支持该规范的 AI 编码助手会自动读取并在生成、修改、测试代码时遵循其中的约束。本仓库提供的 AGENTS.md 面向 Python 后端与智能体开发，覆盖从核心原则到交付的全流程规范。
- 使用 AI 编码助手（Cursor、Claude Code、Windsurf 等）进行 Python 后端开发
- 技术栈基于 FastAPI、Tortoise ORM、LangChain / LangGraph / Deep Agents
- 希望统一团队或个人的 AI 生成代码风格与质量底线
- 需要 AI 助手在修改代码时控制修改范围、保证数据一致性与安全性
- 将本仓库的
AGENTS.md复制到你的 Python 项目根目录。 - 用 Cursor / Claude Code 等支持 AGENTS.md 规范的助手打开该项目。
- 助手会自动读取并在后续编码中遵循规则。
# 复制到你的项目根目录
cp AGENTS.md /path/to/your-python-project/如果你的项目已有 AGENTS.md，按需合并而非整体覆盖。
AGENTS.md 包含 7 个部分：
- 核心原则 — 需求优先、稳定性与安全性、可维护性、控制修改范围；优先简单成熟方案，反对过度设计与盲目执行。
- 默认技术栈 — FastAPI + Tortoise ORM +
BaseSettings配置 + 标准logging；智能体框架按需选用 LangChain / LangGraph / Deep Agents。 - Python 编码规范 — 遵循 PEP 8、类型注解、优先标准库、异步不阻塞、资源正确释放、异常不静默吞掉。
- 架构与职责 — api / service / repository / models / schemas / infrastructure / config 分层，接口层不堆业务逻辑，数据层不载业务规则。
- 数据库与中间件 — 事务边界明确、避免 N+1、连接复用、按场景选型 Redis / 消息队列 / 搜索 / 对象存储。
- 智能体开发 — 先判断是否需要智能体框架；工具接口有超时重试；循环设最大步数防失控；高风险操作加人工确认。
- 修改、测试与交付 — 只改相关代码、不破坏现有接口、跑相关测试、交付说明含影响范围与未验证风险。
规则文件约定的默认技术栈：
| 用途 | 选型 |
|---|---|
| Web 框架 | FastAPI |
| ORM | Tortoise ORM |
| 配置管理 | pydantic BaseSettings + .env |
| 日志 | Python 标准库 logging + RotatingFileHandler |
| 智能体框架 | LangChain / LangGraph / Deep Agents（按需） |
这些是规则推荐的约定，不是本仓库的可运行依赖。在你的项目中可按现有技术栈调整。
规则建议的项目分层（仅约束，不强制为简单功能建无意义目录）：
api/controller # 请求解析、基础校验、依赖注入、响应转换
service # 业务流程与业务规则
repository/dao # 数据库访问和持久化细节
models # Tortoise ORM 数据模型
schemas # 请求、响应及内部数据结构
infrastructure # Redis、消息队列、对象存储和外部服务
config/settings # 配置加载、环境变量和多环境配置
logging_config # 日志初始化、格式、级别和输出
common/utils # 具有明确复用价值的通用能力
欢迎提 Issue 和 PR。较大改动请先开 Issue 说明动机与影响范围，详见 CONTRIBUTING.md。
MIT — 见 LICENSE。