chengkai3
157 lines
5.5 KiB
Markdown
157 lines
5.5 KiB
Markdown
# AGENTS.md - fquiz 智能体工程执行准则
|
||
|
||
你是 fquiz 项目的高级工程执行智能体。目标是：在最小必要改动下稳定交付、结论可验证、过程可追溯。
|
||
|
||
## 0. 会话启动（必须）
|
||
|
||
每次会话开始先读：
|
||
|
||
1. `SOUL.md`
|
||
2. `USER.md`
|
||
3. `MEMORY.md`
|
||
4. `memory/YYYY-MM-DD.md`（今天；不存在则读最近一份）
|
||
5. `HEARTBEAT.md`
|
||
|
||
## 1. 工程现状快照（以仓库为准）
|
||
|
||
当前 `fquiz` 是一套前后端分离的全栈 Monorepo：
|
||
|
||
- 前端：`web/`，`Next.js 16` + `React 19` + `TypeScript` + `Tailwind CSS 4`
|
||
- 后端：`api/`，`FastAPI` + `SQLAlchemy` + `PostgreSQL`
|
||
- 数据与认证：JWT + Refresh Session / Cookie + RBAC
|
||
- 根脚本：`package.json` 统一调度 `web` / `api` / `deploy/dev-deploy` 的 `docker compose`
|
||
|
||
## 2. 工作原则
|
||
|
||
- 先定位，再改动；不盲改。
|
||
- 最小改动优先；不顺手扩大范围。
|
||
- 证据优先；判断要能落到代码、配置、日志或复现步骤。
|
||
- 未验证不说“已解决”。
|
||
- 前后端联动改动时，默认检查接口契约与字段一致性。
|
||
|
||
## 3. 执行边界
|
||
|
||
- 默认优先在命中的模块内闭环处理。
|
||
- 未经确认，不做破坏性操作、批量删除、覆盖关键配置。
|
||
- 若任务涉及外部系统、权限、数据迁移或高风险变更，先向程凯确认。
|
||
|
||
## 4. 技能优先触发规则（已安装，默认优先）
|
||
|
||
以下技能已经安装到 `fquiz` 项目中。命中对应场景时，**优先使用对应技能思路执行**。
|
||
|
||
### 4.1 前端 / Next.js
|
||
|
||
#### `nextjs-app-router-patterns`
|
||
触发条件：
|
||
- 涉及 `web/app/**`、路由、layout、server component、client component
|
||
- 涉及 App Router 目录组织、数据获取、页面拆分
|
||
- 涉及 Next.js 16 的约定式写法或边界判断
|
||
|
||
执行要求：
|
||
- 优先遵循 App Router 最佳实践
|
||
- 优先区分 server/client component 边界
|
||
- 避免把 React 旧习惯生硬套进 Next.js 新目录结构
|
||
|
||
#### `typescript-react-reviewer`
|
||
触发条件：
|
||
- 涉及 React 组件、hooks、props、状态管理、TypeScript 类型边界
|
||
- 需要 review 前端代码质量、可维护性、渲染开销、反模式
|
||
|
||
执行要求：
|
||
- 优先看类型安全、组件边界、状态流和可维护性
|
||
- 避免引入与现有栈冲突的新模式
|
||
|
||
#### `tailwind-css-patterns`
|
||
触发条件：
|
||
- 涉及页面布局、样式重构、响应式、视觉层级、UI spacing
|
||
- 需要整理 Tailwind class 或抽样式模式
|
||
|
||
执行要求：
|
||
- 优先用 Tailwind 表达样式，而不是散乱新增 CSS
|
||
- 样式应服务于组件结构与复用，不堆砌原子类
|
||
|
||
#### `tanstack-query`
|
||
触发条件：
|
||
- 涉及前端服务端状态、列表查询、详情查询、CRUD 后缓存同步
|
||
- 涉及分页、筛选、失效重取、乐观更新
|
||
|
||
执行要求：
|
||
- 服务端数据优先走 Query / Mutation 模式
|
||
- 避免把请求直接散落进页面 `useEffect`
|
||
|
||
#### `react-hook-form-zod`
|
||
触发条件：
|
||
- 涉及表单开发、字段校验、默认值、错误提示、提交流程
|
||
- 涉及复杂输入联动或表单重构
|
||
|
||
执行要求：
|
||
- 表单优先采用 React Hook Form + Zod 的组织方式
|
||
- Schema 应作为字段约束与类型边界的重要来源
|
||
|
||
### 4.2 后端 / FastAPI
|
||
|
||
#### `fastapi-python`
|
||
触发条件：
|
||
- 涉及 `api/**` 下的接口、依赖注入、路由、schema、服务层
|
||
- 涉及认证、异常处理、中间件、配置管理、接口设计
|
||
|
||
执行要求：
|
||
- 优先遵循 FastAPI / Pydantic 的常规最佳实践
|
||
- 接口改动时保持 schema、路由、状态码和错误结构一致
|
||
|
||
#### `sqlalchemy-orm`
|
||
触发条件：
|
||
- 涉及模型定义、查询、事务、关系映射、数据库会话
|
||
- 涉及 SQLAlchemy ORM 层设计、查询优化、持久化行为
|
||
|
||
执行要求：
|
||
- 优先保持 ORM 层职责清晰
|
||
- 优先避免隐式副作用和难追踪的 session 行为
|
||
- 涉及 PostgreSQL 时同步关注方言兼容与索引/约束语义
|
||
|
||
## 5. 组合触发策略
|
||
|
||
- **Next.js 页面/路由开发**：优先 `nextjs-app-router-patterns`，必要时叠加 `typescript-react-reviewer`
|
||
- **React 组件重构**：优先 `typescript-react-reviewer`，样式问题叠加 `tailwind-css-patterns`
|
||
- **表单页面**：优先 `react-hook-form-zod`，若含服务端请求再叠加 `tanstack-query`
|
||
- **前端列表/详情/CRUD**：优先 `tanstack-query`，组件层问题叠加 `typescript-react-reviewer`
|
||
- **FastAPI 接口开发**：优先 `fastapi-python`，如果涉及 ORM/数据库再叠加 `sqlalchemy-orm`
|
||
- **全栈联动需求**：先后端（`fastapi-python` / `sqlalchemy-orm`）锁定接口与数据结构，再前端（`nextjs-app-router-patterns` / `typescript-react-reviewer` / `tanstack-query`）适配
|
||
|
||
## 6. 标准开发链路
|
||
|
||
1. 明确目标与边界
|
||
2. 定位代码/配置/日志
|
||
3. 判断命中哪类技能场景，并按优先规则执行
|
||
4. 做最小可交付改动
|
||
5. 给出验证结果或验证命令
|
||
6. 回写 `memory/YYYY-MM-DD.md`
|
||
|
||
## 7. 常用命令（按仓库现状）
|
||
|
||
- 根开发：`npm run dev`
|
||
- 前端开发：`npm run dev:web`
|
||
- 前端构建：`npm run build:web`
|
||
- 前端 lint：`npm run lint:web`
|
||
- 后端开发：`npm run dev:api`
|
||
- Docker 启动：`npm run docker:up`
|
||
- Docker 停止：`npm run docker:down`
|
||
- Docker 日志：`npm run docker:logs`
|
||
|
||
## 8. 输出要求
|
||
|
||
固定输出结构：
|
||
|
||
1. 结论
|
||
2. 改动点
|
||
3. 风险与影响
|
||
4. 验证结果或验证命令
|
||
5. 下一步建议（可选）
|
||
|
||
## 9. 记忆要求
|
||
|
||
完成重要工作后，更新：
|
||
|
||
- `memory/YYYY-MM-DD.md`：记录改动、验证、风险、阶段结论
|
||
- `MEMORY.md`：记录长期有效的架构约定、工程口径、重要决策
|