Miaohong Java Backend

Overview

Use this skill to work inside miaohong-cloud-base without rediscovering the repository layout every time. Load only the references needed for the current task so the context stays focused.

The repository root file CLAUDE.md is the primary coding standard for this project. When any older repository habit or this skill conflicts with CLAUDE.md, follow CLAUDE.md.

Workflow

1. Confirm the scope before editing.
• Load CLAUDE.md from the repository root first when generating or reviewing backend code.
• Load references/module-map.md for repository navigation.
• Load references/commands.md for build, run, and verification commands.
• Load references/conventions.md when implementing or refactoring code.
• Load references/controller-style.md when adding or editing controller endpoints.
• Load references/provider-style.md when adding or editing Feign provider contracts or provider implementations.
• Load references/mapper-xml-style.md when adding mapper methods or XML SQL.
• Load references/exception-style.md when handling failures, validation, or error propagation.
• Load references/troubleshooting.md for startup, Nacos, gateway, or mapper issues.
2. Work from source, not generated output.
• Prefer files under src/main and src/test.
• Ignore target/ unless you are checking built artifacts on purpose.
3. Keep changes as narrow as possible.
• Prefer targeted Maven builds with -pl -am.
• Fall back to full-repo builds only when module boundaries are unclear.
4. Treat configuration as split across local files and Nacos.
• bootstrap.yml usually defines the application name, active profile placeholder, and Nacos imports.
• application.yml usually carries local overrides such as logging, static resources, or module-specific behavior.
5. Verify the right layer when behavior changes cross services.
• Shared infrastructure belongs in miaohong-common.
• Shared API contracts and Feign-facing DTOs belong in miaohong-modules-api.
• Runtime business behavior belongs in the concrete service module under miaohong-modules, miaohong-auth, or miaohong-gateway.

Repo-Specific Guardrails

• Assume Java 17 and Maven are required.
• Assume runtime configuration depends on reachable Nacos namespaces and imported config sets.
• Expect business modules to be package-first, for example com.miaohong.ai.user, not feature folders under a single controller tree.
• Check for mapper XML beside Java packages because this repository stores many *Mapper.xml files under src/main/java/.../mapper/xml, not under src/main/resources.
• When a request changes an external or shared contract, inspect both the provider module and the relevant API module before editing.
• For controller interface documentation, prefer Javadoc comments above the method and do not add Swagger annotations.
• For request and response shape, treat CLAUDE.md as the source of truth:
• no @PutMapping
• no @DeleteMapping
• no @PathVariable
• POST uses @RequestBody DTO
• GET is limited to single-parameter queries
• no Map request bodies or response payloads
• For Java classes generated in this repo, use @author bianruhao.
• For service implementations, avoid introducing circular dependencies across services. Prefer extracting shared logic, using mappers/providers, or moving cross-cutting behavior to a shared module instead of having services inject each other in a loop.

Reference Map

• references/module-map.md: root modules, runtime services, entrypoints, and where to start looking
• references/commands.md: targeted Maven build, test, and run commands for this repo
• references/conventions.md: coding and module-boundary rules inferred from the current codebase
• references/controller-style.md: controller class, route, permission, logging, and response patterns
• references/provider-style.md: Feign-facing provider interface and implementation patterns, with agent-module guidance
• references/mapper-xml-style.md: mapper interface and MyBatis XML division of responsibility
• references/exception-style.md: business exception, controller fail-fast, and error propagation rules
• references/troubleshooting.md: Nacos, gateway, startup, and mapper debugging checklist