SkillAgentSearch skills...

architecture-review

Analyze Java project architecture at macro level - package structure, module boundaries, dependency direction, and layering

Install / Use

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

Installs into whichever agent you are using.

About this skill
📄

SKILL.md

Installable skill definition

Quality Score

91/100

Supported Platforms

Universal

Our assessment of architecture-review

architecture-review scores 91/100 on our quality scale, 1134th of 4,702 Development & Engineering skills we index (top 25%).

Its SKILL.md is 8.6 KB long, well organised into 34 sections with 11 code examples: a thorough specification that gives an agent plenty to work with.

It has 747 GitHub stars, a meaningful sign that others use it.

Substance
29/30
Structure
20/20
Description
15/15
Adoption
12/20
Freshness
15/15

Maintenance, license and trust

  • The repository was last updated about 2 months ago, so architecture-review is actively maintained.
  • Our last check on 2026-10-06 found the source still online.
  • It is released under the MIT license, a permissive license that allows use, modification and commercial use with attribution.
  • Its trust signals score 100/100, with no cautions. These come from repository metadata, not a code audit — read the skill file before letting an agent act on it.

Safety scan

No issues found

Our scan of the whole file found no instruction hijacking, hidden characters, credential access, data exfiltration or destructive commands. An AI review of the same text found nothing harmful.

AI review by kimi-k2.7-code on 2026-10-04. Automated pattern scan on 2026-10-04. It catches known dangerous patterns, not every risk — read a skill before letting an agent act on it.

architecture-review compared with similar skills

All 4 of these similar skills score higher than architecture-review; compare them before choosing.

SkillScoreStarsUpdatedFormat
architecture-review (this skill)by decebals917472mo agoSKILL.md
taste-skillby Leonxlnx100117.6k9d agoCLAUDE.md
ai-job-searchby ai-job-search-dev10072.3ktodayCLAUDE.md
claude-howtoby luongnv8910047.4k3d agoCLAUDE.md
lobehubby lobehub10085.7ktodayMCP Server

Frequently asked questions

How do I install architecture-review?
Run npx skills add decebals/claude-code-java --skill architecture-review. The install tabs above show the steps for each supported agent.
Which AI agents does architecture-review work with?
It is written for Universal, as a SKILL.md file. Other agents that read the same format can often use it too.
Is architecture-review safe to use?
Our scan of the whole file found no instruction hijacking, hidden characters, credential access, data exfiltration or destructive commands. An AI review of the same text found nothing harmful. It is MIT-licensed and scores 100/100 on trust signals. Skills are instructions an agent will follow, so read the file before installing it and do not approve commands you do not understand.
Is architecture-review still maintained?
The repository was last updated about 2 months ago, so architecture-review is actively maintained.

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

| Smell | Symptom | Impact | |-------|---------|--------| | Package-by-layer bloat | service/ with 50+ classes | Hard to find related code | | Domain → Infra dependency | Entity imports @Repository | Core logic tied to framework | | Circular dependencies | A → B → C → A | Untestable, fragile | | God package | util/ or common/ growing | Dump for misplaced code | | Leaky abstractions | Controller knows SQL | Layer 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

Package-by-Feature (Recommended)

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

// ❌ 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

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

// 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

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:

# 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:

## 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

Related Skills

View on GitHub
GitHub Stars747
CategoryDevelopment
Updated2mo ago
Forks147

Languages

Shell

Trust signals

100/100

From repository metadata: license, adoption, age and documentation. Not a code audit — see the Safety scan above for what the skill file itself contains.

No cautions