Skip to content

rgglez/rgglez-dev-skills / plugins/go-dependency-direction/skills/go-dependency-direction

go-dependency-direction

Verified

Applies dependency-direction rules when writing or reviewing Go code — consumer-defined minimal interfaces, no domain→infrastructure imports, one-way package arrows. Load whenever writing, refactoring, or reviewing Go packages, designing package layout, defining interfaces, or wiring repository/service/handler layers.

Dependency direction in Go

Persistence

Active for the rest of the session once loaded. Off only when the user says "stop go-dd" / "normal mode" / "ignora las reglas de dependencias" — then write Go the ordinary way, and say so in one line.

Back on when they say "go-dd" / "go-dd on" / "aplica las reglas de dependencias", or invoke the skill again. Confirm in one line and resume.

The import graph is the architecture. Directory names (domain/, usecase/, infrastructure/) are decoration. A package called domain that imports the one holding your database pool is infrastructure code wearing a label.

Every layout decision reduces to one question: which package is permitted to know that another exists?

Interfaces are declared by the caller

Put the interface in the package that invokes it, listing only the methods that package invokes. Declaring it beside the implementation forces every caller to import the provider, and any signature change there ripples outward to all of them.

Avoid — the provider exports the abstraction:

// package mailer
type Mailer interface {
	Send(ctx context.Context, to, subject, body string) error
	SendBatch(ctx context.Context, to []string, subject, body string) error
	Close() error
}

type SMTPMailer struct{ /* ... */ }
func (m *SMTPMailer) Send(...) error { /* ... */ }

Prefer — the caller states the shape it depends on, and the implementation carries no project imports:

// package invoicing
type sender interface {
	Send(ctx context.Context, to, subject, body string) error
}

type Service struct {
	mail sender
}

func NewService(mail sender) *Service {
	return &Service{mail: mail}
}
// package smtpmail
type Client struct {
	addr string
	from string
	auth smtp.Auth
}

func (c *Client) Send(ctx context.Context, to, subject, body string) error {
	msg := fmt.Appendf(nil, "Subject: %s\r\n\r\n%s", subject, body)
	return smtp.SendMail(c.addr, c.auth, c.from, []string{to}, msg)
}

smtpmail has never heard of invoicing. invoicing has never heard of SMTP. Neither one has to change when the other does — that is what dependency inversion buys, and it comes from the import list, not from a picture.

Details worth keeping:

  • Keep the interface small. One method here, because that is all Service calls — not the three SMTPMailer happens to publish.
  • Unexported is usually right. sender, not Sender. No one outside needs to refer to it.
  • Accept interfaces, return structs. Constructors take the caller's interface and hand back the concrete type.
  • This covers every collaborator, not just storage: HTTP clients, notifiers, caches, clocks, metrics sinks, queue publishers.

Two checks before you add an import

  1. Which way does this new arrow run?
  2. Is there already an arrow running the opposite way between these two packages?

And once per package: strip the project down to this package alone — does it still build? Packages holding types, arithmetic, validation, or wire formats must survive that.

Layered designs are only as good as their arrows

handler → service → repository, with no return path. Two shortcuts erode it, both arriving as small conveniences:

  • The service reaches for the handler's error-to-status helper. Fix: the service returns typed or sentinel errors, and the handler decides the status code.
  • The repository borrows the service's DTO because the struct already exists. Fix: the repository returns its own model and the service converts.

Reject both. Writing a small struct twice costs less than an arrow pointing backwards.

Check it, don't trust it

# every package's direct imports, one line each — the whole graph
go list -f '{{.ImportPath}} -> {{.Imports}}' ./...

# does anything reach a package it should not?
go list -deps ./... | grep <suspect>

Prefer .Imports over .Deps: .Deps is transitive and buries the answer under sixty lines of internal stdlib. Transport or persistence packages showing up in the core's import list is a genuine structural defect — and one that is invisible to any review that only looks at the diff.

Cases this does not cover

  • main and wiring packages import freely. Building the concrete smtpmail.Client and passing it to NewService is exactly their purpose.
  • Skip the interface when there is one implementation and no test fake. The rule concerns direction, not universal abstraction.
  • Don't redeclare a standard-library interface. When the shape you need already exists — io.Writer, io.Reader, fmt.Stringer, sort.Interface, http.Handler — take it instead of writing your own copy. It already satisfies the rule (one method, exported by no implementation), every reader knows it on sight, and it composes with everything built on it: io.MultiWriter, io.Copy, bufio, httptest. Write your own only for a shape the stdlib does not have, such as Write and Flush together.

Rules distilled from Forget clean architecture — Master dependency direction in Go by Yaninyz witty (Stackademic, July 2026). Wording and examples here are original.

writing-skillsobra/superpowersUse when creating new skills, editing existing skills, or verifying skills work before deploymentStars: 322kUpdated Claude CodeCodexVerifiedInstall
xlsxanthropics/skillsUse this skill any time a spreadsheet file is the primary input or output. This means any task where the user wants to: open, read, edit, or fix an existing .xlsx, .xlsm, .xltx, .csv, or .tsv file (e.g., adding columns, computing formulas, formatting, charting, cleaning messy data); create a new spreadsheet from scratch or from other data sources; or convert between tabular file formats. Trigger especially when the user references a spreadsheet file by name or path — even casually (like "the xlsx in my downloads") — and wants something done to it or produced from it. Also trigger for cleaning or restructuring messy tabular data files (malformed rows, misplaced headers, junk data) into proper spreadsheets. The deliverable must be a spreadsheet file. Do NOT trigger when the primary deliverable is a Word document, HTML report, standalone Python script, database pipeline, or Google Sheets API integration, even if tabular data is involved.Stars: 198kUpdated Claude CodeCodexVerifiedInstall
shipping-and-launchaddyosmani/agent-skillsPrepares production launches. Use when preparing to deploy to production, or when asking what needs to be in place before shipping. Use when you need a pre-launch checklist, when setting up monitoring, when planning a staged rollout, or when you need a rollback strategy.Stars: 119kUpdated Claude CodeCodexVerifiedInstall
childhoodthedotmack/claude-memBabysit a shipped release after merge, publication, or deployment. Verify published packages, production behavior, installed plugins, and late CI or user reports until the observation window is clean; use babysit for PR readiness before release.Stars: 118kUpdated Claude CodeCodexVerifiedInstall