SkillHub 后端模块结构规范
为 SkillHub 后端 Java 多模块 Maven 项目提供模块划分与依赖方向的编码规范。
技能本身是代码放置规则,不涉及权限或敏感数据处理,但要求 agent 在放置代码前遵守依赖方向,可能涉及对现有代码的修改。证据显示技能明确指出现有依赖方向偏差且建议新代码避免,体现了数据流透明性。扣分原因:缺少明确的用户确认机制,且技能可能被用于修改关键代码,但未提供回滚或隔离措施。
技能自洽,提供了明确的放置规则和模块表,但未提供自检或测试。扣分原因:未提供任何测试或验证方法,边缘情况和错误处理未提及,如规则冲突时的处理。
技能适用场景清晰,针对 Java 后端代码放置。扣分原因:未提供非适用范围的边界声明,触发条件仅基于关键词,可能被误触发。环境适配良好,全面支持中文,且不依赖海外服务。
技能结构清晰,包含触发条件、规则、模块表,且提供已知偏差说明。扣分原因:缺少参数稳定性、版本更新历史和维护责任的明确说明,依赖文档分散在 README 中。
技能目标明确,即帮助 agent 正确放置代码。扣分原因:技能输出为规则遵守,无法直接验证其完成度,且静态评估无法确认实际效果。
证据类型有限,技能本身未提供测试或可验证的执行记录。扣分原因:静态审查无法执行验证,仓库中其他文件如测试脚本与技能核心不直接相关,且无第三方执行证据。
- 技能基于静态审查,未经实际执行验证,适用性需谨慎。
- 技能描述的现有依赖偏差可能变化,实际代码结构需以最新代码为准。
- 触发条件基于关键词,可能被误触发, agent 应结合上下文判断。
这个 Skill 能做什么，适合哪些场景？
该技能定义了一套规则，帮助 AI 代理在 SkillHub 后端（Spring Boot 3.2.3，Java 21）中添加或修改代码时，将代码放入正确的 Maven 模块和 Java 包。它明确了依赖方向（如 app 依赖 domain，infra 实现 domain 接口）以及各模块的职责（领域、基础设施、应用等）。该技能同时指出了当前领域层对存储模块的依赖偏离，并提供了避免进一步偏离的指导。它还包含构建测试的最佳实践和用户身份类型的约定。
读取代码结构并识别模块边界。它将代码类型映射到正确的模块和 Java 包（例如实体、仓库接口、领域服务→domain；控制器、应用服务、查询仓库→app；JPA实现→infra）。该技能强制依赖方向（app→domain，infra→domain等），并提醒领域层不能新增对基础设施模块的依赖。它规定了使用 Make 目标（而非直接使用 Maven）运行后端测试，并强调所有用户身份字段均为字符串类型。
- 为 SkillHub 后端新增一个 Entity 或 Value Object 时，遵循正确包路径（com.iflytek.skillhub.domain.{submodule}/）
- 新增 REST API 控制器或应用服务时，确保放置于 skillhub-app 模块和 com.iflytek.skillhub.controller/ 包下
- 在基础设施层实现 JPA 仓库接口时，确认模块为 skillhub-infra 且包位于 com.iflytek.skillhub.infra.repository/
- 开发后端功能后，运行 make test-backend-app 或 make test-backend 以避免直接执行 Maven 命令导致的陈旧构建问题
- 审查现有后端代码时，检查模块依赖是否违反设计文档中的依赖方向
这个 Skill 有哪些优点和局限？
- 为代码放置提供了清晰、可操作的规则，减少架构漂移
- 识别了现有领域层对存储依赖的偏离，并给出避免进一步偏离的指导
- 包含了高效的测试构建指令，避免常见的 Maven 陈旧产物问题
- 为实体、仓库、控制器等各类代码类型提供了明确的包路径映射
- 仅针对 SkillHub 后端，对其他项目需定制模块和包结构
- 未提供自动化检查，仅依赖代理遵循规则
- 未提及对技能的测试或验证
- 领域依赖偏离是已知的技术债，新代码无法自动修正
如何安装这个 Skill？
此技能已作为 SkillHub 仓库的一部分提供，路径为 .agents/skills/backend-module-structure/SKILL.md。若需在 Claude Code 中使用，将技能目录复制到您项目的 .claude/skills/ 目录。
如何使用这个 Skill？
触发场景包括：添加或修改 Java 后端代码、创建新服务、控制器、仓库或实体，跨文件重构，或审查代码放置。根据技能的表格将代码放入正确的模块和包。遵循依赖方向规则，避免在领域层添加新的跨模块依赖。运行测试时使用 make test-backend-app（针对 app 模块）或 make test-backend（针对所有后端模块），而不要直接执行 ./mvnw -pl skillhub-app clean test。