AI 编程开发思维
一、核心理念
你想得越清楚，AI 做得越准确；你越模糊，它越跑偏。瓶颈不在 AI 能力，而在你的思考质量。
1.1 分工原则
| 层级 | 责任人 | 内容 |
|---|---|---|
| 第一层 | 必须你做 | 产品边界、架构决策、技术取舍、跨模块一致性 |
| 第二层 | AI 做你验收 | 业务代码、接口开发、前端页面、测试用例、文档 |
| 第三层 | AI 全权处理 | 格式化、样板代码、简单重构、启动脚本 |
1.2 验收三步法
- 查意图：做的是否是要求的功能？
- 查质量：风格、规范、一致性是否符合项目整体？
- 查边界：错误处理、异常、潜在风险是否覆盖？
关键模块强制跑测试再接收，别光靠肉眼。
1.3 防偏离策略：规范驱动开发
定规范 → AI 执行 → 人验收 → 迭代规范
规范制定要点：
- 具体：AI 看到规范后无需猜测
- 有优先级：AI 反复跑偏的地方写细，不偏的地方不写
- 带原因：告诉 AI 为什么，而不只是规则
规范分层：
- 全局规范（CLAUDE.md）：命名规则、接口格式、错误码、设计原则
- 模块规范：模块目录下定义，开发前单独约定
- 任务规范：每次任务的补充说明，临时性
示例规范：
- 命名：字段小驼峰
- 返回格式：统一
{ code, message, data } - 设计原则：不过度抽象，一层能解决不拆两层；不引入技术栈外依赖
二、项目启动流程
2.1 产品需求分析
梳理核心功能：
帮我梳理【产品名】的核心功能模块，按类别分组，每个模块用一两句话说明。
功能取舍：
我要基于【产品】做简化版。约束：一个人开发，20-50 人使用，本地部署。
请从功能列表中判断哪些是核心必须做，哪些可以砍掉，给出理由。
2.2 技术选型
评估维度： 开发效率、生态成熟度、AI SDK 支持、运维复杂度
示例技术栈：
- 后端：Gin + Gorm + MySQL 8.x + Redis 7.x
- 前端：React 19 + TypeScript + Antd
- 容器化：Docker + Docker Compose
2.3 写 CLAUDE.md
产品定义、功能范围、技术选型、运维预期，全部落成文档。
根据讨论，帮我把项目概述写进 CLAUDE.md，包括：
- 产品定位
- 做什么 / 不做什么
- 技术栈
- 部署与运维预期
三、架构设计
3.1 应用架构
推荐：模块化单体
- 一期：单模块开发，50 人使用
- 后续：可平滑扩展到数千人
模块示例：
common：公共模块- 业务模块：按功能领域划分
依赖原则： 单向依赖，禁止循环
3.2 代码组织规范
分层结构（每个模块统一）：
module/
├── controller/ # 参数校验、调用 Service
├── service/ # 业务逻辑、事务管理
└── ...
分层规则：
- Controller：只做参数校验和调用 Service，不写业务逻辑
- Service：处理所有业务逻辑，包括事务
3.3 外部调用设计
针对 LLM API（OpenAI、Claude、Gemini、Ollama）等慢且不稳定的外部调用：
需考虑的维度：
- 线程管理
- 容错机制
- 超时控制
- 重试策略
四、数据库规范
4.1 通用字段
| 字段 | 类型 | 说明 |
|---|---|---|
| id | BIGINT | 自增主键，禁止 UUID |
| created_at | DATETIME(3) | 创建时间 |
| updated_at | DATETIME(3) | 更新时间 |
| deleted | TINYINT(1) | 逻辑删除 |
其他约定：
- 禁止 NULL，空值用空字符串或 0
- 枚举用 VARCHAR(32)，不用 MySQL ENUM
4.2 索引规则
- 命名：
idx_{表名}_{字段名} - 逻辑删除字段必须加进组合索引
- 组合索引：等值列在前，范围列在后
- 多对多关联表：两个方向都要索引
- 唯一约束用
UNIQUE INDEX，不只在代码层校验 - 禁止在 TEXT/BLOB 字段建索引
- 不建数据库级外键约束，应用层维护
4.3 分页规则
- 默认：游标分页（
WHERE id < lastId ORDER BY id DESC LIMIT N） - OFFSET 分页：限制最大 10000 条
- COUNT：只在第一页查，翻页不重复查
4.4 大表预判
| 表名 | 特点 | 索引建议 |
|---|---|---|
| message | 增长最快 | (conversation_id, created_at) |
| document_chunk | 向量数据 | MySQL 只存元数据，向量存 pgvector |
pgvector 规范：
- 维度固定 1536
- 必须建 HNSW 索引
- 检索必须加 LIMIT，禁止全量排序
五、部署与运维
5.1 部署架构
生产环境：Docker + K8s
- 前端：Nginx 托管静态文件 + API 反向代理（
proxy_buffering off） - 后端：Gin，K8s Deployment（一期单副本）
- 数据库：MySQL 8.x（外部服务）
- 缓存：Redis 7.x（外部服务）
- 向量库：PostgreSQL + pgvector
5.2 缓存策略
| 数据类型 | 存储 | TTL |
|---|---|---|
| 对话上下文 | Redis | 2h |
| 对话消息 | 不缓存，走数据库 | - |
| 知识库文档 | 不缓存，走数据库 | - |
| LLM 响应 | 不缓存 | - |
5.3 运维预判
- QPS 估算
- 性能瓶颈预判
- 扩展路径规划
