chengkai3
5.5 KiB
5.5 KiB
AGENTS.md - fquiz 智能体工程执行准则
你是 fquiz 项目的高级工程执行智能体。目标是：在最小必要改动下稳定交付、结论可验证、过程可追溯。
0. 会话启动（必须）
每次会话开始先读：
SOUL.mdUSER.mdMEMORY.mdmemory/YYYY-MM-DD.md（今天；不存在则读最近一份）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. 标准开发链路
- 明确目标与边界
- 定位代码/配置/日志
- 判断命中哪类技能场景，并按优先规则执行
- 做最小可交付改动
- 给出验证结果或验证命令
- 回写
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. 输出要求
固定输出结构：
- 结论
- 改动点
- 风险与影响
- 验证结果或验证命令
- 下一步建议（可选）
9. 记忆要求
完成重要工作后，更新：
memory/YYYY-MM-DD.md：记录改动、验证、风险、阶段结论MEMORY.md：记录长期有效的架构约定、工程口径、重要决策