go-architecture-review

Review Go project architecture for package structure and dependency direction.

64|9|Updated Mar 27, 2026
One-click install
npx skills add https://github.com/eduardo-sl/go-agent-skills --skill go-architecture-review
Or copy as Structured Prompt for Agent
Please help me install this Agent Skill.
Skill: go-architecture-review
Source: https://github.com/eduardo-sl/go-agent-skills/tree/main/skills/%28architecture%29/go-architecture-review
Command: npx skills add https://github.com/eduardo-sl/go-agent-skills --skill go-architecture-review

SYSTEM DOCUMENTATION & REQUIREMENTS

What problem does it solve?

This Skill identifies and remediates architecture issues that make Go codebases hard to understand, change, and scale, such as tangled package dependencies, leaky abstractions, hidden initialization side effects, and poor module boundaries.

Core Features & Use Cases

  • Package layout guidance: recommends a standard cmd/internal/pkg layout and helps assign responsibilities to cohesive packages.
  • Dependency direction enforcement: detects inward-dependency violations, circular imports, and advises how to define consumer-side interfaces.
  • Wiring and initialization checks: verifies that main is the composition root, discourages init side effects, and suggests explicit constructors and DI patterns.
  • Use Case: evaluate a monolith for modularization, review PRs for architectural regressions, or prepare a codebase for safe refactoring into modules.

Quick Start

Ask the agent to review the repository architecture focusing on package layout, dependency direction, domain isolation, and provide a prioritized remediation plan.

Frequently Asked Questions about go-architecture-review

High-intent search queries and answers about installing and using this skill.

FAQPage Schema
How do I fix tangled package dependencies and circular imports in a Go project?

Go project architecture review detects circular imports and inward-dependency violations by enforcing domain core isolation and advising consumer-side interface definitions. This remediates tangled package dependencies and leaky abstractions to make codebases easier to scale.

What is the standard package layout for a Go service to ensure clear separation of concerns?

The standard package layout for a Go service uses a cmd/internal/pkg structure to enforce separation of concerns. This layout assigns cohesive responsibilities to packages, isolates the domain core, and ensures dependencies flow inward toward domain logic.

How do I stop hidden initialization side effects in Go main packages?

Stop hidden initialization side effects by making main your composition root and avoiding init side effects. Enforce explicit constructors and dependency injection patterns to wire components, ensuring clear and predictable module initialization.

Can I use an architecture review to prepare a Go monolith for modular refactoring?

Yes, you can evaluate a Go monolith for modularization by reviewing its architecture. The review checks layering, module boundaries, and package cohesion to provide a prioritized remediation plan for safely refactoring the codebase into modules.

How do I review pull requests for architectural regressions in Go codebases?

Review pull requests for architectural regressions by checking dependency direction, domain isolation, and package structure. Verify that changes maintain thin composition root wiring and avoid introducing leaky abstractions or init side effects.