common-project-standard

# 项目规范技能 ## 功能描述 提供项目结构、文档管理、代码忽略等方面的标准和最佳实践，帮助团队建立统一的项目规范。同时提供技能规范验证工具和开源技能包装机制。 ## 何时使用 在以下情况调用此技能： - 创建新项目时 - 维护现有项目时 - 需要制定项目规范时 - 需要验证技能规范性时 - 需要集成开源技能时 ## 核心功能 - **技能管理**：规范技能的创建和管理流程 - **文档管理**：规范文档的编写和维护标准 - **Git忽略**：规范 .gitignore 文件的配置 - **AI忽略**：规范 AI 相关文件的忽略规则 - **项目结构**：规范项目目录结构 - **技能安装**：提供技能安装和配置指导 - **规范验证**：验证技能是否符合标准格式 - **开源集成**：支持开源技能的包装和切换 ## 输入参数 | 参数 | 类型 | 必填 | 说明 | |------|------|------|------| | projectType | String | 否 | 项目类型（backend/frontend/fullstack） | | framework | String | 否 | 使用的框架 | | validateSkills | Boolean | 否 | 是否验证技能规范 | | openSourceSkills | List | 否 | 要集成的开源技能列表 | ## 输出格式 ```json { "status": "SUCCESS", "projectType": "backend", "framework": "Spring Boot", "guidelines": { "skill": {...}, "documentation": {...}, "gitignore": {...}, "aiIgnore": {...}, "structure": {...}, "installation": {...}, "validation": {...}, "openSourceIntegration": {...} } } ``` --- ## 1. 技能管理规范 ### 1.1 技能目录结构 ``` skills/ ├── skill-name/ # 技能名称（小写连字符） │ └── SKILL.md # 技能定义文件（必填） ``` ### 1.2 技能命名规范 | 类型 | 前缀 | 示例 | |------|------|------| | 异常分析 | `exception-` | `exception-analysis` | | AI 聊天 | `spring-ai-` | `spring-ai-chat` | | 研发流程 | `common-` | `common-coding`, `common-test` | | 个人技能 | `personal-` | `personal-backend-coding-standard` | | 项目规范 | `common-project-` | `common-project-standard` | | 开源包装 | `os-` | `os-ui-library`, `os-chat-model` | ### 1.3 SKILL.md 文档结构 ```markdown --- name: "skill-name" description: "技能描述，简要说明技能的核心价值和用途" trigger: "触发条件，简洁描述技能何时被触发" disable-when: "禁用条件，描述不适合使用此技能的场景" category: "技能分类，如：backend/frontend/database/devops/ai" tags: ["标签1", "标签2"] requires: ["依赖技能1", "依赖技能2"] --- # 技能名称 ## 功能描述 ## 触发条件 ## 何时使用 ## 何时不使用 ## 核心功能 ## 输入参数 ## 输出格式 ## 使用流程 ## 调用示例 ## 失败案例 ## 最佳实践 ## 配置要求 ## 扩展指南 ``` ### 1.3.0 Frontmatter 元数据规范 Frontmatter 是技能的元数据定义区，用于描述技能的基本信息和属性： | 字段 | 类型 | 必要性 | 说明 | |------|------|--------|------| | **name** | String | 必填 | 技能名称，必须与目录名一致 | | **description** | String | 必填 | 技能的核心价值和用途描述（1-2句话） | | **trigger** | String | 必填 | 触发条件，简洁描述技能何时被触发 | | **disable-when** | String | 必填 | 禁用条件，描述不适合使用此技能的场景 | | **category** | String | 必填 | 技能分类（backend/frontend/database/devops/ai等） | | **tags** | Array | 推荐 | 技能标签，用于分类和搜索 | | **requires** | Array | 可选 | 依赖的其他技能名称 | **Frontmatter 示例**： ```markdown --- name: "common-spring-boot-init" description: "快速创建 Spring Boot 项目结构，支持多种数据库和依赖配置" trigger: "用户请求创建新的 Spring Boot 项目时" disable-when: "项目已存在或非 Java 技术栈项目" category: "backend" tags: ["spring", "java", "backend", "project-init"] requires: ["common-db-design"] --- ``` ### 1.3.1 文档章节说明 | 章节 | 必要性 | 说明 | |------|--------|------| | **功能描述** | 必填 | 技能的核心能力和价值定位 | | **触发条件** | 必填 | 技能被触发执行的条件和前置要求 | | **何时使用** | 必填 | 适合使用此技能的场景 | | **何时不使用** | 推荐 | 不适合使用此技能的场景（禁用样例） | | **核心功能** | 必填 | 技能提供的具体功能列表 | | **输入参数** | 必填 | 输入参数定义（表格形式） | | **输出格式** | 必填 | 输出数据格式（JSON示例） | | **使用流程** | 推荐 | 使用该技能的步骤说明 | | **调用示例** | 推荐 | 实际使用的代码或命令示例 | | **失败案例** | 推荐 | 常见错误场景及解决方案 | | **最佳实践** | 推荐 | 使用该技能的最佳实践建议 | | **配置要求** | 可选 | 环境变量、配置文件等要求 | | **扩展指南** | 可选 | 如何扩展或定制该技能 | ### 1.3.2 触发条件规范 触发条件应明确以下内容： 1. **前置条件**：使用技能前必须满足的条件 2. **环境要求**：所需的软件、依赖、权限等 3. **数据准备**：需要预先准备的数据或配置 4. **触发方式**：技能被调用的方式（API、命令行、事件等） **示例格式**： ```markdown ## 触发条件 - **前置条件**：项目已初始化，具备基础目录结构 - **环境要求**：Java 21+, Maven 3.8+, Spring Boot 3.2+ - **数据准备**：配置文件 `application.yml` 已存在 - **触发方式**：API 调用 / 命令行执行 / 事件触发 ``` ### 1.3.3 何时不使用（禁用样例） 明确列出不适合使用此技能的场景： **示例格式**： ```markdown ## 何时不使用 - 当项目已使用其他 ORM 框架时，不建议使用此技能 - 简单的 CRUD 操作无需使用此技能 - 需要复杂事务管理的场景请使用其他方案 ``` ### 1.3.4 失败案例规范 记录常见的失败场景及解决方案： **示例格式**： ```markdown ## 失败案例 | 错误场景 | 错误信息 | 解决方案 | |----------|----------|----------| | 数据库连接失败 | `Connection refused` | 检查数据库服务是否启动 | | 权限不足 | `Permission denied` | 确认用户有足够的文件权限 | | 依赖缺失 | `ClassNotFoundException` | 检查 pom.xml 依赖配置 | ``` ### 1.4 技能注册流程 1. 在 `skills/` 目录下创建技能目录 2. 创建 `SKILL.md` 文件 3. 在 `AGENTS.md` 中添加技能说明 4. 在 `SKILLS.md` 中注册技能 --- ## 2. 文档管理规范 ### 2.1 文档目录结构 ``` docs/ ├── api/ # API 文档 │ └── openapi.yaml ├── architecture/ # 架构文档 │ └── architecture.md ├── guides/ # 使用指南 │ └── getting-started.md ├── README.md # 项目说明（根目录） ├── AGENTS.md # 代理与技能架构（根目录） └── SKILLS.md # 技能清单（根目录） ``` ### 2.2 文档命名规范 | 类型 | 命名规则 | 示例 | |------|----------|------| | 文档文件 | 小写连字符 | `getting-started.md` | | 目录名称 | 小写连字符 | `api/`, `guides/` | ### 2.3 文档模板 #### README.md 模板 ```markdown # 项目名称 ## 项目简介 ## 技术栈 ## 快速开始 ## 项目结构 ## API 接口 ## 开发指南 ## 部署说明 ## 贡献指南 ## 许可证 ``` #### SKILLS.md 模板 ```markdown # 技能清单 ## 个人定制技能 | 技能名称 | 描述 | |----------|------| | personal-backend-coding-standard | 后端编码规范技能 | | personal-frontend-coding-standard | 前端编码规范技能 | | personal-java-common | Java 通用工具技能 | | personal-project-runner | 项目启动管理技能 | | personal-doc-manager | 个人文档管理技能 | | personal-solution-research | 方案调研技能 | | personal-brief-style | 简洁风格技能 | ## 通用技能 | 技能名称 | 描述 | |----------|------| | common-project-standard | 项目规范技能 | | common-contract-generation | 契约生成技能 | | common-frontend-playwright-test | 前端Playwright测试技能 | | common-backend-unit-test | 后端单元测试技能 | | common-coding | 编码技能 | | common-requirement-clarification | 需求澄清技能 | | common-api-doc | API文档生成技能 | | common-data-migration | 数据迁移技能 | | common-db-design | 数据库设计技能 | | common-dockerize | Docker容器化技能 | | common-grill-me | Grill Me 深度质询技能 | | common-spec-driven | Spec驱动规范技能 | | common-spring-boot-init | Spring Boot项目初始化技能 | | common-ui-design-spec | UI设计规范技能 | | common-ui-mockup | UI原型图生成技能 | | common-vue-init | Vue项目初始化技能 | ## 开源技能包装 | 技能名称 | 描述 | 底层实现 | |----------|------|----------| | os-ui-library | UI组件库技能 | 可配置（自研/Component-A/Component-B） | | os-chat-model | 聊天模型技能 | 可配置（OpenAI/DeepSeek/Claude） | ``` #### AGENTS.md 模板 ```markdown # 代理与技能架构 ## 概述 本项目使用 Trae AI 技能系统，通过技能扩展项目能力。 ## 技能目录 所有技能位于 `skills/` 目录下。 ## 技能分类 ### 个人定制技能 - personal-backend-coding-standard - 后端编码规范 - personal-frontend-coding-standard - 前端编码规范 - personal-java-common - Java 通用工具 - personal-project-runner - 项目启动管理 - personal-doc-manager - 个人文档管理 - personal-solution-research - 方案调研 - personal-brief-style - 简洁风格 ### 通用技能 - common-project-standard - 项目规范 - common-contract-generation - 契约生成 - common-frontend-playwright-test - 前端测试 - common-backend-unit-test - 后端测试 - common-coding - 编码规范 - common-requirement-clarification - 需求澄清 - common-api-doc - API文档生成 - common-data-migration - 数据迁移 - common-db-design - 数据库设计 - common-dockerize - Docker容器化 - common-grill-me - Grill Me 深度质询 - common-spec-driven - Spec驱动规范 - common-spring-boot-init - Spring Boot初始化 - common-ui-design-spec - UI设计规范 - common-ui-mockup - UI原型图生成 - common-vue-init - Vue项目初始化 ## 技能使用方式 ### 1. 安装技能 使用项目根目录的 `install-skills.sh` 脚本安装技能： ```bash # 安装所有技能 ./install-skills.sh /path/to/project # 安装指定技能 ./install-skills.sh -s common-coding -s common-project-standard . ``` ### 2. 注册技能 在 SKILLS.md 中注册技能，系统会自动加载。 ### 3. 使用技能 在需要时调用相应的技能接口。 ### 4. 验证技能规范 ```bash # 验证所有技能 ./validate-skills.sh # 验证指定技能 ./validate-skills.sh -s common-coding # 修复技能格式 ./validate-skills.sh -f ``` ``` ### 2.4 文档编写规范 1. **语言**：统一使用中文 2. **格式**：使用 Markdown 格式 3. **标题**：使用 `#` 表示标题层级 4. **代码块**：使用三个反引号 + 语言标识 5. **链接**：使用绝对路径或相对路径 --- ## 3. Git 忽略规范 ### 3.1 .gitignore 文件位置 - 根目录：`.gitignore` - 全局忽略规则 - 模块目录：`module/.gitignore` - 模块特定规则 ### 3.2 通用忽略规则 ```gitignore # 构建产物 target/ build/ dist/ *.class *.jar *.war # IDE 文件 .idea/ .vscode/ .project .classpath .settings/ # 日志文件 *.log logs/ # 配置文件 application-local.yml application-local.properties .env # OS 文件 .DS_Store Thumbs.db # Maven .mvn/ mvnw mvnw.cmd # Gradle .gradle/ gradlew gradlew.bat ```