common-project-standard

# 项目规范技能 ## 功能描述 提供项目结构、文档管理、代码忽略等方面的标准和最佳实践，帮助团队建立统一的项目规范。同时提供技能规范验证工具和开源技能包装机制。 ## 何时使用 在以下情况调用此技能： - **创建新项目**：初始化项目结构、配置包名、设置目录规范 - **包名设计**：根据项目名生成正确的根包名（连字符拆分规则） - **文档规范**：编写 README、AGENTS.md、SKILLS.md 等文档 - **忽略配置**：配置 .gitignore、.traeignore、.cursorignore 等 - **技能管理**：创建新技能、注册技能、验证技能格式 - **开源集成**：包装开源技能、配置实现切换 - **项目重构**：调整目录结构、统一命名规范 - **团队规范**：制定团队编码约定、配置 AI 助手行为 - **技能冲突**：确定技能优先级、解决规范冲突 ## 核心功能 - **技能管理**：规范技能的创建和管理流程 - **文档管理**：规范文档的编写和维护标准 - **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/` 目录下创建技能目录（命名：`personal-` 或 `common-` 前缀） 2. 创建 `SKILL.md` 文件（包含完整的 Frontmatter 和章节） 3. 运行验证：`./scripts/validate-skills.sh -s <skill-name>` 4. 安装到双平台：`./scripts/skills.sh install <skill-name>` 5. **同步汇总文档**：`./scripts/skills.sh sync-docs` 6. 手动更新以下文档（如需要）： - `SKILLS.md` — 添加技能到对应分类表格 - `agents.md` — 更新技能路由表 - `SKILLS-ROUTER.md` — 添加场景索引 **更新现有技能**： 1. 修改 `skills/<name>/SKILL.md` 2. 运行验证：`./scripts/validate-skills.sh -s <skill-name>` 3. 全量更新：`./scripts/skills.sh update`（自动同步文档） 4. 检查文档是否需要更新（描述变更、新增场景等） **删除技能**： 1. 删除 `skills/<name>/` 目录 2. 从 `SKILLS.md` 中移除对应行 3. 从 `agents.md` 中移除路由条目 4. 从 `SKILLS-ROUTER.md` 中移除场景索引 5. 运行 `./scripts/skills.sh update` 同步到双平台 --- ### 1.5 任务流程强制约束 **核心原则**：必要环节不能少，可以多，但绝对不能少！ 根据任务类型，必须执行对应的完整流程（详见 `agents.md` 强制流程约束章节）： #### 调研/方案类任务（7 步） 1. 明确调研目标 2. 收集候选方案（**至少 3 个互联网大厂/业界标杆**） 3. 深度比对分析 4. 优劣特色总结 5. 受益情况分析 6. 推荐理由 7. 输出调研报告 **强制要求**： - ✅ 至少比对 3 个方案 - ✅ 必须给出优劣特色和理由 - ✅ 必须分析受益情况 #### 编码/开发类任务（8 步） 1. 需求澄清（`common-grill-me` 深度质询） 2. 需求文档化 3. 方案设计 4. 技术方案 5. 编码实现 6. 单元测试 7. UI 测试验证（**涉及 UI 时 mandatory**） 8. 测试报告汇总 **强制要求**： - ✅ 需求澄清不可跳过 - ✅ 单元测试不可跳过 - ✅ **涉及 UI 页面时，UI 测试 mandatory** #### Bug 修复类任务（4 步） 1. 问题定位（`common-systematic-debugging`） 2. 修复实现 3. 测试验证 4. UI 验证（**涉及 UI 时 mandatory**） **简化说明**： - ✅ 不需要完整的需求澄清和方案设计 - ✅ 测试环节不可跳过 --- ## 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文档生成