1. 引言AI编程助手的新范式在当今快速发展的软件开发领域AI编程工具已经从简单的代码补全助手演变为能够深度理解项目上下文、参与架构设计、甚至自主完成复杂任务的智能伙伴。要让AI真正成为团队的一员而不是一个临时访客我们需要为它准备一份完整的入职手册——一套系统化的项目文档体系。本文将详细介绍如何为AI编程助手准备入职材料特别是针对历史项目的文档生成流程让AI能够快速理解项目全貌成为高效的开发协作者。2.4 设计文档AI的施工图纸与项目约束前置设计文档不仅仅是走流程的形式主义而是AI能够理解并执行的施工图纸。AI最大的问题在于不知道项目的具体约束条件如果不明确告知它会按照最通用的方式编写代码这往往与项目的实际需求不符。设计文档的核心价值将项目约束前置到设计阶段让AI在编码时直接遵守这些约束而不是事后修正。为什么项目约束对AI至关重要技术栈约束指定必须使用的框架、库、版本❌ AI默认选择最新、最流行的技术栈✅ 项目实际可能受限于遗留系统、团队技能、性能要求架构约束定义系统边界、通信协议、数据流向❌ AI默认设计理想化的微服务或单体架构✅ 项目实际混合架构、特定集成模式、性能瓶颈考虑业务规则约束明确业务逻辑、验证规则、状态流转❌ AI默认实现通用的CRUD操作✅ 项目实际复杂的业务规则、合规要求、审计追踪性能约束响应时间、吞吐量、资源限制❌ AI默认优化理论最优解✅ 项目实际硬件限制、成本考虑、用户体验要求如何为AI编写有效的设计文档实体设计优先原则先定义数据模型再设计接口在API设计过程中一个常见的错误是先设计接口再考虑数据模型。这会导致接口与业务实体脱节产生不一致的数据结构和冗余的转换逻辑。正确的做法是实体设计必须优先于接口设计原因如下业务一致性实体反映了核心业务概念接口只是访问这些实体的方式数据完整性先定义实体可以确保数据验证规则的一致性可维护性实体变更时所有相关接口可以统一调整AI理解AI需要先理解是什么实体再理解怎么做接口错误做法 vs 正确做法❌ 错误做法先设计接口# 用户管理API设计接口先行 ## 接口定义 ### POST /api/register 请求体 json { name: string, email: string, password: string }GET /api/user/{id}响应{user_id:1,user_name:张三,user_email:zhangsanexample.com}PUT /api/profile/{id}请求体{nickname:string,avatar_url:string}问题字段命名不一致namevsuser_name结构分散用户信息分散在多个接口中缺乏统一的数据模型**✅ 正确做法先设计实体** markdown # 用户管理模块设计实体先行 ## 1. 实体定义核心 java // User.java - 核心用户实体 public class User { private Long id; // 用户ID private String username; // 用户名唯一 private String email; // 邮箱唯一 private String passwordHash; // 密码哈希 private UserProfile profile; // 用户资料 private ListRole roles; // 角色列表 private LocalDateTime createdAt; // 创建时间 private LocalDateTime updatedAt; // 更新时间 } // UserProfile.java - 用户资料实体 public class UserProfile { private String nickname; // 昵称 private String avatarUrl; // 头像URL private String bio; // 个人简介 private LocalDate birthday; // 生日 }2. 值对象定义// Email.java - 邮箱值对象publicclassEmail{privatefinalStringvalue;publicEmail(Stringvalue){validateEmail(value);this.valuevalue;}privatevoidvalidateEmail(Stringemail){// 邮箱格式验证逻辑}}// Password.java - 密码值对象publicclassPassword{privatefinalStringhash;publicPassword(StringplainPassword){validateStrength(plainPassword);this.hashhashPassword(plainPassword);}}3. 接口设计基于实体用户注册接口PostMapping(/api/users)publicResponseEntityUserResponseregister(RequestBodyValidCreateUserRequestrequest){// 基于User实体创建用户}// 请求体与User实体保持一致publicclassCreateUserRequest{NotBlankprivateStringusername;EmailprivateStringemail;Size(min8)privateStringpassword;privateUserProfileRequestprofile;// 与UserProfile实体对应}用户查询接口GetMapping(/api/users/{id})publicResponseEntityUserResponsegetUser(PathVariableLongid){// 返回完整的User实体信息}// 响应体与User实体保持一致publicclassUserResponse{privateLongid;privateStringusername;privateStringemail;privateUserProfileResponseprofile;privateListRoleResponseroles;privateLocalDateTimecreatedAt;}4. 设计约束必须遵守实体优先所有接口设计必须基于已定义的实体命名一致接口字段名必须与实体属性名保持一致结构映射请求/响应体必须是实体的子集或投影验证统一数据验证规则在实体层定义接口层复用转换透明实体到DTO的转换必须明确且可追溯5. AI编码指导实现任何接口前先确认对应的实体模型已明确定义当需要新增字段时先在实体层添加再同步到相关接口避免在接口层定义业务逻辑所有业务规则应在实体或服务层处理保持实体与数据库模型的映射关系清晰一致##### 实体优先设计的优势 1. **减少认知负担**AI只需理解一次实体结构就能推导出所有相关接口 2. **提高一致性**所有接口共享相同的实体定义避免字段命名冲突 3. **便于重构**实体变更时AI可以自动识别所有需要更新的接口 4. **更好的测试**基于实体的测试用例可以覆盖所有使用场景 5. **文档生成**从实体自动生成API文档保持文档与代码同步 ##### 实施建议 1. **在项目初期**先定义核心领域实体User、Order、Product等 2. **设计接口时**每个接口必须明确说明它操作哪个实体 3. **代码审查时**检查接口是否遵循实体定义 4. **文档编写时**先写实体文档再写接口文档 5. **AI协作时**提供完整的实体定义作为上下文再要求实现接口 **记住**实体是业务的基石接口只是访问这些基石的门户。先打好地基实体设计再建门户接口设计才能构建稳定、可维护的系统架构。 **示例用户注册功能的设计约束** markdown # 用户注册功能设计文档 ## 项目约束必须遵守 ### 技术栈约束 - **后端框架**: Spring Boot 2.7.x不得使用3.x - **数据库**: MySQL 8.0必须使用JPA而非原生SQL - **缓存**: Redis 6.x所有用户会话必须缓存 - **安全**: 必须使用Spring Security密码必须bcrypt加密 ### 架构约束 - **服务边界**: 认证服务独立部署不得与其他业务逻辑耦合 - **API设计**: RESTful风格必须遵循公司API规范v2 - **数据流向**: 用户数据必须经过数据清洗服务再入库 - **错误处理**: 统一使用GlobalExceptionHandler不得自定义异常处理 ### 业务规则约束 - **密码强度**: 至少8位包含大小写字母和数字 - **邮箱验证**: 必须发送验证邮件24小时内有效 - **防刷限制**: 同一IP每小时最多注册5次 - **数据合规**: 必须记录注册时间、IP地址、用户代理 ### 性能约束 - **响应时间**: 注册接口必须在500ms内返回 - **并发能力**: 支持每秒1000次注册请求 - **资源限制**: 单用户会话内存不超过1MB - **数据库**: 用户表必须分库分表单表不超过1000万记录 ## 设计决策说明 1. 选择Spring Boot 2.7.x而非3.x与现有微服务版本保持一致 2. 使用JPA而非MyBatis团队熟悉度更高维护成本低 3. Redis缓存会话提升登录状态验证性能 4. 独立认证服务便于后续扩展OAuth、SSO等认证方式 ## AI编码指导 - 实现时直接参考上述约束无需询问是否可以使用其他技术 - 遇到约束冲突时优先遵守业务规则约束 - 性能优化必须在满足所有业务约束的前提下进行约束文档的编写要点明确性使用必须、不得等明确词汇避免模糊表述可验证性约束应该能够被代码审查或自动化测试验证优先级明确约束的优先级顺序业务约束 技术约束 性能约束理由说明解释每个约束背后的原因帮助AI理解设计意图例外情况明确哪些情况下可以违反约束以及审批流程约束文档的实际效果当AI收到这样的设计文档时减少猜测明确知道项目限制不会提出不切实际的技术方案提高效率一次性获得所有约束减少来回确认的时间保证质量生成的代码从一开始就符合项目要求便于审查人类开发者可以快速验证AI是否遵守了所有约束记住好的设计文档不是告诉AI要做什么而是明确告诉AI不能做什么和必须怎么做。这就像给建筑工人一张详细的施工图纸上面标注了材料规格、结构要求、安全标准而不是只说建一栋房子。2. 第一步创建AI入职手册2.3 避免文档拆解的常见陷阱粒度控制的艺术在为AI准备项目文档时文档的拆解粒度至关重要。一个常见的误区是按UI页面拆解用户故事User Stories这往往会导致上下文碎片化AI只能看到孤立的页面功能无法理解完整的业务流程重复劳动相同的业务逻辑在不同页面文档中重复描述维护困难页面结构调整时大量关联文档需要同步更新AI理解偏差AI难以从碎片化信息中重建完整的系统认知合理的拆解原则按业务能力Business Capability而非页面拆解❌ 错误做法“用户注册页面”、“登录页面”、“个人资料页面”✅ 正确做法“用户身份认证模块”包含注册、登录、资料管理完整流程按领域边界Domain Boundary组织文档用户管理领域订单处理领域支付结算领域报表分析领域按复杂度和共享上下文拆解不按单个接口拆❌ 错误做法为每个REST接口创建独立文档如GET /api/users、POST /api/users等✅ 正确做法将相关接口按业务上下文分组用户管理模块包含用户CRUD、权限管理、会话管理等所有相关接口订单生命周期包含订单创建、查询、更新、取消、状态流转等完整流程支付处理包含支付发起、回调、退款、对账等支付全链路保持适中的文档粒度太粗一个文档包含所有内容 → AI难以定位具体信息太细每个函数/接口一个文档 → 维护成本高缺乏整体视图适中每个核心业务模块一个文档包含完整的功能上下文优先级排序原则开发顺序参考当AI需要实现或理解某个业务模块时建议按以下优先级顺序提供上下文查询操作GET/READ→ 理解数据结构和业务规则创建操作POST/CREATE→ 了解数据验证和业务逻辑更新/删除操作PUT/PATCH/DELETE→ 掌握状态变更和权限控制批量操作→ 处理批量数据处理逻辑导出功能→ 数据格式和性能考虑导入功能→ 数据验证和错误处理这种优先级排序帮助AI逐步建立完整的业务认知从最简单的读取开始逐步深入到复杂的写操作和批量处理。为AI优化的文档结构示例# 用户管理模块文档 ## 业务能力范围 - 用户注册与认证 - 个人资料管理 - 权限与角色控制 - 会话管理 ## 涉及的前端页面 - /register (注册页面) - /login (登录页面) - /profile (个人资料页面) - /settings (设置页面) ## 核心业务流程 1. 新用户注册流程 2. 用户登录与认证流程 3. 资料更新流程 4. 权限验证流程 ## API接口清单 - POST /api/auth/register - POST /api/auth/login - GET /api/users/{id} - PUT /api/users/{id} - POST /api/auth/logout ## 数据模型 - User (用户表) - Session (会话表) - Role (角色表)这种按业务能力组织的文档结构让AI能够理解完整的业务上下文识别模块间的依赖关系在修改时评估影响范围提供更准确的代码建议记住文档的拆解粒度决定了AI的理解深度。过于细碎的文档就像给AI一堆拼图碎片却不给参考图而合理的业务模块化文档则提供了完整的拼图框架。2.1 入职手册的核心要素AI的入职手册与人类工程师的入职材料有相似之处但也有其特殊性。一个完整的AI入职手册应包含项目概述用简洁的语言描述项目目标、业务价值和技术栈开发环境配置包括依赖安装、环境变量、启动脚本等代码规范编码风格、命名约定、提交规范架构原则项目的设计哲学和架构决策沟通协议如何与AI交互包括指令格式、上下文管理策略2.2 创建基础入职手册模板# AI开发者入职手册 ## 项目基本信息 - **项目名称**: [项目名称] - **技术栈**: [主要技术栈] - **代码仓库**: [Git仓库地址] - **主要维护者**: [负责人] ## 开发环境 1. 依赖安装: npm install / pip install -r requirements.txt 2. 环境变量: 复制 .env.example 为 .env 并配置 3. 启动命令: npm run dev / python main.py ## 代码规范 - 语言: [编程语言] - 缩进: [空格数] - 命名: [camelCase/snake_case等] - 注释: [注释规范] ## 与AI协作协议 1. 每次对话请保持上下文完整 2. 修改代码时请说明原因 3. 涉及架构变更时请先讨论3. 第二步历史项目文档自动化生成3.1 让AI扫描代码仓库对于历史项目第一步是让AI全面了解现有代码库。以下是具体操作步骤# 1. 授权AI访问代码仓库# 使用GitHub CLI或API令牌让AI能够读取代码# 2. 执行代码分析命令# 使用工具如sourcetrail、code2prompt等生成代码概览# 3. 生成AGENTS.md文档3.2 生成AGENTS.mdAI代理配置文件AGENTS.md是AI理解项目结构和职责分工的关键文档# 项目AI代理配置 ## 可用代理角色 1. **架构师代理**: 负责系统设计和架构决策 2. **后端工程师代理**: 处理服务端逻辑和API开发 3. **前端工程师代理**: 负责用户界面和交互逻辑 4. **数据库专家代理**: 管理数据模型和查询优化 5. **测试工程师代理**: 编写测试用例和质量保证 ## 各代理的职责边界 - 架构师: 涉及系统拆分、技术选型、性能优化 - 后端工程师: REST API、业务逻辑、中间件 - 前端工程师: 组件开发、状态管理、用户体验 - 数据库专家: 表设计、索引优化、迁移脚本 - 测试工程师: 单元测试、集成测试、E2E测试 ## 协作流程 1. 新功能需求 → 架构师评估 → 分配任务 2. 各代理并行开发 → 代码审查 → 集成测试 3. 部署上线 → 监控反馈 → 迭代优化3.3 生成完整项目文档体系3.3.1 架构文档生成# 系统架构文档 ## 整体架构图 mermaid graph TB A[客户端 Web/App] -- B[API网关] B -- C[认证服务] B -- D[业务服务1] B -- E[业务服务2] C -- F[(用户数据库)] D -- G[(业务数据库1)] E -- H[(业务数据库2)]技术栈分层表现层: [前端框架]应用层: [后端框架]数据层: [数据库/缓存]基础设施: [部署/监控]核心模块用户管理模块订单处理模块支付集成模块报表生成模块#### 3.3.2 模块索引文档 markdown # 模块索引 ## 模块概览 | 模块名称 | 路径 | 负责人 | 状态 | |---------|------|--------|------| | auth | /src/auth | AI代理 | 活跃 | | orders | /src/orders | AI代理 | 活跃 | | payments | /src/payments | AI代理 | 维护中 | | reports | /src/reports | AI代理 | 开发中 | ## 模块依赖关系 - auth → 独立模块 - orders → 依赖auth、payments - payments → 依赖auth - reports → 依赖orders3.3.3 API文档生成# API文档 ## 用户认证接口 ### POST /api/auth/login **请求体**: json { username: string, password: string }响应:{token:jwt_token,user:{id:1,username:admin}}GET /api/users/{id}权限: 需要管理员角色响应: 用户详细信息#### 3.3.4 数据库文档生成 markdown # 数据库设计文档 ## 表结构 ### users表 sql CREATE TABLE users ( id INT PRIMARY KEY AUTO_INCREMENT, username VARCHAR(50) UNIQUE NOT NULL, email VARCHAR(100) UNIQUE NOT NULL, password_hash VARCHAR(255) NOT NULL, created_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP );orders表CREATETABLEorders(idINTPRIMARYKEYAUTO_INCREMENT,user_idINTNOTNULL,amountDECIMAL(10,2)NOTNULL,statusENUM(pending,paid,shipped,delivered),created_atTIMESTAMPDEFAULTCURRENT_TIMESTAMP,FOREIGNKEY(user_id)REFERENCESusers(id));索引优化建议users.username: 已添加唯一索引orders.user_id: 已添加外键索引orders.status: 建议添加索引以加速查询## 4. 第三步AI操作参考流程 ### 4.1 新功能开发流程 mermaid flowchart TD A[接收新需求] -- B[查阅AGENTS.md分配角色] B -- C[架构师分析需求] C -- D[参考架构文档设计方案] D -- E[后端/前端代理并行开发] E -- F[参考API文档实现接口] F -- G[参考数据库文档操作数据] G -- H[测试代理验证功能] H -- I[文档代理更新相关文档] I -- J[功能上线完成]4.2 代码审查与优化当AI需要修改或优化代码时定位问题: 根据错误日志或性能指标定位问题模块查阅文档: 查看对应模块的文档了解设计意图分析影响: 评估修改对上下游模块的影响实施修改: 按照代码规范进行修改更新文档: 同步更新相关文档保持一致性4.3 故障排查流程# 故障排查检查清单 ## 第一步问题定位 1. 查看错误日志和监控指标 2. 确定影响范围和严重程度 3. 查阅相关模块的文档了解正常行为 ## 第二步根本原因分析 1. 检查最近代码变更 2. 验证数据一致性 3. 测试接口响应 ## 第三步修复实施 1. 制定修复方案 2. 实施修复并测试 3. 更新相关文档5. 最佳实践与注意事项5.1 文档维护策略定期更新: 每次重大变更后同步更新文档版本控制: 文档与代码一起进行版本管理自动化检查: 设置CI/CD检查文档与代码的一致性权限管理: 敏感信息如API密钥不写入文档5.2 AI协作优化技巧上下文管理: 为AI提供足够的上下文避免信息断层渐进式授权: 从只读开始逐步授予修改权限反馈循环: 定期评估AI的工作质量并调整策略安全边界: 明确AI不能操作的敏感区域5.3 工具推荐代码分析: Sourcegraph、CodeQL、Semgrep文档生成: Swagger/OpenAPI、JSDoc、Sphinx架构可视化: Draw.io、Mermaid、PlantUMLAI协作平台: GitHub Copilot、Cursor、Claude Code6. 总结为AI编程工具准备完整的入职手册和项目文档不是一次性任务而是一个持续的过程。通过系统化的文档体系AI能够快速上手: 减少学习曲线立即投入工作保持一致: 遵循项目规范保持代码质量高效协作: 与人类开发者无缝配合自主工作: 在明确边界内自主完成任务知识传承: 确保项目知识不会因人员变动而丢失开始为你的AI伙伴准备入职材料吧让它从第一天起就成为团队的高效成员下一步行动建议:为当前项目创建基础的AI入职手册运行代码分析工具生成初步文档逐步完善AGENTS.md和各专项文档建立文档更新和维护流程
AI编程CRUD类项目实操
发布时间：2026/7/29 4:02:17
1. 引言AI编程助手的新范式在当今快速发展的软件开发领域AI编程工具已经从简单的代码补全助手演变为能够深度理解项目上下文、参与架构设计、甚至自主完成复杂任务的智能伙伴。要让AI真正成为团队的一员而不是一个临时访客我们需要为它准备一份完整的入职手册——一套系统化的项目文档体系。本文将详细介绍如何为AI编程助手准备入职材料特别是针对历史项目的文档生成流程让AI能够快速理解项目全貌成为高效的开发协作者。2.4 设计文档AI的施工图纸与项目约束前置设计文档不仅仅是走流程的形式主义而是AI能够理解并执行的施工图纸。AI最大的问题在于不知道项目的具体约束条件如果不明确告知它会按照最通用的方式编写代码这往往与项目的实际需求不符。设计文档的核心价值将项目约束前置到设计阶段让AI在编码时直接遵守这些约束而不是事后修正。为什么项目约束对AI至关重要技术栈约束指定必须使用的框架、库、版本❌ AI默认选择最新、最流行的技术栈✅ 项目实际可能受限于遗留系统、团队技能、性能要求架构约束定义系统边界、通信协议、数据流向❌ AI默认设计理想化的微服务或单体架构✅ 项目实际混合架构、特定集成模式、性能瓶颈考虑业务规则约束明确业务逻辑、验证规则、状态流转❌ AI默认实现通用的CRUD操作✅ 项目实际复杂的业务规则、合规要求、审计追踪性能约束响应时间、吞吐量、资源限制❌ AI默认优化理论最优解✅ 项目实际硬件限制、成本考虑、用户体验要求如何为AI编写有效的设计文档实体设计优先原则先定义数据模型再设计接口在API设计过程中一个常见的错误是先设计接口再考虑数据模型。这会导致接口与业务实体脱节产生不一致的数据结构和冗余的转换逻辑。正确的做法是实体设计必须优先于接口设计原因如下业务一致性实体反映了核心业务概念接口只是访问这些实体的方式数据完整性先定义实体可以确保数据验证规则的一致性可维护性实体变更时所有相关接口可以统一调整AI理解AI需要先理解是什么实体再理解怎么做接口错误做法 vs 正确做法❌ 错误做法先设计接口# 用户管理API设计接口先行 ## 接口定义 ### POST /api/register 请求体 json { name: string, email: string, password: string }GET /api/user/{id}响应{user_id:1,user_name:张三,user_email:zhangsanexample.com}PUT /api/profile/{id}请求体{nickname:string,avatar_url:string}问题字段命名不一致namevsuser_name结构分散用户信息分散在多个接口中缺乏统一的数据模型**✅ 正确做法先设计实体** markdown # 用户管理模块设计实体先行 ## 1. 实体定义核心 java // User.java - 核心用户实体 public class User { private Long id; // 用户ID private String username; // 用户名唯一 private String email; // 邮箱唯一 private String passwordHash; // 密码哈希 private UserProfile profile; // 用户资料 private ListRole roles; // 角色列表 private LocalDateTime createdAt; // 创建时间 private LocalDateTime updatedAt; // 更新时间 } // UserProfile.java - 用户资料实体 public class UserProfile { private String nickname; // 昵称 private String avatarUrl; // 头像URL private String bio; // 个人简介 private LocalDate birthday; // 生日 }2. 值对象定义// Email.java - 邮箱值对象publicclassEmail{privatefinalStringvalue;publicEmail(Stringvalue){validateEmail(value);this.valuevalue;}privatevoidvalidateEmail(Stringemail){// 邮箱格式验证逻辑}}// Password.java - 密码值对象publicclassPassword{privatefinalStringhash;publicPassword(StringplainPassword){validateStrength(plainPassword);this.hashhashPassword(plainPassword);}}3. 接口设计基于实体用户注册接口PostMapping(/api/users)publicResponseEntityUserResponseregister(RequestBodyValidCreateUserRequestrequest){// 基于User实体创建用户}// 请求体与User实体保持一致publicclassCreateUserRequest{NotBlankprivateStringusername;EmailprivateStringemail;Size(min8)privateStringpassword;privateUserProfileRequestprofile;// 与UserProfile实体对应}用户查询接口GetMapping(/api/users/{id})publicResponseEntityUserResponsegetUser(PathVariableLongid){// 返回完整的User实体信息}// 响应体与User实体保持一致publicclassUserResponse{privateLongid;privateStringusername;privateStringemail;privateUserProfileResponseprofile;privateListRoleResponseroles;privateLocalDateTimecreatedAt;}4. 设计约束必须遵守实体优先所有接口设计必须基于已定义的实体命名一致接口字段名必须与实体属性名保持一致结构映射请求/响应体必须是实体的子集或投影验证统一数据验证规则在实体层定义接口层复用转换透明实体到DTO的转换必须明确且可追溯5. AI编码指导实现任何接口前先确认对应的实体模型已明确定义当需要新增字段时先在实体层添加再同步到相关接口避免在接口层定义业务逻辑所有业务规则应在实体或服务层处理保持实体与数据库模型的映射关系清晰一致##### 实体优先设计的优势 1. **减少认知负担**AI只需理解一次实体结构就能推导出所有相关接口 2. **提高一致性**所有接口共享相同的实体定义避免字段命名冲突 3. **便于重构**实体变更时AI可以自动识别所有需要更新的接口 4. **更好的测试**基于实体的测试用例可以覆盖所有使用场景 5. **文档生成**从实体自动生成API文档保持文档与代码同步 ##### 实施建议 1. **在项目初期**先定义核心领域实体User、Order、Product等 2. **设计接口时**每个接口必须明确说明它操作哪个实体 3. **代码审查时**检查接口是否遵循实体定义 4. **文档编写时**先写实体文档再写接口文档 5. **AI协作时**提供完整的实体定义作为上下文再要求实现接口 **记住**实体是业务的基石接口只是访问这些基石的门户。先打好地基实体设计再建门户接口设计才能构建稳定、可维护的系统架构。 **示例用户注册功能的设计约束** markdown # 用户注册功能设计文档 ## 项目约束必须遵守 ### 技术栈约束 - **后端框架**: Spring Boot 2.7.x不得使用3.x - **数据库**: MySQL 8.0必须使用JPA而非原生SQL - **缓存**: Redis 6.x所有用户会话必须缓存 - **安全**: 必须使用Spring Security密码必须bcrypt加密 ### 架构约束 - **服务边界**: 认证服务独立部署不得与其他业务逻辑耦合 - **API设计**: RESTful风格必须遵循公司API规范v2 - **数据流向**: 用户数据必须经过数据清洗服务再入库 - **错误处理**: 统一使用GlobalExceptionHandler不得自定义异常处理 ### 业务规则约束 - **密码强度**: 至少8位包含大小写字母和数字 - **邮箱验证**: 必须发送验证邮件24小时内有效 - **防刷限制**: 同一IP每小时最多注册5次 - **数据合规**: 必须记录注册时间、IP地址、用户代理 ### 性能约束 - **响应时间**: 注册接口必须在500ms内返回 - **并发能力**: 支持每秒1000次注册请求 - **资源限制**: 单用户会话内存不超过1MB - **数据库**: 用户表必须分库分表单表不超过1000万记录 ## 设计决策说明 1. 选择Spring Boot 2.7.x而非3.x与现有微服务版本保持一致 2. 使用JPA而非MyBatis团队熟悉度更高维护成本低 3. Redis缓存会话提升登录状态验证性能 4. 独立认证服务便于后续扩展OAuth、SSO等认证方式 ## AI编码指导 - 实现时直接参考上述约束无需询问是否可以使用其他技术 - 遇到约束冲突时优先遵守业务规则约束 - 性能优化必须在满足所有业务约束的前提下进行约束文档的编写要点明确性使用必须、不得等明确词汇避免模糊表述可验证性约束应该能够被代码审查或自动化测试验证优先级明确约束的优先级顺序业务约束 技术约束 性能约束理由说明解释每个约束背后的原因帮助AI理解设计意图例外情况明确哪些情况下可以违反约束以及审批流程约束文档的实际效果当AI收到这样的设计文档时减少猜测明确知道项目限制不会提出不切实际的技术方案提高效率一次性获得所有约束减少来回确认的时间保证质量生成的代码从一开始就符合项目要求便于审查人类开发者可以快速验证AI是否遵守了所有约束记住好的设计文档不是告诉AI要做什么而是明确告诉AI不能做什么和必须怎么做。这就像给建筑工人一张详细的施工图纸上面标注了材料规格、结构要求、安全标准而不是只说建一栋房子。2. 第一步创建AI入职手册2.3 避免文档拆解的常见陷阱粒度控制的艺术在为AI准备项目文档时文档的拆解粒度至关重要。一个常见的误区是按UI页面拆解用户故事User Stories这往往会导致上下文碎片化AI只能看到孤立的页面功能无法理解完整的业务流程重复劳动相同的业务逻辑在不同页面文档中重复描述维护困难页面结构调整时大量关联文档需要同步更新AI理解偏差AI难以从碎片化信息中重建完整的系统认知合理的拆解原则按业务能力Business Capability而非页面拆解❌ 错误做法“用户注册页面”、“登录页面”、“个人资料页面”✅ 正确做法“用户身份认证模块”包含注册、登录、资料管理完整流程按领域边界Domain Boundary组织文档用户管理领域订单处理领域支付结算领域报表分析领域按复杂度和共享上下文拆解不按单个接口拆❌ 错误做法为每个REST接口创建独立文档如GET /api/users、POST /api/users等✅ 正确做法将相关接口按业务上下文分组用户管理模块包含用户CRUD、权限管理、会话管理等所有相关接口订单生命周期包含订单创建、查询、更新、取消、状态流转等完整流程支付处理包含支付发起、回调、退款、对账等支付全链路保持适中的文档粒度太粗一个文档包含所有内容 → AI难以定位具体信息太细每个函数/接口一个文档 → 维护成本高缺乏整体视图适中每个核心业务模块一个文档包含完整的功能上下文优先级排序原则开发顺序参考当AI需要实现或理解某个业务模块时建议按以下优先级顺序提供上下文查询操作GET/READ→ 理解数据结构和业务规则创建操作POST/CREATE→ 了解数据验证和业务逻辑更新/删除操作PUT/PATCH/DELETE→ 掌握状态变更和权限控制批量操作→ 处理批量数据处理逻辑导出功能→ 数据格式和性能考虑导入功能→ 数据验证和错误处理这种优先级排序帮助AI逐步建立完整的业务认知从最简单的读取开始逐步深入到复杂的写操作和批量处理。为AI优化的文档结构示例# 用户管理模块文档 ## 业务能力范围 - 用户注册与认证 - 个人资料管理 - 权限与角色控制 - 会话管理 ## 涉及的前端页面 - /register (注册页面) - /login (登录页面) - /profile (个人资料页面) - /settings (设置页面) ## 核心业务流程 1. 新用户注册流程 2. 用户登录与认证流程 3. 资料更新流程 4. 权限验证流程 ## API接口清单 - POST /api/auth/register - POST /api/auth/login - GET /api/users/{id} - PUT /api/users/{id} - POST /api/auth/logout ## 数据模型 - User (用户表) - Session (会话表) - Role (角色表)这种按业务能力组织的文档结构让AI能够理解完整的业务上下文识别模块间的依赖关系在修改时评估影响范围提供更准确的代码建议记住文档的拆解粒度决定了AI的理解深度。过于细碎的文档就像给AI一堆拼图碎片却不给参考图而合理的业务模块化文档则提供了完整的拼图框架。2.1 入职手册的核心要素AI的入职手册与人类工程师的入职材料有相似之处但也有其特殊性。一个完整的AI入职手册应包含项目概述用简洁的语言描述项目目标、业务价值和技术栈开发环境配置包括依赖安装、环境变量、启动脚本等代码规范编码风格、命名约定、提交规范架构原则项目的设计哲学和架构决策沟通协议如何与AI交互包括指令格式、上下文管理策略2.2 创建基础入职手册模板# AI开发者入职手册 ## 项目基本信息 - **项目名称**: [项目名称] - **技术栈**: [主要技术栈] - **代码仓库**: [Git仓库地址] - **主要维护者**: [负责人] ## 开发环境 1. 依赖安装: npm install / pip install -r requirements.txt 2. 环境变量: 复制 .env.example 为 .env 并配置 3. 启动命令: npm run dev / python main.py ## 代码规范 - 语言: [编程语言] - 缩进: [空格数] - 命名: [camelCase/snake_case等] - 注释: [注释规范] ## 与AI协作协议 1. 每次对话请保持上下文完整 2. 修改代码时请说明原因 3. 涉及架构变更时请先讨论3. 第二步历史项目文档自动化生成3.1 让AI扫描代码仓库对于历史项目第一步是让AI全面了解现有代码库。以下是具体操作步骤# 1. 授权AI访问代码仓库# 使用GitHub CLI或API令牌让AI能够读取代码# 2. 执行代码分析命令# 使用工具如sourcetrail、code2prompt等生成代码概览# 3. 生成AGENTS.md文档3.2 生成AGENTS.mdAI代理配置文件AGENTS.md是AI理解项目结构和职责分工的关键文档# 项目AI代理配置 ## 可用代理角色 1. **架构师代理**: 负责系统设计和架构决策 2. **后端工程师代理**: 处理服务端逻辑和API开发 3. **前端工程师代理**: 负责用户界面和交互逻辑 4. **数据库专家代理**: 管理数据模型和查询优化 5. **测试工程师代理**: 编写测试用例和质量保证 ## 各代理的职责边界 - 架构师: 涉及系统拆分、技术选型、性能优化 - 后端工程师: REST API、业务逻辑、中间件 - 前端工程师: 组件开发、状态管理、用户体验 - 数据库专家: 表设计、索引优化、迁移脚本 - 测试工程师: 单元测试、集成测试、E2E测试 ## 协作流程 1. 新功能需求 → 架构师评估 → 分配任务 2. 各代理并行开发 → 代码审查 → 集成测试 3. 部署上线 → 监控反馈 → 迭代优化3.3 生成完整项目文档体系3.3.1 架构文档生成# 系统架构文档 ## 整体架构图 mermaid graph TB A[客户端 Web/App] -- B[API网关] B -- C[认证服务] B -- D[业务服务1] B -- E[业务服务2] C -- F[(用户数据库)] D -- G[(业务数据库1)] E -- H[(业务数据库2)]技术栈分层表现层: [前端框架]应用层: [后端框架]数据层: [数据库/缓存]基础设施: [部署/监控]核心模块用户管理模块订单处理模块支付集成模块报表生成模块#### 3.3.2 模块索引文档 markdown # 模块索引 ## 模块概览 | 模块名称 | 路径 | 负责人 | 状态 | |---------|------|--------|------| | auth | /src/auth | AI代理 | 活跃 | | orders | /src/orders | AI代理 | 活跃 | | payments | /src/payments | AI代理 | 维护中 | | reports | /src/reports | AI代理 | 开发中 | ## 模块依赖关系 - auth → 独立模块 - orders → 依赖auth、payments - payments → 依赖auth - reports → 依赖orders3.3.3 API文档生成# API文档 ## 用户认证接口 ### POST /api/auth/login **请求体**: json { username: string, password: string }响应:{token:jwt_token,user:{id:1,username:admin}}GET /api/users/{id}权限: 需要管理员角色响应: 用户详细信息#### 3.3.4 数据库文档生成 markdown # 数据库设计文档 ## 表结构 ### users表 sql CREATE TABLE users ( id INT PRIMARY KEY AUTO_INCREMENT, username VARCHAR(50) UNIQUE NOT NULL, email VARCHAR(100) UNIQUE NOT NULL, password_hash VARCHAR(255) NOT NULL, created_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP );orders表CREATETABLEorders(idINTPRIMARYKEYAUTO_INCREMENT,user_idINTNOTNULL,amountDECIMAL(10,2)NOTNULL,statusENUM(pending,paid,shipped,delivered),created_atTIMESTAMPDEFAULTCURRENT_TIMESTAMP,FOREIGNKEY(user_id)REFERENCESusers(id));索引优化建议users.username: 已添加唯一索引orders.user_id: 已添加外键索引orders.status: 建议添加索引以加速查询## 4. 第三步AI操作参考流程 ### 4.1 新功能开发流程 mermaid flowchart TD A[接收新需求] -- B[查阅AGENTS.md分配角色] B -- C[架构师分析需求] C -- D[参考架构文档设计方案] D -- E[后端/前端代理并行开发] E -- F[参考API文档实现接口] F -- G[参考数据库文档操作数据] G -- H[测试代理验证功能] H -- I[文档代理更新相关文档] I -- J[功能上线完成]4.2 代码审查与优化当AI需要修改或优化代码时定位问题: 根据错误日志或性能指标定位问题模块查阅文档: 查看对应模块的文档了解设计意图分析影响: 评估修改对上下游模块的影响实施修改: 按照代码规范进行修改更新文档: 同步更新相关文档保持一致性4.3 故障排查流程# 故障排查检查清单 ## 第一步问题定位 1. 查看错误日志和监控指标 2. 确定影响范围和严重程度 3. 查阅相关模块的文档了解正常行为 ## 第二步根本原因分析 1. 检查最近代码变更 2. 验证数据一致性 3. 测试接口响应 ## 第三步修复实施 1. 制定修复方案 2. 实施修复并测试 3. 更新相关文档5. 最佳实践与注意事项5.1 文档维护策略定期更新: 每次重大变更后同步更新文档版本控制: 文档与代码一起进行版本管理自动化检查: 设置CI/CD检查文档与代码的一致性权限管理: 敏感信息如API密钥不写入文档5.2 AI协作优化技巧上下文管理: 为AI提供足够的上下文避免信息断层渐进式授权: 从只读开始逐步授予修改权限反馈循环: 定期评估AI的工作质量并调整策略安全边界: 明确AI不能操作的敏感区域5.3 工具推荐代码分析: Sourcegraph、CodeQL、Semgrep文档生成: Swagger/OpenAPI、JSDoc、Sphinx架构可视化: Draw.io、Mermaid、PlantUMLAI协作平台: GitHub Copilot、Cursor、Claude Code6. 总结为AI编程工具准备完整的入职手册和项目文档不是一次性任务而是一个持续的过程。通过系统化的文档体系AI能够快速上手: 减少学习曲线立即投入工作保持一致: 遵循项目规范保持代码质量高效协作: 与人类开发者无缝配合自主工作: 在明确边界内自主完成任务知识传承: 确保项目知识不会因人员变动而丢失开始为你的AI伙伴准备入职材料吧让它从第一天起就成为团队的高效成员下一步行动建议:为当前项目创建基础的AI入职手册运行代码分析工具生成初步文档逐步完善AGENTS.md和各专项文档建立文档更新和维护流程
