java-vibe-kit

Bootstrap a Vibe Coding workflow into any Spring Boot project: a CLAUDE.md, a set of project docs, and Claude Code slash-commands — with best-practice rules matched to your Spring Boot version.

Join an existing Spring Boot project, run one command, and your AI assistant gains a persistent memory of how this codebase works.

Why

AI coding tools have no memory between sessions. Without a project context file they re-guess your conventions every time — wrong layering, wrong DTO shapes, wrong persistence patterns, the wrong response envelope. This kit generates that context from your actual codebase, and keeps the AI honest with version-correct Spring Boot rules (2.7 → 3.4+).

It also handles the real-world case: the project isn't fully best-practice yet. The kit adds correct rules for new code without forcing risky refactors on legacy packages (Strangler Fig). And when the project has its own abstractions — a response envelope, MapStruct mappers, a global exception handler — the kit teaches the AI to always use the abstraction, not the raw framework call.

Install

Run inside the root of your Spring Boot project (where pom.xml or build.gradle lives):

npx @tungvivas/java-vibe-kit

The installer (no AI, fully deterministic):

1. Reads ./pom.xml or ./build.gradle(.kts) → detects your Spring Boot & Java version
2. Copies slash-commands → ./.claude/commands/
3. Copies the version-matched best-practice file → ./.claude/spring-practices/
4. Installs skills → ./.claude/skills/ (auto-applied by Claude — no command needed)
5. Installs agents → ./.claude/agents/ (Spring subagents, isolated context)
6. Writes settings.json → ./.claude/settings.json (allowlist + build-verify hook)
7. Copies doc templates → ./docs/ and ./CLAUDE.md
8. Tells you to run /init in Claude Code

Requires Node.js 16+ (only for the installer — your project stays pure Java).

Options

| Flag | Effect | |------|--------| | --version <n> | Override detected Spring Boot version (e.g. --version 3.3) | | --force | Overwrite files that already exist | | --dry-run | Show what would happen, write nothing | | -h, --help | Help |

Use

After install, open the project in Claude Code:

/init            ← scan codebase, ask to confirm uncertain bits, generate docs

/init generates, in one reviewed pass: CLAUDE.md → docs/API_CONTRACT.md → docs/ARCHITECTURE.md → .claude/rules/project-rules.md → docs/PROJECT-STATUS.md → docs/ABSTRACTIONS.md → docs/decisions/.

Then every working session:

| Command | When | Does | |---------|------|------| | /start | Start of session | Read docs, summarize progress, wait | | /plan | Before a non-trivial feature | Clarify → compare approaches → design → write a reviewed plan to docs/plans/ | | /new-feature | New module, code only | Scaffold → implement (follows a /plan if one exists); tests/docs/review are separate commands | | /write-tests | Code without tests | Slice tests + integration tests | | /write-context | New/complex module | Create CONTEXT.md snapshot | | /write-api-contract | Endpoints changed | Extract endpoint table + DTO shapes into docs/api/<domain>.md | | /review-pr | Before commit | Spring review checklist → 🔴/🟡/🟢 | | /update-status | End of session | Update PROJECT-STATUS.md + commit | | /dev-cycle | Whole feature | Gated end-to-end orchestrator (follows a /plan if one exists) | | /convert-srs | You have a PDF/Word/Excel/PPT spec | Converts to Markdown under docs/srs/, splits multi-module, indexes |

Commands vs skills vs agents

The kit installs all three — they differ in who triggers them and where they run:

| | Command (/start, /review-pr) | Skill (spring-boot-practices) | Agent (spring-reviewer) | |---|---|---|---| | Who triggers it | You type /name deliberately | Claude activates it when context matches | You (or Claude) dispatch by name | | Runs in | Your main conversation | Your main conversation | An isolated context (parallel/background) | | Best for | A workflow you run at a point in time | Knowledge that should apply whenever relevant | Heavy/parallel work without bloating the main thread | | Lives in | .claude/commands/ | .claude/skills/<name>/SKILL.md | .claude/agents/<name>.md |

So /review-pr stays a command (you choose when to review); spring-boot-practices is a skill (idioms auto-apply the moment you write a controller, even in free-form chat); and spring-reviewer is an agent (it reviews in a separate context, so you can keep coding while it runs). The skill is a thin pointer to your .claude/spring-practices/<version>.md profile, so there is a single source of truth (no duplication) — and the agents point to the skills too.

Six skills ship today:

• spring-boot-practices — points to your version-matched profile; auto-applies when writing/reviewing/refactoring Spring Boot code.
• abstraction-priority — carries the decision tree for using your project's shared abstractions instead of raw framework calls; auto-applies before a raw API call.
• clarify-request — turns a vague request ("fix bug A", "thêm trường X") into a ready-to-paste, project-filled prompt instead of guessing; prints it for you to review.
• git-commit — generates Conventional Commit messages from your staged diff, using the prefix/language/scope config in .claude/rules/project-rules.md.
• explain — explains a class, concept, request flow, or design decision in Vietnamese, grounded in your actual docs and code (no assumed persistence library or version).
• srs-ingest — detects when you mention a non-Markdown spec (PDF/Word/Excel/PPT/screenshot) and hands off to /convert-srs to bring it into docs/srs/.

Agents (parallel / isolated context)

Six Spring-specialized subagents run in their own context window — dispatch them by name, and they can run in the background while you keep working (each in its own git worktree if needed). They read your skills + profile + docs/, so their output matches this project's conventions.

| Agent | Use for | How to call | |-------|---------|-------------| | spring-reviewer | Review changes before commit (read-only) | "use spring-reviewer on my changes" | | spring-build-fixer | Maven/Gradle/compile errors (jakarta↔javax, BOM) | "use spring-build-fixer to fix this build" | | spring-debugger | Runtime errors — bean wiring, transactions, lazy-loading | "use spring-debugger to trace this stacktrace" | | spring-test-writer | Write a feature's test suite + coverage | "run spring-test-writer in the background for OrderService" | | spring-onboarding | Map an unfamiliar repo — structure, entry points, traced request paths (read-only) | "use spring-onboarding to map this codebase" | | spring-git-workflow | Branching, atomic commits, rebase/conflict/recovery — safe git | "use spring-git-workflow to clean up my branch before a PR" |

There is no slash syntax — agents are invoked in plain language (Claude dispatches them). They complement, not replace, your own global agents and Claude Code's native worktree support.

Automation (settings & hooks)

The installer writes a .claude/settings.json so vibe coding flows with fewer interruptions:

• Permission allowlist — pre-approves mvn, ./mvnw, gradle, ./gradlew, and read-only git (status, diff, log, show) so Claude isn't constantly asking permission. State-changing git (commit, push) is deliberately not allowed — you approve those.

• Build-verify Stop hook — after each turn it runs compile (with your detected build tool), but only when .java files changed since HEAD — so a question-only turn skips it entirely:

  git diff --quiet HEAD -- '*.java' || mvn -q compile

  A compile failure is shown to Claude (non-blocking) so it can fix it before you commit — without trapping the session. To disable: delete the hooks block from settings.json.

If the project already has a .claude/settings.json, the installer skips it (won't overwrite your settings) — merge the allowlist/hook in manually, or re-run with --force.

Version-matched best practices

The installer copies exactly one profile based on your Spring Boot version:

| Spring Boot | Profile | Key idioms | |-------------|---------|-----------| | 2.x (2.7) | sb2.7.md | javax.*, Spring 5, Java 8/11, RestTemplate, @WebMvcTest | | 3.0–3.1 | sb3.0-3.1.md | jakarta.* migration, Spring 6, Java 17 baseline, records for DTOs | | 3.2–3.3 | sb3.2-3.3.md | RestClient, JdbcClient, virtual threads, @HttpExchange clients | | 3.4+ | sb3.4plus.md | Newest idioms, structured logging; fallback for future versions |

These files cover framework idioms only (DI, web layer, persistence, transactions, validation, exceptions, testing). Project-specific choices — package layout, naming, chosen abstractions — are inferred from your code and written into .claude/rules/project-rules.md.

Coexistence (joining a not-yet-standard project)

/init classifies what it finds as standard, below-standard, or uncertain, then writes a Coexistence Strategy into project-rules.md:

• Patterns you already do right → kept as required rules.
• Sub-standard patterns → correct rule applied to new code only.
• Legacy packages → listed as do-not-touch (no refactor unless asked).

Anything uncertain becomes a question — the kit never silently rewrites your rules.

Abstraction Priority (generic Spring convention)

The kit enforces a generic priority rule for backend code:

1. The project's own abstraction — its response envelope, mappers, base service/repository, shared exception handling — used if it exists for the need
2. Spring/framework component direct — used only when no project abstraction exists
3. Custom build — only when neither exists

When you run /init, it scans your codebase for these abstractions (a response-envelope class, MapStruct/ModelMapper usage, a @RestControllerAdvice, base service/repo interfaces) and writes a Project Abstractions table into docs/ABSTRACTIONS.md. From then on:

• /new-feature consults that table when generating code
• /review-pr flags an abstraction bypass as 🔴 BLOCKER in new code
• /write-context captures the WHY behind any framework-direct decisions

Example:

| Need | Use this (project abstraction) | Not this (raw) | |------|--------------------------------|----------------| | HTTP response body | ApiResponse<T> envelope | raw ResponseEntity / POJO | | Entity ↔ DTO | UserMapper (MapStruct) | manual getter/setter mapping | | Error handling | @RestControllerAdvice | try/catch in the controller | | Pagination | project PageResponse<T> | raw Page<T> leaking to the API |

What gets created in your project

your-spring-app/
├── CLAUDE.md                       # generated/filled by /init
├── .claude/
│   ├── commands/                   # 11 slash-commands (copied by installer)
│   │   ├── init.md  start.md  plan.md  new-feature.md  review-pr.md
│   │   ├── write-tests.md  write-context.md  write-api-contract.md
│   │   ├── update-status.md  dev-cycle.md
│   │   └── convert-srs.md
│   ├── spring-practices/           # 1 version-matched profile (copied)
│   │   └── sb3.2-3.3.md
│   ├── references/                 # shared specs — single source of truth for commands + agents
│   │   ├── plan-spec.md             #   → /plan, /dev-cycle, /new-feature
│   │   ├── feature-structure.md     #   → /new-feature, /dev-cycle (folder + order + coding rules)
│   │   ├── review-checklist.md      #   → /review-pr + spring-reviewer agent
│   │   └── test-spec.md             #   → /write-tests + spring-test-writer agent
│   ├── skills/                     # auto-applied by Claude (no command needed)
│   │   ├── spring-boot-practices/  #   → version idioms; triggers when writing Spring code
│   │   │   └── SKILL.md
│   │   ├── abstraction-priority/   #   → enforces project abstractions over raw calls
│   │   │   └── SKILL.md
│   │   ├── clarify-request/        #   → normalizes vague requests into a filled prompt
│   │   │   └── SKILL.md
│   │   ├── git-commit/             #   → conventional commit messages
│   │   │   ├── SKILL.md
│   │   │   └── references/conventions.md
│   │   ├── explain/                #   → explains code/concept/flow/why in Vietnamese
│   │   │   ├── SKILL.md
│   │   │   └── templates/vi.md
│   │   └── srs-ingest/             #   → detects non-MD specs, hands off to /convert-srs
│   │       └── SKILL.md
│   ├── agents/                     # Spring subagents (isolated context, run in parallel)
│   │   ├── spring-reviewer.md  spring-build-fixer.md  spring-debugger.md
│   │   └── spring-test-writer.md  spring-onboarding.md  spring-git-workflow.md
│   ├── settings.json               # allowlist (fewer prompts) + build-verify Stop hook
│   └── rules/
│       └── project-rules.md        # auto-loaded every session (filled by /init)
└── docs/                           # filled by /init
    ├── ARCHITECTURE.md  API_CONTRACT.md  ABSTRACTIONS.md
    ├── PROJECT-STATUS.md
    ├── decisions/
    ├── srs/                        # Markdown specs — /convert-srs writes here (see README.md inside)
    ├── api/                        # created on-demand: per-domain endpoint detail (see Scaling docs)
    └── STATUS-ARCHIVE.md           # created on-demand: overflow from PROJECT-STATUS.md

Scaling docs (keeping context lean on big projects)

The docs split into two tiers so context stays cheap as the project grows:

• Bounded (don't grow with feature count) — CLAUDE.md (≤200 lines), docs/ARCHITECTURE.md, docs/ABSTRACTIONS.md. These describe project-wide patterns; keep them at that altitude — don't inline per-feature detail.
• On-demand / split (grow with the project) — endpoint detail in docs/api/<domain>.md (indexed from API_CONTRACT.md, or replaced by springdoc-openapi), per-feature CONTEXT.md, one ADR per file in docs/decisions/. Read only when relevant.

Built-in guards keep the always-loaded / frequently-read files from bloating:

| File | Guard | |------|-------| | API_CONTRACT.md | conventions + index only; endpoints → docs/api/<domain>.md or OpenAPI | | PROJECT-STATUS.md | ≤80 lines; old "Completed" → docs/STATUS-ARCHIVE.md (never auto-read) | | feature CONTEXT.md | Refactor Log keeps ~10 recent entries; older → git history |

License

MIT