AgentSkillsCN

java-repo-bootstrap

为Java后端项目统一规范仓库布局、模块边界、命名规范及基础文档。在启动新项目、重构现有仓库，或向单体仓库迁移时，可选用此工具。

SKILL.md
--- frontmatter
name: java-repo-bootstrap
description: Standardize repository layout, module boundaries, naming conventions, and baseline docs for Java backend projects. Use when starting a new project, restructuring an existing repo, or migrating to a mono-repo.
license: Apache-2.0
compatibility: "Any OS; Git required; Java projects (framework-agnostic)."
metadata:
  version: "0.1.0"
  tags: ["java", "backend", "repo-layout", "architecture", "docs"]

Java Repo Bootstrap

Scope

In scope:

  • •Propose and apply a repository layout (mono-repo or multi-module).
  • •Define module boundaries and dependency direction (allowed imports, ownership).
  • •Standardize naming conventions (modules, packages, docs).
  • •Add baseline documentation: README, CONTRIBUTING, ADR template, architecture notes.
  • •Add minimal CI entrypoints (scripts/commands) but do NOT implement a full CI system.

Out of scope:

  • •Framework-specific scaffolding (Spring/Quarkus/Micronaut) beyond optional examples.
  • •Deep refactors across many packages without a phased plan.
  • •Changing external API contracts unless explicitly requested.

When to use

  • •Starting a new Java backend codebase.
  • •Refactoring repo structure (messy src/, unclear modules).
  • •Converting to mono-repo or multi-module.
  • •Onboarding a new team and needing consistent conventions.

Inputs (required context)

  • •Current repo tree (top-level files + modules).
  • •Build tool status: Gradle/Maven/Other (or unknown).
  • •Existing CI constraints (if any): required commands, existing pipelines.
  • •Public API surfaces (if any): REST endpoints, libraries, shared modules.

Procedure (plan-first, small diffs)

  1. •

    Discovery

    • •Enumerate current top-level layout and key modules.
    • •Identify build entrypoints (gradlew/mvnw, build files).
    • •Identify public surfaces (API modules, docs, published artifacts).
  2. •

    Choose a target layout (justify with trade-offs)

    • •Option A: Single service repo (single module).
    • •Option B: Multi-module repo (domain/application/infra or feature modules).
    • •Option C: Mono-repo with multiple services + shared libraries. Provide a file impact map and a migration strategy if restructuring.
  3. •

    Define module boundaries + dependency rules

    • •Define allowed dependency direction (e.g., domain <- application <- infra).
    • •Define shared modules policy (who can depend on what).
    • •Define package naming conventions and "no cycles" guardrails.
  4. •

    Apply structure using git-safe moves

    • •Use git mv for moves.
    • •Update imports and build configs incrementally.
    • •Ensure each commit builds.
  5. •

    Add baseline docs (templates allowed)

    • •README: purpose, how to build/test/run, local dev, troubleshooting.
    • •CONTRIBUTING: branch strategy, code style, tests required, commit guidelines.
    • •ADR: add template + index.
    • •Architecture notes: a minimal C4-style overview (context/container).
  6. •

    Verify (Definition of Done)

    • •Repo tree matches target layout.
    • •Build commands are documented and reproducible.
    • •Minimal docs exist and are discoverable.

Outputs / Artifacts

  • •Updated folder layout + module boundaries documented.
  • •README.md, CONTRIBUTING.md, docs/architecture/, docs/adr/ (or similar).
  • •A short "Repo Conventions" section with:
    • •module naming
    • •package naming
    • •dependency rules
    • •how to run build/tests

Definition of Done (DoD)

  • • Repo builds locally using a documented command.
  • • Tests run using a documented command (even if minimal).
  • • Docs added: README + ADR template + architecture overview.
  • • No broken imports; compilation succeeds.
  • • Module dependencies are acyclic (or explicitly justified).

Guardrails (What NOT to do)

  • •Do not perform a big-bang rewrite. Use phased migration.
  • •Do not rename public APIs without an explicit migration plan.
  • •Do not move files without git mv unless unavoidable.
  • •Do not invent architecture rules that contradict existing constraints.

Common failure modes & fixes

  • •Symptom: "Everything depends on everything"
    • •Cause: missing dependency direction
    • •Fix: introduce domain/core module and enforce one-way dependencies.
  • •Symptom: "CI breaks after moves"
    • •Cause: scripts/paths hardcoded
    • •Fix: update build entrypoints + document canonical commands.
  • •Symptom: "Endless bikeshedding on layout"
    • •Fix: pick a default layout and codify in docs; revisit via ADR later.

References

  • •See templates/ for README/ADR/Contributing stubs.
  • •See references/ for deeper layout and module-boundary guidelines.