# zlxx-vibecoding-template

**Repository Path**: ibdp/zlxx-vibecoding-template

## Basic Information

- **Project Name**: zlxx-vibecoding-template
- **Description**: 内部用的vibe coding  AI代码生成最佳实践相关用例、资料、文档汇总
- **Primary Language**: Unknown
- **License**: Not specified
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 1
- **Forks**: 2
- **Created**: 2026-03-26
- **Last Updated**: 2026-04-07

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# 技术中心vibe coding规范说明项目

## 整体说明

本项目为内部项目，主要用于规范内部项目代码编制规范，尤其是基于AI的vibe coding过程中如何让产出的代码符合预期，不偏离或少偏离，尽可能减少人的代码编制工作量，且向着更加贴合需求、最大节省人为干预和行政本地化标准化vibe coding模式的方向努力

- 开发工具：暂定trae cn 国内版，
- 模型选择：auto或自定义模型
- 开发基础架构：以技术中心现有的微服务架构为开发基础进行参考和设计开发
- 前端icon组件参照：iconPark vue
- 前端开发框架：vue3
- 后端开发语言：根据具体需求选择java、python或nodejs等，在微服务项目中只能使用java jdk17+，且需要遵循开发规范

## 配置要求

本文档主要用于指导相关人员完成基于trae的代码生成基本环境配置，通过配置达到生成的代码基本符合编码规范和代码结构，确保生成的代码无大偏差，且利于后续完善和扩展。本文档指导环境准备可涵盖如下内容：

1. 项目结构解析并自动生成项目模块分析报告
2. 按照项目模块分析报告和用户需求描述（提示词），自动生成符合规范和要求的前后端代码，并具备可执行、可验证特性
3. 自动生成测试用例，方便进行接口验证
4. 自动生成完整的注释、权限控制、注解、缓存、sql建表语句（或表结构更新语句）
5. 自动生成前端代码相关文件并自动完成UI审查，可出具审查报告并提出优化建议，以及根据优化建议进行必要的界面效果优化

### 配置内容

本文档所涉及配置内容主要集中在trae开发工具中，如果涉及到其他方面的配置会做特别说明，对于trae配置，主要有：

1. 项目规则配置
2. 个人规则配置（个性化）
3. skill技能配置
4. mcp配置
5. 模型约定
6. agent配置和约定
7. 代码生成提示词示例

### 项目代码规则配置（trae中设置）：

 \*\*注意：\*\*项目代码上下文提示见doc/def.md，可以将文件直接复制到项目根目录的.trae/roles/文件夹下，如果文件夹不存在需要新建文件夹，或者在trae的设置->规则和技能->项目规则中录入

```
# 后端代码生成要求

- 当用户进行以实体类为基础，进行整体模块的生成时，如果待生成文件已经存在，先记录文件内容作为参照（如函数定义、接口定义等代码结构），然后删除旧文件，进行全新生成
- 当用户进行小范围代码修改和业务逻辑变更时，如果涉及到了公共方法、公共函数、公共文件的变更，如果可以不变尽可能不动这些文件，如果非变不可，一定要反复询问用户，获得用户许可后再进行变更，否则应停止动作
- 在项目根目录下的doc目录下寻找类似《项目结构分析报告.md》等markdown或md后缀的项目说明文档，读取其中内容，这些文档里有项目各个模块的作用、接口说明、公共类服务接口能力介绍、权限控制方法等，作为后续代码生成的参考
- 根据用户要求，生成实体类或基于现有实体类生成配套的dto、vo、mapper、service、serviceImpl、controller、feign、converter和对应的前端模块页面，总体考虑前后端接口对照关系
- 所有实体类应继承自BaseEntity，且实体类本身不需要申明创建人、创建时间、更新人、更新时间的字段
- 所有实体类应严格按照同包名下其他实体类结构，包括类注解、字段注解，包括TableFiled、schema、NotBlank和TableLogic注解
- 所有实体类中的TableField中对于字段名称的约定，应在字段名称前加上F\_前缀，在主键上应包括value和type属性的赋值
- 所有实体类中NotBlank注解应按需添加到字段上，对于用户没有提出、且你认为不需要添加该注解的字段，应忽略对该字段添加NotBlank
- 所有实体类中涉及到isDeleted等软删除标记的字段添加TableLogic注解
- 所有实体类的类注解\<TableName>所命名的表名，应加上表前缀T\_
- 所有生成的VO类和DTO类，应确保有类注解Data和Schema，具体注解字段设置可参照同包名下的其他VO或DTO的实现，DTO和Vo类实现  Serializable接口，需要和前端进行交互的字段将在这两个类中体现，DTO中需要做非空判断的字段应加入NotNull注解，并标明 groups = {Save.class, Update.class，或其他类的引用}，以及message提示信息（见SysRoleDTO），以及在必要的字段上加入size注解，如@Size(min = 2, max = 20, message = "角色名称长度2-20位", groups = {Save.class, Update.class})
- 所有针对实体类生成Mapper，应确保类继承自BaseMapper<类名>,且类应包含Mapper和Schema注解，具体可参照同报名下其他Mapper的代码实现
- 所有针对实体类生成Service接口，应确保接口继承自IService<类名>，可参照同目录其他service的实现
- 所有针对实体类生成ServiceImpl类，应确保类继承自ServiceImpl\<Mapper类名称, 实体类名称>，并实现对应的Service接口定义，确保类具有Service注解、AllArgsConstructor注解、Transactional(rollbackFor = Exception.class)和CacheConfig(cacheNames = "\[类名]", cacheManager = "businessCacheManager")等注解
- 所有针对实体类生成ServiceImpl类中public类型的新增类函数实现，应加上CacheEvict（如@Caching(evict = {

 @CacheEvict(value = CACHE\_PREFIX\_REGION + CACHE\_PREFIX\_SELECT, allEntries = true),

@CacheEvict(value = CACHE\_PREFIX\_FINDBYID, allEntries = true)

&#x20;})

- 所有针对实体类生成ServiceImpl类中public类型的更新数据类函数实现，应加上CacheEvict（如@Caching(evict = {

@CacheEvict(value = CACHE\\\_PREFIX\\\_REGION + CACHE\\\_PREFIX\\\_SELECT, allEntries = true),

&#x20;@CacheEvict(value = CACHE\\\_PREFIX\\\_REGION + CACHE\\\_PREFIX\\\_INFINIDB, key = "#\[函数参数名].\[主键字段名]")

&#x20;})

- 所有针对实体类生成ServiceImpl类中public类型的数据分页获取类函数实现，应添加@Transactional(readOnly = true)注解，以及类似@Cacheable(value = CACHE\\\_PREFIX\\\_REGION + CACHE\\\_PREFIX\\\_SELECT,

&#x20;key = "T(com.zlxxaicloud.zlxx.common.core.util.CacheKeyGenerator).generate(#\[函数中的DTO参数名]) + '+' + T(com.zlxxaicloud.zlxx.common.core.util.CacheKeyGenerator).generate(#\[函数参数中PageQuery参数名])"

))的注解，类中应添加CACHE\_PREFIX\_REGION常量用来标识缓存数据的前缀（在redis中键的名称前缀）

- 所有生成controller中，应尽可能参照同包名下的其他controller的代码结构，包括RestController注解、AllArgsConstructor注解、RequestMapping注解、Tag注解、SecurityRequirement/Validated注解，每个接口函数应包含Mapping注解（GET/POST/PUT等）、Operation注解、HasPermission注解、SysLog注解等，其中HasPermission注解中的value属性值应是实体名称按结构分隔并以下划线连接+操作类型，如添加sysOrg实体的接口，其HasPermission注解的value值应该是sys\\\_org\\\_add，类和函数实现的注释要明确
- 所有生成controller中，至少应包含CRUD等基本的接口，如根据查询条件获取带分页的实体列表集合、根据实体ID获取实体详情、执行更新实体信息、新增实体信息、根据ID删除实体，如果实体中有类似parentId等上下级关系，则还应该包含根据上级ID获取实体树形列表这种实体包含关系的信息接口（顶级实体的上级ID为-1）
- 所有生成的controller，应在test源码文件夹下，生成各个接口对应的测试用例（junit test case），包括接口参数空值测试、接口参数非法值测试、接口逻辑正确性测试等用例
- 针对每个实体类生成converter的接口定义，具体可参照同目录下其他converter的实现，包括mapper注解、继承BaseConverter、泛型申明等
- 针对实体生成默认的feign远程服务接口，接口应加入FeignClient注解，如@FeignClient(contextId = "remoteClientDetailsService", value = ServiceNameConstants.UPMS\_SERVICE)，其中的'remoteClientDetailsService'应由remote字符串+实体类名称+Service字符串组合而成
- 同时根据实体类定义生成实体对应的sql建表语句，在sql建表语句中应包含对应的旧的表结构删除前置语句，默认对照的数据库为mysql，生成的建表语句以<表名称.sql>的命名方式保存在项目根目录下的sql文件夹下
- 结合项目整体内容和上下文，对本次生成的内容给出书面优化建议

# 前端页面模块生成规则

- 前端页面统放在项目主目录的frontend目录下，在该目录下按照具体业务范围是管理端、展示端或客户端分别选择对应的mange、view和client子目录，在这些子目录下是具体业务系统的目录结构，这些应由代码生成的人来决定，如果没有给出明确提示则反问用户让其提供
- 需要生成文件主要有api申明文件（如前端src下的api包下的文件）、router更新（一般在src下的router包下）、view界面（一般在src下的views包下），其他文件根据实际需要新增或更新，但涉及到公共文件的修改需要询问用户确认后再执行
- 项目整体使用了微服务架构，前端页面请求后端接口需要经过网关代理，在API接口定义中需要加上api接口地址前缀（如后端接口是/role/list，代理后的接口是/admin/role/list），具体前缀由用户指定，如果没有指定则反问用户，直到用户给出具体前缀
- 前端页面的实现应结合后端接口实现，如果后端接口无法满足前端页面要求，则修改后端接口使其适应前端页面
- 前端页面以zlxxa-pc-manage-base下的role模块作为蓝本进行代码生成
- 如果实体类中有上级ID等类似的设计，应在页面生成中设计为左侧树形结构，右侧列表结构
- 用户有以上内容意外的、特殊的、个性化要求，应遵循用户要求
- 除非用户特别说明，否则表单中涉及到下拉框这类需要动态获取数据的字段，先从实体类中固化这些数据，然后设计特定接口获取到这些数据
- 前端页面代码生成后应检查代码质量，并调用相关skills检查页面是否满足UI设计规范

# 综合规则

- 先后端代码生成完毕后，应自动更新doc下相关文档内容，以及前后端模块、子模块下的readme.md文档内容
- 调用UI审查和优化skills进行前端UI审核并自动完成优化
- 将生成内容整理成计划清单，逐项生成并进行二次分析确认，确保生成的内容可用、正确
- zai所有代码文件的头部都申明作者信息，如果用户在上下文中没有明确说明作者信息，则反问用户，直到用户明确给出作者信息



```

### 配置前端专家agent

```
You are a Frontend Expert, an elite frontend engineer specializing in modern Vue 3 development, pixel-perfect UI implementation, and performance optimization. You excel at creating responsive, accessible web applications with exceptional user experience.

## Core Responsibilities

### Modern Vue 3 Development
- Build applications using Vue 3 Composition API with TypeScript for type safety
- Implement advanced patterns like Suspense, async components, and custom composables
- Create reusable component libraries with proper props, emits, and slot patterns
- Use Pinia for state management with proper store architecture
- Implement proper component lifecycle management and cleanup

### Pixel-Perfect UI Implementation
- Translate design mockups to code with pixel-level precision
- Implement responsive designs using mobile-first approach with Tailwind CSS or SCSS
- Create smooth animations and micro-interactions using CSS transitions and Vue transitions
- Ensure cross-browser compatibility and graceful degradation
- Use CSS Grid and Flexbox for complex layouts

### Performance Optimization
- Optimize Core Web Vitals (LCP < 2.5s, FID < 100ms, CLS < 0.1)
- Implement code splitting and lazy loading for optimal bundle sizes
- Use virtual scrolling for large data sets and optimize rendering performance
- Optimize images with modern formats (WebP/AVIF) and responsive loading
- Implement proper caching strategies and CDN configuration

### Accessibility Excellence
- Follow WCAG 2.1 AA guidelines for all components
- Implement proper ARIA labels, roles, and semantic HTML structure
- Ensure full keyboard navigation and screen reader compatibility
- Test with real assistive technologies (VoiceOver, NVDA, JAWS)
- Support inclusive design patterns for diverse user needs

### Enterprise Component Integration
- Implement Element Plus, Ant Design Vue, or Naive UI with proper customization
- Configure component libraries for optimal bundle size and performance
- Create wrapper components that maintain design system consistency
- Implement proper theming and customization systems
- Ensure proper TypeScript integration with component libraries

## Technical Implementation Standards

### Component Architecture
- Create single-responsibility components with clear interfaces
- Implement proper prop validation and default values
- Use provide/inject for dependency injection when appropriate
- Structure components for maximum reusability and testability
- Follow consistent naming conventions and file organization

### State Management Patterns
- Use Pinia stores for global state with proper module organization
- Implement proper state mutations and action patterns
- Use computed properties for derived state
- Handle async operations with proper loading and error states
- Implement optimistic updates for better UX

### Performance Techniques
- Implement virtual scrolling for lists with >100 items
- Use requestAnimationFrame for smooth animations
- Debounce and throttle user input handlers
- Implement proper memoization with computed properties
- Use Web Workers for CPU-intensive operations

### Testing Strategies
- Write unit tests for all utility functions and composables
- Implement component testing with Vue Test Utils
- Create integration tests for critical user flows
- Test accessibility with automated tools and manual testing
- Ensure cross-browser testing coverage

## Quality Assurance

### Code Quality
- Maintain TypeScript strict mode compliance
- Follow ESLint and Prettier configurations
- Implement proper error boundaries and error handling
- Write self-documenting code with clear variable names
- Create comprehensive JSDoc comments for public APIs

### Performance Monitoring
- Implement Real User Monitoring (RUM) for performance tracking
- Set up performance budgets and monitoring alerts
- Monitor Core Web Vitals in production
- Use browser dev tools for performance profiling
- Implement proper logging and error reporting

### Accessibility Validation
- Run automated accessibility audits with axe-core
- Test keyboard navigation flow for all interactive elements
- Verify color contrast ratios meet WCAG standards
- Test with screen readers and assistive technologies
- Implement proper focus management and skip links

## Delivery Requirements

### Project Setup
- Configure Vite or Webpack 5 for optimal build performance
- Set up proper TypeScript configuration with strict mode
- Configure ESLint, Prettier, and Husky for code quality
- Implement proper environment variable management
- Set up CI/CD pipelines with automated testing

### Component Documentation
- Document component APIs with clear examples
- Provide usage guidelines and best practices
- Include accessibility considerations and requirements
- Create interactive demos and code playgrounds
- Maintain changelog and version documentation

### Deployment Optimization
- Configure proper caching headers and CDN setup
- Implement service workers for offline functionality
- Optimize for search engines with proper meta tags
- Set up proper monitoring and error tracking
- Implement gradual rollout and rollback strategies

## Communication Standards

### Technical Explanations
- Provide specific metrics when discussing performance improvements
- Explain accessibility decisions with WCAG guideline references
- Use concrete examples when explaining complex concepts
- Include before/after comparisons for optimization work
- Provide clear implementation timelines and effort estimates

### Code Reviews
- Focus on performance, accessibility, and maintainability
- Suggest specific improvements with code examples
- Explain the 'why' behind recommended changes
- Consider trade-offs between different approaches
- Ensure changes align with project architecture

When implementing frontend solutions, always prioritize user experience, performance, and accessibility. Strive for pixel-perfect implementation while maintaining clean, maintainable code. Your goal is to deliver exceptional web applications that work flawlessly across all devices and for all users.
```

<br />

## 常用mcp

### 架构图绘制

drawio（MCP）

```
{
  "mcpServers": {
    "drawio-mcp": {
      "command": "npx",
      "args": [
        "-y",
        "@drawio/mcp@latest"
      ]
    }
  }
}
```

### 飞书MCP

```
{
  "mcpServers": {
    "feishu-mcp": {
      "command": "npx",
      "args": [
        "-y",
        "feishu-mcp",
        "--stdio"
      ],
      "env": {
        "FEISHU_APP_ID": "cli_a92572afaf7a5cc5",
        "FEISHU_APP_SECRET": "b0ZJ3Akxu56TXCZ1cdeHuhRBUh4tIDp1",
        "FEISHU_SCOPE_VALIDATION": "false"
      }
    }
  }
}
```

### markdown转word

```
{
  "mcpServers": {
    "aigroup-mdtoword": {
      "command": "npx",
      "args": [
        "-y",
        "aigroup-mdtoword-mcp@latest"
      ]
    }
  }
}
```

### figma集成

```
{
  "mcpServers": {
    "TalkToFigmaMcp": {
      "command": "bunx",
      "args": [
        "cursor-talk-to-figma-mcp@latest"
      ]
    }
  }
}
```

## 提示词示例

### 创建新的项目结构提示词示例

```
我需要在项目根目录下新建一个新的微服务模块，模块名称叫[zlxxai-log]，是一个日志采集和审计模块，为其他微服务模块提供日志采集和审计服务，微服务的主包名是[com.zlxxaicloud.zlxx.log]，模块总体结构仿照zlxxai-base，包括api和biz两个子模块；生成两个子模块下相关的dto、eitity、feigh、util、vo、mapper、service、service.impl、converter、controller等包路径，生成主启动类[LogApplication]，以及resources下相应的配置文件，服务端口为[5899]，仿照doc下的application-template.yaml生成即将托管到nacos中的模块配置文件，名称叫zlxxai-log-biz-dev.yml，并将该文件保存到doc下
在zlxxai-frontend/zlxxai-pc/下新建[zlxxai-log]文件夹，作为[zlxxai-log]模块的前端文件所在位置，[zlxxai-log]模块的前端文件整体目录结构、代码结构、业务逻辑和风格总体仿照同文件夹下的zlxxai-pc-manage-base
最后，把新的模块加入到项目根目录下pom中的modules中
```

### 根据实体类生成相关代码的提示词示例

```
按照如下要求生成对应实体类及其实体类相关的dto、vo、mapper、service、serviceImpl、controller、converter、feign服务接口定义、前端配套页面、sql建表文件，以及更新相关的文档内容，要求如下：
总体代码风格和总体内容参照zlxxai-upms下SysRole实体类对照的各类文件
实体类、dto、vo、feign相关文件归属于zlxxai-base/zlxxai-base-api子模块，mapper、service、serviceImpl、controller、converter归属于zlxxai-base/zlxxai-base-biz子模块，自适应对应的包目录
前端页面应属于zlxxai-frontend/zlxxai-pc/zlxxai-pc-manage/zlxxai-pc-manage-base子模块
前端API接口前缀定义为[base]，在生成前端页面请求后端的API接口时需要加上次前缀
实体类名称：大模型信息
包含字段：
id：主键，自增
模型名称（如：Qwen2-7B-Instruct）：						数据类型为字符串，验证要求：非空，2-20长度，允许数字、字母、下划线、中划线
模型别名（易记名称，如：通义千问2-7B）：					数据类型为字符串，验证要求：非空，2-20长度，允许数字、字母、下划线、中划线
模型类型（如LLM/Embedding/Rerank/TTS/ASR/多模态）			数据类型为字符串，验证要求：非空
模型分类ID（如开源大模型/私有模型）							关联模型分类表的ID
模型格式（如PyTorch、GGUF、AWQ、GPTQ、ONNX、Safetensors）	数据类型为字符串，验证要求：非空
模型大小（如7B、13B、70B、1.8B 等参数规模）					数据类型为字符串，验证要求：非空
模型描述												数据类型为字符串，验证要求：最大长度不大于200
模型状态（未上传/已上传/训练中/已发布/已停用/已删除）			字符串，通过定义常量来实现状态的定义
协议类型：如 openai-v1 / anthropic / 自定义				字符串，通过定义常量来实现状态的定义
最大生成长度											数字，默认8192
默认温度												带小数点的数字，默认0.8
默认top_p											带小数点的数字，默认0.8
接口域名/地址（如https://api.openai.com）				数据类型为字符串，验证要求：非空，url地址格式
接口路径（如/v1/chat/completions）						数据类型为字符串，验证要求：非空，最大长度不大于100
api_key密钥											数据类型为字符串，验证要求：非空，2-100长度
api_secret											数据类型为字符串，验证要求：可以为空
逻辑删除标识（0正常 1删除）
排序													显示顺序
是否支持多模态/视觉（true/false）
量化等级（如FP16、INT8、INT4、AWQ-4bit、GPTQ-8bit）
支持语言（如zh/en/zh-en）
GPU要求（显存大小的说明：10GB/24GB）
推荐显卡（如A10/A100）

dto和vo要求：
实现Serializable接口
加入必要的前后端交互的字段信息，并设置字段的验证要求、schema信息、部分字段的长度要求等，这些信息均可从实体类定义中获取
其他没有特别说明的按照项目规则生成即可
```

### 将markdown文档转换为word文档提示词示例

```
将doc目录下的[项目模块分析报告.md]转换为word文档，并保存在doc目录下，文件名保留原文件名
```

## 常用skills 

### skills 仓库hub

[https://github.com/qufei1993/skills-hub/blob/main/docs/README.zh.md ](https://github.com/qufei1993/skills-hub/blob/main/docs/README.zh.md)

安装包见tools/Skills Hub\_0.4.1\_x64-setup.exe

<https://github.com/xingkongliang/skills-manager/blob/main/README.zh-CN.md>

安装包见tools/skills-manager\_1.10.0\_x64\_en-US.msi tools/skills-manager\_1.10.0\_x64-setup.exe

### UI审查和优化的skill

<https://impeccable.style/#downloads>

安装方式如下， 随着安装步骤选择要安装的skill，以及要部署到的开发工具即可

```Shell
npx skills add pbakaus/impeccable
```

## AI辅助研发的特点

- 在业务领域，AI只具备通用知识，个性化需求还得靠自己
- 上下文有大小限制，询问论述过多可能会面临上下文缺失、丢失的情况，此时最好进行手动上下文压缩，一来可以节省部分tokens，二来可以防止或延缓上下文丢失，
  通常需求多次纠偏才能达到较好的效果
- 每次回答完最好能都能反问AI是否有不合理的地方（把这个放在项目或系统的规则、系统的prompt中）、是否能正常运行等
- AI不太会处理模块间的依赖设计规范，如Base依赖了业务模块这类，最好能在编码阶段把基础、公共模块进行封装防止反向依赖
- 对话中沟通的内容类似于口头沟通，是“不算数”的，它会随着对话长度的增加逐渐被遗忘，应主动记录到文件并作为后续沟通的依据
- 对于生成过的内容，反复沟通确认是必须的
  对于待生成内容，通过list方式列出各项子内容
- 如果你不指定技术架构等细节，AI就按照自己的推理随意发挥，
  沟通确认要占据总工作量的一大半，跟人类协作是这样，跟 AI 协作也是这样
- 对于企业规范统一的内容应形成统一的系统提示词，对于项目规范和统一的内容应设置项目提示词