New: 98,000+ skills indexed from GitHub repos with 100+ stars · every skill safety-checkedBrowse top skillsTop skills
Esc to closeBrowse all skills
Submit a skillBrowse skills
Submit a skillBrowse skills

Agent skill

Java Architecture Review

by decebals in decebals/claude-code-java

Reviews a Java project's architecture at the macro level: package structure, module boundaries, dependency direction and layering.

MITAuto-check passedDevelopment

Install Java Architecture Review

skills CLI
$ npx skills add decebals/claude-code-java --skill architecture-review -a claude-code

Project install by default; add -g for ~/.claude/skills/.

GitHub CLI
$ gh skill install decebals/claude-code-java architecture-review --agent claude-code

Project scope by default; add --scope user for a personal install. Needs GitHub CLI 2.90.0 or later (public preview).

Manual copy
$ git clone --depth 1 https://github.com/decebals/claude-code-java.git skills-src && mkdir -p .claude/skills && cp -r skills-src/skills/architecture-review .claude/skills/architecture-review && rm -rf skills-src

Use ~/.claude/skills/ instead of .claude/skills for a personal install. The folder must contain SKILL.md.

Claude Code skills documentation · loads skills from .claude/skills/

Facts

Skill name
architecture-review
GitHub stars
751
Token cost
~2.2k tokens
SKILL.md length
389 words
Files
2
Skills in repo
18
Repo updated
First seen
Licence
MIT

At a glance

Reviews a Java project's architecture at the macro level: package structure, module boundaries, dependency direction and layering.

  • Works in 9 steps: Package Structure → Dependency Direction → Layer Boundaries → …
  • Reviewing the package structure of a Java codebase
  • SKILL.md covers When to Use, Quick Reference: Architecture…, Package Organization Strategies and Dependency Direction Rules, plus 5 more sections
  • Instructions only: no scripts, shell commands, URLs or credentials in SKILL.md

What it does

The skill looks at structure rather than individual classes. It compares package-by-layer, package-by-feature (the recommended choice) and hexagonal or clean layouts with their pros and cons, and states the key rule that dependencies point inward, from adapters to application to domain.

A quick-reference table lists architecture smells with symptoms and impact: package-by-layer bloat, a domain that depends on infrastructure, circular dependencies, god packages such as a growing `util` or `common`, and leaky abstractions. A checklist covers package structure and dependency direction, for example no framework imports such as Spring, JPA or Jackson in the domain, and adapters depending on the domain rather than the reverse. The excerpt is cut off inside that checklist.

When your agent uses it

  • Reviewing the package structure of a Java codebase
  • Checking dependency direction between layers
  • Judging whether a project follows clean or hexagonal architecture

Example prompts

  • “Review the architecture of this Spring project and flag any layering violations.”
  • “Is our service package too big? Suggest a package-by-feature layout.”
  • “Check whether the domain package imports any framework classes.”

Workflow steps

9 steps, taken from the step headings in SKILL.md.

  1. Package Structure
  2. Dependency Direction
  3. Layer Boundaries
  4. Module Boundaries
  5. Scalability Indicators
  6. The Big Ball of Mud
  7. The Util Dumping Ground
  8. Anemic Domain Model
  9. Framework Coupling in Domain

What it can do on your machine

Read from SKILL.md and the folder at commit 0d98fe9. It shows what the files ask for, not the result of running them.

  • Tool permissions

    Pre-approves nothing: there is no allowed-tools line, so your agent's usual permission prompts apply.

    From allowed-tools in the SKILL.md frontmatter.

  • Runs code

    No scripts in the folder and no shell commands in SKILL.md (its code samples are java, bash and markdown).

    From the folder's file list and the shell code blocks in SKILL.md.

  • Network

    No URLs in SKILL.md.

    From URLs in SKILL.md, links to its own repository left out.

  • Credentials

    Names no API keys, tokens, secrets or passwords.

    From names ending in _API_KEY, _TOKEN, _SECRET, _KEY or _PASSWORD in SKILL.md.

Context cost

Java Architecture Review loads about 2.2k tokens when it runs. Until then it costs about 75 tokens; SKILL.md has 389 words of instructions outside code blocks.

Always · name and description, kept in context so the agent knows when to use it
~75
When it runs · the whole SKILL.md, loaded when a task matches
~2.2k

Estimates: characters ÷ 4, the usual rule of thumb; real counts depend on the model's tokenizer. Scripts and assets cost tokens only if the agent reads them.

Safety

Auto-check passed

The automated check found no risky patterns in SKILL.md.

Automated static check — not a guarantee. Review scripts before installing. It scans the text of SKILL.md for risky patterns (piping downloads into a shell, reading credential files, hidden Unicode, destructive commands); files beside SKILL.md are not scanned.

SKILL.md

The full file from decebals/claude-code-java at commit 0d98fe9, republished under its MIT licence (© decebals). 389 words, ~2,199 tokens.

Download SKILL.mdSave it as .claude/skills/architecture-review/SKILL.md (or your agent's skills folder). This skill also uses 1 other file; get the full folder from GitHub.
name
architecture-review
description
Analyze Java project architecture at macro level - package structure, module boundaries, dependency direction, and layering. Use when user asks "review architecture", "check structure", "package organization", or when evaluating if a codebase follows clean architecture principles.
license
MIT

Architecture Review Skill

Analyze project structure at the macro level - packages, modules, layers, and boundaries.

When to Use

  • User asks "review the architecture" / "check project structure"
  • Evaluating package organization
  • Checking dependency direction between layers
  • Identifying architectural violations
  • Assessing clean/hexagonal architecture compliance

Quick Reference: Architecture Smells

SmellSymptomImpact
Package-by-layer bloatservice/ with 50+ classesHard to find related code
Domain → Infra dependencyEntity imports @RepositoryCore logic tied to framework
Circular dependenciesA → B → C → AUntestable, fragile
God packageutil/ or common/ growingDump for misplaced code
Leaky abstractionsController knows SQLLayer boundaries violated

Package Organization Strategies

Package-by-Layer (Traditional)
com.example.app/
├── controller/
│   ├── UserController.java
│   ├── OrderController.java
│   └── ProductController.java
├── service/
│   ├── UserService.java
│   ├── OrderService.java
│   └── ProductService.java
├── repository/
│   ├── UserRepository.java
│   ├── OrderRepository.java
│   └── ProductRepository.java
└── model/
    ├── User.java
    ├── Order.java
    └── Product.java

Pros: Familiar, simple for small projects Cons: Scatters related code, doesn't scale, hard to extract modules

com.example.app/
├── user/
│   ├── UserController.java
│   ├── UserService.java
│   ├── UserRepository.java
│   └── User.java
├── order/
│   ├── OrderController.java
│   ├── OrderService.java
│   ├── OrderRepository.java
│   └── Order.java
└── product/
    ├── ProductController.java
    ├── ProductService.java
    ├── ProductRepository.java
    └── Product.java

Pros: Related code together, easy to extract, clear boundaries Cons: May need shared kernel for cross-cutting concerns

Hexagonal/Clean Architecture
com.example.app/
├── domain/                    # Pure business logic (no framework imports)
│   ├── model/
│   │   └── User.java
│   ├── port/
│   │   ├── in/               # Use cases (driven)
│   │   │   └── CreateUserUseCase.java
│   │   └── out/              # Repositories (driving)
│   │       └── UserRepository.java
│   └── service/
│       └── UserDomainService.java
├── application/               # Use case implementations
│   └── CreateUserService.java
├── adapter/
│   ├── in/
│   │   └── web/
│   │       └── UserController.java
│   └── out/
│       └── persistence/
│           ├── UserJpaRepository.java
│           └── UserEntity.java
└── config/
    └── BeanConfiguration.java

Key rule: Dependencies point inward (adapters → application → domain)

Dependency Direction Rules

The Golden Rule
┌─────────────────────────────────────────┐
│              Frameworks                 │  ← Outer (volatile)
├─────────────────────────────────────────┤
│           Adapters (Web, DB)            │
├─────────────────────────────────────────┤
│         Application Services            │
├─────────────────────────────────────────┤
│          Domain (Core Logic)            │  ← Inner (stable)
└─────────────────────────────────────────┘

Dependencies MUST point inward only.
Inner layers MUST NOT know about outer layers.
Violations to Flag
java
// ❌ Domain depends on infrastructure
package com.example.domain.model;

import org.springframework.data.jpa.repository.JpaRepository;  // Framework leak!
import javax.persistence.Entity;  // JPA in domain!

@Entity
public class User {
    // Domain polluted with persistence concerns
}

// ❌ Domain depends on adapter
package com.example.domain.service;

import com.example.adapter.out.persistence.UserJpaRepository;  // Wrong direction!

// ✅ Domain defines port, adapter implements
package com.example.domain.port.out;

public interface UserRepository {  // Pure interface, no JPA
    User findById(UserId id);
    void save(User user);
}

Architecture Review Checklist

1. Package Structure
  • Clear organization strategy (by-layer, by-feature, or hexagonal)
  • Consistent naming across modules
  • No util/ or common/ packages growing unbounded
  • Feature packages are cohesive (related code together)
2. Dependency Direction
  • Domain has ZERO framework imports (Spring, JPA, Jackson)
  • Adapters depend on domain, not vice versa
  • No circular dependencies between packages
  • Clear dependency hierarchy
3. Layer Boundaries
  • Controllers don't contain business logic
  • Services don't know about HTTP (no HttpServletRequest)
  • Repositories don't leak into controllers
  • DTOs at boundaries, domain objects inside
Show full SKILL.md (151 more words)Show less
4. Module Boundaries
  • Each module has clear public API
  • Internal classes are package-private
  • Cross-module communication through interfaces
  • No "reaching across" modules for internals
5. Scalability Indicators
  • Could extract a feature to separate service? (microservice-ready)
  • Are boundaries enforced or just conventional?
  • Does adding a feature require touching many packages?

Common Anti-Patterns

1. The Big Ball of Mud
src/main/java/com/example/
└── app/
    ├── User.java
    ├── UserController.java
    ├── UserService.java
    ├── UserRepository.java
    ├── Order.java
    ├── OrderController.java
    ├── ... (100+ files in one package)

Fix: Introduce package structure (start with by-feature)

2. The Util Dumping Ground
util/
├── StringUtils.java
├── DateUtils.java
├── ValidationUtils.java
├── SecurityUtils.java
├── EmailUtils.java      # Should be in notification module
├── OrderCalculator.java # Should be in order domain
└── UserHelper.java      # Should be in user domain

Fix: Move domain logic to appropriate modules, keep only truly generic utils

3. Anemic Domain Model
java
// Domain object is just data
public class Order {
    private Long id;
    private List<OrderLine> lines;
    private BigDecimal total;
    // Only getters/setters, no behavior
}

// All logic in "service"
public class OrderService {
    public void addLine(Order order, Product product, int qty) { ... }
    public void calculateTotal(Order order) { ... }
    public void applyDiscount(Order order, Discount discount) { ... }
}

Fix: Move behavior to domain objects (rich domain model)

4. Framework Coupling in Domain
java
package com.example.domain;

@Entity  // JPA
@Data    // Lombok
@JsonIgnoreProperties(ignoreUnknown = true)  // Jackson
public class User {
    @Id @GeneratedValue
    private Long id;

    @NotBlank  // Validation
    private String email;
}

Fix: Separate domain model from persistence/API models

Analysis Commands

When reviewing architecture, examine:

bash
# Package structure overview
find src/main/java -type d | head -30

# Largest packages (potential god packages)
find src/main/java -name "*.java" | xargs dirname | sort | uniq -c | sort -rn | head -10

# Check for framework imports in domain
grep -r "import org.springframework" src/main/java/*/domain/ 2>/dev/null
grep -r "import javax.persistence" src/main/java/*/domain/ 2>/dev/null

# Find circular dependencies (look for bidirectional imports)
# Check if package A imports from B and B imports from A

Recommendations Format

When reporting findings:

markdown
## Architecture Review: [Project Name]

### Structure Assessment
- **Organization**: Package-by-layer / Package-by-feature / Hexagonal
- **Clarity**: Clear / Mixed / Unclear

### Findings

| Severity | Issue | Location | Recommendation |
|----------|-------|----------|----------------|
| High | Domain imports Spring | `domain/model/User.java` | Extract pure domain model |
| Medium | God package | `util/` (23 classes) | Distribute to feature modules |
| Low | Inconsistent naming | `service/` vs `services/` | Standardize to `service/` |

### Dependency Analysis
[Describe dependency flow, violations found]

### Recommendations
1. [Highest priority fix]
2. [Second priority]
3. [Nice to have]

Token Optimization

For large codebases:

  1. Start with find to understand structure
  2. Check only domain package for framework imports
  3. Sample 2-3 features for pattern analysis
  4. Don't read every file - look for patterns

© decebals, MIT. Rendered from Markdown: HTML in the file is shown as text, images as links, and headings moved down two levels. Raw file

Files

SKILL.md and 1 other file in skills/architecture-review of decebals/claude-code-java.

  • SKILL.md
  • README.md

Open the folder on GitHubat commit 0d98fe9

Compare with similar skills

Java Architecture Review next to the 5 skills that share the most tags, products or categories with it. Stars are the repository's; “used in” counts other GitHub owners with a copy.

Java Architecture Review compared with similar skills
SkillStarsUsed inTokensAuto-checkLicenceRepo updated
Java Architecture Review this skilldecebals/claude-code-java751—~2.2kAutomated safety check: PassMIT
707 Technologies Hexagonal Architecturejabrena/plinth447—~1.4kAutomated safety check: PassApache-2.0
Code Review Skillawesome-skills/code-review-skill2.1k—~2.8kAutomated safety check: NotesMIT
Architecture PatternsKartikLabhshetwar/better-shot2.4k2 repos~1.4kAutomated safety check: PassCustom licence
Brooks Audithyhmrright/brooks-lint1.5k1 repos~537Automated safety check: PassMIT
Adopt a Design PatternTotoro-jam/battle-tested-patterns345—~4.9kAutomated safety check: PassMIT

Similar skills

  • 707 Technologies Hexagonal Architecture

    jabrena/plinth

    A skill your agent uses when you need framework-agnostic Hexagonal architecture guidance for Java projects - ports and adapters boundaries, application core independence, driving and driven…

    447 GitHub stars~1.4k tokensUpdated 3 days ago
    DevelopmentAuto-check passed

  • Code Review Skill

    awesome-skills/code-review-skill

    Provides comprehensive code review guidance for React 19, Vue 3, Angular 17+, Svelte 5, Rust, TypeScript, Java, Java 8, PHP, Ruby, Rails, Python, Django, FastAPI, Go, C/.NET, Kotlin, Swift, Dart…

    2.1k GitHub stars~2.8k tokensUpdated 1 mo ago
    DevelopmentAuto-check: notes

  • Architecture Patterns

    KartikLabhshetwar/better-shot

    Deep dive into software architecture for macOS. An agent skill from KartikLabhshetwar/better-shot.

    2.4k GitHub starsUsed in 2 repos~1.4k tokens
    DevelopmentAuto-check passed

  • Brooks Audit

    hyhmrright/brooks-lint

    Architecture audit that maps module dependencies, checks layering integrity, and flags structural decay across a codebase, drawing on twelve classic engineering books.

    1.5k GitHub starsUsed in 1 repo~537 tokens
    DevelopmentAuto-check passed

  • Adopt a Design Pattern

    Totoro-jam/battle-tested-patterns

    Matches a coding problem to one of 46 documented systems patterns, checks that it really fits, then adapts it into your codebase with a test for its invariant.

    345 GitHub stars~4.9k tokensUpdated 1 mo ago
    DevelopmentAuto-check passed

  • OpenOlat Developer Assistant

    OpenOLAT/OpenOLAT

    Gives an agent the architecture knowledge and controller, service and template patterns needed to write correct, idiomatic code in the OpenOlat learning management system.

    447 GitHub stars~6.9k tokensUpdated yesterday
    DevelopmentAuto-check passed

More from decebals/claude-code-java

All 18 skills in this repo

  • Java Design Patterns Reference

    decebals/claude-code-java

    A practical Java reference for Builder, Factory, Singleton, Strategy, Observer and other patterns, with a table matching problems to patterns.

    751 GitHub starsUsed in 1 repo~4.4k tokens
    Auto-check passed

  • Jpa Patterns

    decebals/claude-code-java

    JPA/Hibernate patterns and common pitfalls (N+1, lazy loading, transactions, queries).

    751 GitHub starsUsed in 1 repo~4k tokens
    Auto-check passed

  • Logging Patterns

    decebals/claude-code-java

    Java logging best practices with SLF4J, structured logging (JSON), and MDC for request tracing.

    751 GitHub starsUsed in 1 repo~3.3k tokens
    Auto-check passed

  • REST API Contract Review

    decebals/claude-code-java

    Reviews REST API design for correct HTTP verbs, versioning, DTO use, consistent responses and backward compatibility before an API change ships.

    751 GitHub stars~2.8k tokensUpdated 1 mo ago
    Auto-check passed

  • Changelog Generator for Java

    decebals/claude-code-java

    Builds changelog entries from conventional commits in a Java project, after working out whether it uses SemVer, two-part versions or calendar versions.

    751 GitHub stars~2.1k tokensUpdated 1 mo ago
    Auto-check passed

  • Clean Code Principles

    decebals/claude-code-java

    Covers Clean Code principles for Java: DRY, KISS and YAGNI with before-and-after examples, plus naming conventions for variables and booleans.

    751 GitHub stars~3.4k tokensUpdated 1 mo ago
    Auto-check passed

Works with

Categories

Questions about Java Architecture Review

What does Java Architecture Review do?

Reviews a Java project's architecture at the macro level: package structure, module boundaries, dependency direction and layering. The skill looks at structure rather than individual classes. It compares package-by-layer, package-by-feature (the recommended choice) and hexagonal or clean layouts with their pros and cons, and states the key rule that dependencies point inward, from adapters to application to domain.

When should I use Java Architecture Review?

Java Architecture Review fits situations like: reviewing the package structure of a Java codebase; checking dependency direction between layers; judging whether a project follows clean or hexagonal architecture.

How do I install Java Architecture Review in Claude Code?

Run `npx skills add decebals/claude-code-java --skill architecture-review -a claude-code`. Or copy the skill folder (skills/architecture-review in decebals/claude-code-java) into .claude/skills/architecture-review in your project. Claude Code loads it when a task matches its description.

How do I install Java Architecture Review in Codex?

Run `npx skills add decebals/claude-code-java --skill architecture-review -a codex`. Or copy the skill folder (skills/architecture-review in decebals/claude-code-java) into .agents/skills/architecture-review in your project. Codex loads it when a task matches its description.

Can I use Java Architecture Review in Cursor, Gemini CLI or GitHub Copilot?

Cursor, Gemini CLI, GitHub Copilot and OpenCode also load SKILL.md folders. With the skills CLI, run `npx skills add decebals/claude-code-java --skill architecture-review -a cursor` (or -a gemini-cli, github-copilot or opencode for the others). To copy it by hand, put the folder in .cursor/skills/architecture-review, .gemini/skills/architecture-review, .github/skills/architecture-review and .opencode/skills/architecture-review in your project.

What does Java Architecture Review need to run?

SKILL.md names no scripts, command-line tools or credentials: Java Architecture Review is instructions for the agent only.

Does Java Architecture Review access the network?

SKILL.md contains no URLs. Any network use would come from the scripts or tools the agent runs. This is read from the text; nothing was executed.

Is Java Architecture Review safe to install?

Our automated static check of SKILL.md found no risky patterns, such as piping downloads into a shell, reading credential files or hidden Unicode. It is not a guarantee. Review the folder before installing.

What licence does Java Architecture Review use?

Java Architecture Review is published under the MIT licence (declared in SKILL.md). It allows redistribution, so the full SKILL.md is shown on this page.

How many tokens does Java Architecture Review use?

About 2.2k tokens (SKILL.md is roughly 8.8k characters). Agents keep only the skill's name and description in context until a task matches; then they load SKILL.md in full.

What are the alternatives to Java Architecture Review?

Skills that share tags, products or a category with Java Architecture Review: 707 Technologies Hexagonal Architecture (jabrena/plinth, 447 stars), Code Review Skill (awesome-skills/code-review-skill, 2.1k stars), Architecture Patterns (KartikLabhshetwar/better-shot, 2.4k stars) and Brooks Audit (hyhmrright/brooks-lint, 1.5k stars). The comparison table on this page puts their stars, adoption, token cost, safety result and licence side by side.

Who maintains Java Architecture Review?

decebals (a GitHub user) maintains it in decebals/claude-code-java, which has 751 GitHub stars. The repository holds 18 skills in this directory. The repository was last updated on September 6, 2026.

Source: decebals/claude-code-java on GitHub. Facts on this page come from the repository at the commit we read; the author's words are quoted as theirs.