# Golang Architecture

> Standards for structural design, Clean Architecture, and project layout in Golang. Use when structuring Go projects or applying Clean Architecture in Go. (triggers: go.mod, internal/**, architecture, structure, folder layout, clean arch, dependency injection)

- Skill: `comeonoliver/golang-architecture` (Agent Skill)
- Install (CLI): `npx skillmds@latest add comeonoliver/golang-architecture`
- Raw SKILL.md: https://api.skillmd.com/api/skills/comeonoliver/golang-architecture/raw
- Safety review: pending (external: skill-scanner PASS, skillspector PASS)
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: AI & ML
- Author: ComeOnOliver (https://skillmd.com/u/comeonoliver)
- Updated: 2026-09-08
- Page: https://skillmd.com/skills/comeonoliver/golang-architecture

---


# Golang Architecture Standards

## **Priority: P0 (CRITICAL)**

## Principles

- **Clean Architecture**: Separate concerns. Inner layers (Domain) rely on nothing. Outer layers (Adapters) rely on Inner.
- **Project Layout**: Follow standard Go project layout (`cmd`, `internal`, `pkg`).
- **Dependency Injection**: Explicitly pass dependencies via constructors. Avoid global singletons.
- **Package Oriented Design**: Organize by feature/domain, not by layer (avoid `controllers/`, `services/` at root).
- **Interface Segregation**: Define interfaces where they are _used_ (Consumer implementation).

## Standard Project Layout

See [Standard Project Layout](references/project-layout.md) for directory tree.

### Layer Rules

- **Domain**: Inner-most. No deps.
- **UseCase**: Depends on Domain.
- **Adapter**: Outer-most. Depends on UseCase/Domain.

## Guidelines

- **Use Constructors**: `NewService(repo Repository) *Service`.
- **Inversion of Control**: Service depends on `Repository` interface, not `SQLRepository` struct.
- **Wire up in Main**: Main function composes the dependency graph.

## Verification Checklist (Mandatory)

- [ ] **No Globals**: Are there any global singletons or package-level variables being mutated?
- [ ] **DI**: Are dependencies explicitly passed via constructors?
- [ ] **Interfaces**: Are interfaces defined at the consumer side (where they are used)?
- [ ] **Layering**: Does `internal/domain` have zero external dependencies?
- [ ] **Composition**: Are dependencies wired together in `main.go`?

## Anti-Patterns

- **No Global Singletons**: Use DI; avoid package-level mutable variables.
- **No Layer Violations**: Domain must not import from adapter/infrastructure layers.
- **No God Services**: Split large services into single-responsibility components.

## References

- [Standard Project Layout](references/project-layout.md)
- [Clean Architecture Layers](references/clean-arch.md)