★ FEATURED ARTICLE 1. 为什么需要skill.md文件在前后端分离开发中我们经常会遇到重复性的代码编写工作。比如每个Controller类都需要继承BaseController每个分页接口都需要返回统一格式的JSON数据。这些重复性工作不仅浪费时间还容易因为人为疏忽导致代码风格不一致。skill.md文件就是用来解决这个问题的。它相当于一个开发规范文档告诉AI助手比如Trae CN应该如何生成代码。通过这个文件我们可以统一项目代码风格减少重复性工作避免常见错误提高开发效率2. 创建skill.md文件的具体步骤2.1 找到规则和技能设置入口首先需要在Trae CN的设置中找到规则和技能选项。通常这个选项会在个人设置页面项目配置页面或者AI助手的偏好设置中具体位置可能因版本不同而有所变化但一般都会有明显的规则或技能字样。2.2 新建skill.md文件在技能设置页面点击添加技能或新建技能按钮。系统会提示你选择技能类型这里我们选择Markdown文档。给文件命名为skill.md这个命名是约定俗成的方便识别。当然你也可以用其他名字但建议保持一致性。2.3 文件内容结构skill.md文件通常包含以下几个部分# 项目开发规范 ## Controller规范 - 所有Controller必须继承BaseController - 类名以Controller结尾 - 使用RestController注解 ## 分页接口规范 - 返回格式 json { code: 200, message: success, data: { list: [], total: 0, pageNum: 1, pageSize: 10 } }异常处理规范使用统一异常处理器业务异常使用BizException错误码定义在ErrorCode枚举中## 3. 如何编写有效的skill.md内容 ### 3.1 初始版本获取 对于不熟悉的内容可以直接询问AI 请帮我写一个Java Spring Boot项目的skill.md文件模板包含Controller规范、分页接口规范和异常处理规范 AI会给出一个基础版本这个版本可能不完美但可以作为起点。 ### 3.2 实际使用中的调整 在开发过程中你会发现初始版本可能不满足所有需求。这时需要逐步完善 1. **分页接口问题** - 初始版本可能没有分页参数校验 - 可以添加分页参数pageNum最小值为1pageSize最大不超过100 2. **Controller基类问题** - 初始版本可能没有指定基类 - 可以明确所有Controller必须继承com.example.common.BaseController 3. **返回格式问题** - 初始返回格式可能缺少某些字段 - 可以细化data结构添加分页信息等 ### 3.3 持续迭代优化 skill.md文件不是一成不变的应该随着项目发展不断更新 - 每周回顾一次记录新发现的问题 - 团队讨论后更新到文件中 - 重要变更需要通知所有开发人员 ## 4. 实际案例分页接口规范优化 ### 4.1 初始问题 假设AI生成的初始skill.md中分页接口规范是这样的 json { data: [], total: 0 }在实际使用中发现以下问题缺少状态码和消息字段没有分页参数回传数据包裹层级不够4.2 优化过程首先我们询问AI 如何设计一个更完善的Spring Boot分页返回格式应该包含哪些字段根据AI建议和项目实际需求我们修改skill.md## 分页接口规范 返回格式示例 json { code: 200, message: success, data: { list: [], total: 0, pageNum: 1, pageSize: 10, pages: 1 } }字段说明code: HTTP状态码200表示成功message: 提示信息data.list: 实际数据列表data.total: 总记录数data.pageNum: 当前页码data.pageSize: 每页大小data.pages: 总页数### 4.3 验证效果 更新skill.md后让AI重新生成分页接口代码检查是否满足要求。如果不满足继续调整skill.md中的描述直到生成的代码符合预期。 ## 5. 常见问题与解决方案 ### 5.1 AI生成的代码不符合预期 **问题现象** 即使更新了skill.mdAI还是生成不符合要求的代码。 **解决方案** 1. 检查skill.md中的描述是否足够明确 2. 尝试用更具体的语言描述需求 3. 提供示例代码片段 例如不要只说继承BaseController而是写明完整类名 所有Controller必须继承com.example.common.BaseController ### 5.2 团队协作时的规范统一 **问题现象** 不同成员对skill.md的理解不一致导致生成的代码风格有差异。 **解决方案** 1. 在skill.md开头添加版本说明部分 2. 重要变更通过团队会议讨论 3. 定期组织代码评审发现不一致及时更新skill.md ### 5.3 技能文件过于庞大 **问题现象** 随着项目发展skill.md变得越来越长难以维护。 **解决方案** 1. 按模块拆分多个skill文件 - skill-controller.md - skill-service.md - skill-exception.md 2. 建立目录结构 3. 添加索引说明 ## 6. 高级技巧让skill.md更智能 ### 6.1 使用注释说明原因 在skill.md中不仅要写怎么做还要说明为什么 markdown ## 为什么Controller要继承BaseController - 统一处理异常 - 提供公共方法 - 规范日志输出这样AI能更好地理解需求背后的意图生成的代码会更符合预期。6.2 提供正面和反面示例好的skill.md应该包含正确示例错误示例错误原因例如## 分页参数校验 ✅ 正确做法 java GetMapping(/list) public Result list(RequestParam(defaultValue 1) int pageNum, RequestParam(defaultValue 10) int pageSize) { if(pageNum 1 || pageSize 100) { throw new BizException(分页参数不合法); } // ... }❌ 错误做法GetMapping(/list) public Result list(int pageNum, int pageSize) { // 缺少参数校验 // ... }原因缺少默认值可能导致NPE没有校验参数范围可能引发性能问题### 6.3 版本控制 skill.md应该纳入版本控制建议 1. 每个重大变更创建一个分支 2. 提交时写明变更原因 3. 与代码版本保持同步 ## 7. 个人实践经验分享 在实际项目中使用skill.md一年多总结了以下几点经验 1. **从小处着手**不要试图一次性写出完美的skill.md先解决最痛点的几个问题再逐步扩展。 2. **团队共识很重要**新的规范要经过团队讨论确保大家都理解并认同。 3. **定期回顾**每个月花30分钟回顾skill.md删除过时的内容添加新的最佳实践。 4. **量化效果**记录引入skill.md前后的代码审查问题数、重复代码量等指标看到实实在在的改进。 5. **灵活运用**不同项目可能需要不同的skill.md不要生搬硬套。
阅读完成 · 觉得有帮助？
