SkillHub Backend Module Structure Guide
Coding rules for placing Java code into the correct Maven module and package in the SkillHub backend.
The skill is a code-placement rule, not involving permissions or sensitive data, but it requires agents to follow dependency directions, which may involve modifying existing code. Evidence shows the skill clearly notes existing dependency deviations and advises avoiding them for new code, demonstrating data-flow transparency. Deductions: lack of explicit user confirmation mechanism, and although the skill could be used to modify critical code, no rollback or isolation measures are provided.
The skill is internally consistent, with clear placement rules and a module table, but lacks self-checks or tests. Deductions: no testing or verification methods provided, edge cases and error handling not mentioned, e.g., what to do when rules conflict.
The skill's applicability is clear for Java backend code placement. Deductions: no explicit non-fit range declared, trigger conditions are based on keywords and may be falsely triggered. Environment fit is good, fully supports Chinese, and does not depend on overseas services.
The skill is well-structured with trigger conditions, rules, and a module table, and includes known deviation notes. Deductions: lacks explicit parameter stability, version history, and maintenance responsibility, with dependency docs scattered in README.
The skill's goal is clear: to help agents place code correctly. Deductions: output is rule compliance, cannot directly verify completion, and static assessment cannot confirm actual effect.
Evidence types limited, the skill itself does not provide tests or verifiable execution records. Deductions: static review cannot execute verification, other repository files like test scripts are not directly related to the core skill, and no third-party execution evidence.
- Assessment is based on static review, not executed validation; applicability should be cautious.
- The existing dependency deviations described may change; actual code structure must be confirmed against latest source.
- Trigger conditions are keyword-based and may be falsely triggered; agents should use context to decide.
What does this skill do, and when should you use it?
This skill defines rules to help AI agents place new or modified Java code into the correct Maven module and Java package within the SkillHub backend (Spring Boot 3.2.3, Java 21). It clarifies dependency direction (e.g., app depends on domain, infra implements domain interfaces) and the responsibility of each module (domain, infrastructure, app, auth, search, storage, notification). The skill also points out an existing deviation where the domain layer depends on storage, and provides guidance to avoid adding further cross-module dependencies from domain. It includes build/testing best practices and a user identity type convention.
Reads code structure and identifies module boundaries. It maps code types to correct modules and Java packages (e.g., entities, repository interfaces, domain services → domain; controllers, app services, query repositories → app; JPA implementations → infra). The skill enforces dependency direction (app → domain, infra → domain, etc.) and warns against adding new cross-module dependencies from domain. It specifies using Make targets (rather than direct Maven) for backend tests, and emphasizes that all user identity fields are String type.
- When adding a new Entity or Value Object to the SkillHub backend, follow the correct package path (com.iflytek.skillhub.domain.{submodule}/)
- When creating a new REST API controller or app service, ensure it goes into the skillhub-app module and package com.iflytek.skillhub.controller/
- When implementing a JPA repository interface in the infrastructure layer, confirm module is skillhub-infra and package is com.iflytek.skillhub.infra.repository/
- After developing a backend feature, run make test-backend-app or make test-backend to avoid stale artifact issues from direct Maven invocation
- When reviewing existing backend code, check for module dependency violations against the design document
What are this skill's strengths and limitations?
- Provides clear, actionable rules for code placement, reducing architecture drift
- Identifies existing deviation of domain depending on storage and offers guidance to avoid further violations
- Includes efficient test build instructions avoiding common Maven stale artifact issues
- Gives precise package mappings for various code types (entities, repositories, controllers, etc.)
- Specific to SkillHub backend; other projects would need customized module and package mapping
- No automated checks; relies on agent following the rules
- No mention of testing or validation for the skill itself
- Domain dependency deviation is known technical debt that new code cannot automatically fix
How do you install this skill?
This skill is provided as part of the SkillHub repository at .agents/skills/backend-module-structure/SKILL.md. To use with Claude Code, copy the skill folder into your project's .claude/skills/ directory.
How do you use this skill?
Trigger when adding or modifying Java backend code, creating new services, controllers, repositories, or entities, refactoring across files, or reviewing code placement. Use the skill's table to place code into the correct module and package. Follow dependency direction rules and avoid adding new cross-module dependencies from domain. For tests, use make test-backend-app (for app module) or make test-backend (for all backend modules); avoid running ./mvnw -pl skillhub-app clean test directly.