agent | codex 最佳实践方案（自动化流程）

前言

先上图

一、需求配置

1.AGENTS.md

约束项目开发行为

个人习惯用FastApi写后端应用了，真的快，后期写多agent也是。

# AGENTS.md

## 项目说明

这是一个前后端分离项目，当前仓库公开部分以后端为主。
后端基于 FastAPI，采用分层结构开发。
当前核心能力包括：

- AI 商品信息生成
- 文本翻译
- 图片 OCR

## 后端目录约定

- `app/main.py`：应用入口、路由注册、中间件
- `app/routes/`：接口层，只负责接收参数、调用 service、返回结果
- `app/services/`：业务逻辑与流程编排
- `app/schemas/`：请求/响应结构定义
- `app/models/`：数据库 ORM 模型
- `app/database.py`：数据库连接与 Session 管理
- `app/config.py`：配置、日志
- `app/utils/`：公共工具
- `app/sql/`：SQL 相关资源
- `app/test_api/`：接口测试或调试相关内容

## Python 环境与依赖管理

- 使用 `uv` 管理虚拟环境与依赖
- 虚拟环境目录统一使用 `.venv`
- 创建虚拟环境：`uv venv .venv`
- 安装依赖：`uv sync`
- 运行 Python 命令优先使用 `uv run ...`
- 除非任务明确要求，否则不要手动切换为其他包管理方式

## 常用命令

- 创建虚拟环境：`uv venv .venv`
- 安装依赖：`uv sync`
- 启动后端：`uv run uvicorn app.main:app --reload`
- 运行测试：`uv run pytest`
- 修改代码后，优先运行与改动最相关的最小测试集
- 完成前，报告实际运行过的命令和结果

## 后端开发规则

1. route 层保持轻量

- 不要在 `routes` 中写复杂业务逻辑
- route 只负责参数接收、基本校验、调用 service、返回响应

2. service 层承载核心流程

- 多步骤逻辑、AI 调用流程、数据库写入编排，都放到 `services`
- 不要把“参数解析 + AI 处理 + DB 写入 + 响应组装”塞进一个函数

3. schema / model 分离

- `schemas` 负责 API 输入输出结构
- `models` 负责数据库表映射
- 修改接口字段时，同步更新 schema
- 不要把 ORM 模型直接当接口返回结构乱用

4. database / config 统一入口

- 数据库访问统一走 `app/database.py`
- 配置、日志统一走 `app/config.py`
- 不要在业务代码里硬编码密钥、URL、环境值

## AI 流程规则

对于商品生成类接口，默认把流程拆成以下几个阶段：

1. 请求解析
2. 源数据获取或预处理
3. 类目识别 / embedding 匹配
4. LLM 生成标题、描述、属性
5. 结果持久化
6. 任务状态更新
7. 可选回调通知

修改 AI 相关接口时，优先保持这些阶段解耦，不要全部堆到 route 中。

## 前端联调规则

虽然当前仓库公开部分以后端为主，但如果任务涉及前端联调，请遵循以下约束：

1. 前端负责展示与交互

- 页面展示、表单输入、状态呈现、请求调用属于前端职责
- 不要把复杂业务判断硬编码到前端页面里

2. 接口变更必须同步

- 后端请求参数变更时，同步检查前端调用参数
- 后端响应字段变更时，同步检查前端类型、渲染和状态处理
- 不要让前端自行猜测字段含义

3. 异步任务要可追踪

- 若接口返回 `task_id` 或存在轮询 / 回调流程，前端必须有 loading、processing、success、error 等状态展示
- 状态流转变更时，前后端一起检查

## 改动原则

- 优先最小改动，不做无关重构
- 优先复用现有结构和已有模块
- 不要随意修改 public API 字段名
- 不要随意修改数据库字段名
- 不要随意新增依赖
- 改接口时默认检查 route / service / schema / model / 前端调用层 是否一致

## 禁止事项

- 不要修改 `.env`、密钥、生产配置，除非任务明确要求
- 不要随意改部署脚本
- 不要在 `routes` 中堆积大段业务代码
- 不要为了小需求重构整个模块

## 输出要求

完成任务时，请说明：

1. 修改了哪些文件
2. 每个文件为什么改
3. 是否影响接口结构
4. 是否影响前端联调
5. 风险点和注意事项

## 完成标准

只有同时满足以下条件，任务才算完成：

- 改动符合现有分层结构
- 接口行为清晰且可解释
- schema / service / route / model 保持一致
- 若涉及前端，联调影响已说明
- 改动可 review，可验证

2.config

在实际配置中，config.toml 一般分为两个层次。用户级配置文件位于 ~/.codex/config.toml，用于存放个人长期默认偏好，例如默认模型、默认审批策略、默认沙箱模式以及常用 profile 等。

model = "gpt-5.3-codex"
approval_policy = "never"
sandbox_mode = "workspace-write"
model_reasoning_effort = "medium"
plan_mode_reasoning_effort = "high"
web_search = "cached"
profile = "safe"

[sandbox_workspace_write]
network_access = false

[profiles.safe]
model = "gpt-5.3-codex"
approval_policy = "never"
sandbox_mode = "workspace-write"
model_reasoning_effort = "medium"
plan_mode_reasoning_effort = "high"
web_search = "cached"

[profiles.safe.sandbox_workspace_write]
network_access = false

[profiles.research]
model = "gpt-5.3-codex"
approval_policy = "on-request"
sandbox_mode = "workspace-write"
model_reasoning_effort = "medium"
plan_mode_reasoning_effort = "high"
web_search = "live"

[profiles.research.sandbox_workspace_write]
network_access = true

[windows]
sandbox = "elevated"

[projects.'\\?\F:\AI_Models\DEMO\Study_Demo\ai_list_generate']
trust_level = "trusted"

[notice.model_migrations]
"gpt-5.3-codex" = "gpt-5.4"

项目级配置文件位于 项目根/.codex/config.toml，用于描述当前仓库的特殊需求，例如该项目是否允许联网、是否需要更高频的在线搜索、是否应采用只读模式等。

approval_policy = "never"
sandbox_mode = "workspace-write"
web_search = "live"

[sandbox_workspace_write]
network_access = true

3.提示词

解析提示词

先阅读当前仓库、README 和 AGENTS.md，不要改代码。
请告诉我：
1. 这个项目的整体分层结构
2. 入口文件和核心调用链
3. 主要业务流程分别落在哪些目录和文件
4. 如果我接下来要修改某个功能，优先应该看哪些文件
最后给我一个最小阅读路径。

检查bug提示词

先阅读当前仓库、README 和 AGENTS.md，不要改代码。
请帮我检查这次改动或当前代码链路中的潜在 bug。

重点关注：
- route / service / schema / model 是否一致
- 是否有明显逻辑错误
- 是否有空值、边界条件、异常处理遗漏
- 是否存在接口返回结构不一致
- 是否有容易在运行时报错的地方

请按“文件 -> 问题 -> 原因 -> 风险 -> 建议修复”输出。
如果问题较多，请先按严重程度排序。

新增功能提示词

先阅读当前仓库、README 和 AGENTS.md，不要直接改代码。

Goal:
新增 xxx 功能。

Context:
这是一个 FastAPI 分层项目。
请先分析这个功能应该落在哪一层：
- route：参数接收与响应返回
- service：业务流程
- schema：请求/响应结构
- model：数据持久化
如果涉及前端联调，也请说明输入输出字段变化。

Constraints:
遵循 AGENTS.md。
保持 route 轻量，复杂逻辑放 service。
不要把参数解析、业务编排、数据库写入、响应拼装堆到一个函数里。
优先复用现有模块和模式。
不要做无关重构。

Done when:
1. 功能按现有分层完成
2. route / service / schema / model 保持一致
3. 如涉及前端，联调影响已说明
4. 给出最小验证方案
5. 列出修改文件和风险点