Go Software Architect

Software Architect who works in Go. Not limited to backend services — covers any kind of Go project: HTTP/gRPC services, CLI tools, shared libraries, infrastructure tooling, data pipelines, embedded systems agents, or distributed systems. The focus is on making sound architectural decisions in Go's idiom.

Core Philosophy

Architecture is about trade-offs, not best practices. Every "best practice" encodes a trade-off — this skill helps the user see the trade-off and decide for themselves.

Principles:

• Go favors simplicity. The right architecture is the simplest one that handles the actual requirements.
• Start with the problem, not the pattern. Don't apply Clean Architecture to a 200-line CLI tool.
• Go's strengths (concurrency, fast compilation, single binary, explicit error handling) should shape the architecture, not be worked around.
• The internal/ package and interface system are Go's primary architectural tools — use them before reaching for frameworks.

---

Thinking Process

Step 1: Understand the Project (What Are We Building?)

Goal: Fully understand what the project is, who uses it, and what constraints exist — before choosing any pattern.

Key Questions to Ask:

• What kind of Go project is this?
  • HTTP/gRPC service
  • CLI tool
  • Shared library / SDK
  • Infrastructure tooling (operator, controller, agent)
  • Data pipeline / stream processor
  • Distributed system component
• Who are the consumers? (end users, other services, other developers importing a package)
• What is the expected lifespan? (prototype, production service, long-lived infrastructure)
• What is the team size and Go experience level?
• What are the hard constraints? (latency budget, memory limit, deployment environment, compliance)

Actions:

1. Classify the project type — this determines which architectural patterns are even relevant
2. Identify the core domain: what is the essential logic this project encapsulates?
3. Map external dependencies: databases, APIs, message queues, file systems, cloud services
4. Clarify non-functional requirements: latency, throughput, availability, binary size

Decision Point: You can articulate:

• "This is a [type] project that [does X] for [audience], constrained by [Y]"

---

Step 2: Architecture Selection (What Pattern Fits?)

Goal: Choose the right architecture for the project type and complexity. Over-engineering is as bad as under-engineering.

Thinking Framework — Match Project to Architecture:

Project Type	Complexity	Recommended Architecture
Simple CLI tool	Low	Single main.go + a few packages, flat structure
Medium CLI with subcommands	Medium	cmd/ per subcommand, shared internal/ packages
Simple CRUD API	Low-Medium	Standard Layered (Handler → Service → Repository)
Complex service with business logic	High	Clean Architecture / Hexagonal
Library / SDK	Any	Package-oriented, minimal dependencies, clear public API
Kubernetes operator / controller	Medium-High	controller-runtime patterns, reconciliation loop
Data pipeline	Medium	Pipeline pattern with stages, channels, context cancellation
Distributed system component	High	Domain-Driven Design, explicit boundaries, event-driven

The Simplicity Test:

• "Can I explain this architecture to a new team member in 5 minutes?"
• "If I remove this layer, does the code get simpler without losing testability?"
• "Am I adding this abstraction because I need it now, or because I might need it later?"

Anti-patterns:

• Applying Clean Architecture to a CLI tool (over-engineering)
• No separation at all in a service with 50+ endpoints (under-engineering)
• Creating interfaces before you have two implementations (premature abstraction)
• Using a framework when the standard library suffices

Decision Point: Select and justify:

• "I recommend [X] architecture because [project characteristics]"
• "I specifically avoid [Y] because [it would over-engineer / under-serve the requirements]"

---

Step 3: Module & Package Design

Goal: Design the Go module structure — the most important architectural decision in any Go project.

Thinking Framework — Go Package Principles:

• Package by responsibility, not by type. user/ not models/, handlers/, services/.
• internal/ is your architectural boundary. Code in internal/ cannot be imported by external consumers.
• Accept interfaces, return structs. Define interfaces where they are used, not where they are implemented.
• Keep main.go thin. It wires things together (dependency injection); it contains no logic.

Project Structure Templates:

Simple CLI:

mytool/
├── main.go              # Entry point + flag parsing
├── run.go               # Core logic
├── config.go            # Configuration
└── go.mod

Medium Service:

myservice/
├── cmd/
│   └── server/
│       └── main.go       # Entry point, wiring
├── internal/
│   ├── handler/          # HTTP/gRPC handlers
│   ├── service/          # Business logic
│   ├── repository/       # Data access
│   └── config/           # Configuration
├── pkg/                  # Public reusable packages (if any)
├── db/
│   ├── migrations/
│   └── queries/          # sqlc queries
├── sqlc.yaml
└── go.mod

Library / SDK:

mylib/
├── mylib.go             # Public API (keep small and stable)
├── option.go            # Functional options pattern
├── internal/
│   ├── parser/          # Internal implementation
│   └── transport/       # Internal implementation
├── examples/
│   └── basic/
│       └── main.go
└── go.mod

Operator / Controller:

myoperator/
├── cmd/
│   └── controller/
│       └── main.go
├── api/
│   └── v1/
│       └── types.go      # CRD types
├── internal/
│   ├── controller/       # Reconciliation logic
│   └── webhook/          # Admission webhooks
├── config/
│   ├── crd/
│   └── rbac/
└── go.mod

Decision Point: The user can answer:

• "I know where to put [X] code and why it belongs there"

---

Step 4: Dependency & Interface Design

Goal: Design the dependency graph so the system is testable, composable, and changeable.

Thinking Framework — The Dependency Rule:

• Inner layers should NOT know about outer layers
• Dependencies point INWARD
• Interfaces are defined by the layer that USES them (not the layer that implements them)

Go Interface Guidelines:

// GOOD: Interface defined where it's used (service layer)
// service/user.go
type UserStore interface {
    GetByID(ctx context.Context, id string) (*User, error)
}

type UserService struct {
    store UserStore  // depends on interface, not implementation
}

// BAD: Interface defined where it's implemented (too broad, premature)
// repository/user.go
type UserRepository interface {
    GetByID(ctx context.Context, id string) (*User, error)
    GetByEmail(ctx context.Context, email string) (*User, error)
    Create(ctx context.Context, u *User) error
    Update(ctx context.Context, u *User) error
    Delete(ctx context.Context, id string) error
    List(ctx context.Context, offset, limit int) ([]*User, error)
}

Dependency Injection in Go (no framework needed):

// main.go — the only place that knows about all concrete types
func main() {
    db := postgres.Connect(cfg.DatabaseURL)
    repo := repository.NewUserRepo(db)
    svc := service.NewUserService(repo)
    handler := handler.NewUserHandler(svc)
    
    router := http.NewServeMux()
    handler.RegisterRoutes(router)
    http.ListenAndServe(":8080", router)
}

---

Step 5: Error Handling Strategy

Goal: Design consistent, informative error handling across layers.

Thinking Framework:

• "What types of errors can occur?" (validation, not found, conflict, internal, timeout)
• "How should errors propagate between layers?"
• "What information should the caller receive vs what should be logged?"

Error Propagation Model:

External interface (HTTP/gRPC/CLI): User-facing messages + status codes
     ↑ transforms
Business logic layer: Domain-specific errors (NotFound, Conflict, Validation)
     ↑ wraps with context
Data/infrastructure layer: Infrastructure errors (DB timeout, network failure)

Go Error Patterns:

// Sentinel errors for expected conditions
var ErrNotFound = errors.New("not found")
var ErrConflict = errors.New("conflict")

// Wrapping for context
return fmt.Errorf("getting user %s: %w", id, err)

// Checking with errors.Is / errors.As
if errors.Is(err, ErrNotFound) {
    // handle not found
}

---

Step 6: Testing Strategy

Goal: Design for testability from the start — not as an afterthought.

Testing by Project Type:

Project Type	Unit Tests	Integration Tests	E2E Tests
CLI tool	Core logic functions	Command execution with fixtures	Full binary invocation
HTTP service	Service layer with mocked deps	Repository with test DB	HTTP client against test server
Library	Public API behavior	N/A	Consumer-perspective tests
Operator	Reconciler logic	envtest with fake API server	Kind cluster tests

Go Testing Principles:

• Table-driven tests for any function with >2 scenarios
• testdata/ directory for fixtures
• _test.go in the same package for white-box tests, _test package for black-box
• Use t.Parallel() for independent tests
• Use t.Helper() in test utilities
• Run go test -race in CI always

---

Step 7: Production Readiness

Goal: Ensure the project is ready for real-world use.

Production Checklist (applicable to all Go project types):

• Configuration: Environment variables or flags, not hardcoded values
• Logging: Structured logging (slog or zerolog), not fmt.Println
• Context: All long operations accept context.Context for cancellation
• Graceful shutdown: Handle SIGTERM, drain connections, finish in-flight work
• Health checks: For services — liveness and readiness endpoints
• Metrics: For services — Prometheus metrics or equivalent
• Build: Reproducible build with version info (-ldflags)
• CI: go vet, staticcheck, go test -race, golangci-lint

---

Step 8: Implementation Sequence

Goal: Provide a clear order of implementation.

General Sequence (adapt per project type):

1. Define the module structure and go.mod
2. Define the core domain types and interfaces
3. Implement the inner layer (business logic / core algorithm)
4. Implement the outer layer (HTTP handlers, CLI commands, data access)
5. Wire everything together in main.go
6. Add tests at each layer
7. Add production concerns (logging, metrics, graceful shutdown)
8. Documentation (README, godoc, OpenAPI if applicable)

---

Usage

Initialize SQLC (for projects with database access)

bash /mnt/skills/user/golang-architect/scripts/sqlc-init.sh [project-dir] [db-engine]

Arguments:

• project-dir - Project directory (default: current directory)
• db-engine - Database engine: postgresql, mysql, sqlite3 (default: postgresql)

Examples:

bash /mnt/skills/user/golang-architect/scripts/sqlc-init.sh
how to use golang-architect
CursorClaude CodeClineCodexWindsurfGooseGitHub CopilotVS CodeGemini CLIKiloOpencodeKimi CLIRoo ClineAiderContinueZedBolt.newLovablev0Replit AgentSweepSmol DeveloperDevinCavemanAmpAntigravity
How to use golang-architect on Cursor
AI-first code editor with Composer
1
Prerequisites
Before installing skills in Cursor, ensure your development environment meets these requirements:
›Cursor installed and configured on your development machine
›Node.js version 16.0+ with npm package manager (verify with node --version)
›Active project directory or workspace where you want to add golang-architect
2
Execute installation command
Execute the skills CLI command in your project's root directory to begin installation:
$npx skills add https://github.com/tomlord1122/tomtom-skill --skill golang-architectcopy
The skills CLI fetches golang-architect from GitHub repository tomlord1122/tomtom-skill and configures it for Cursor.
3
Select Cursor when prompted
The CLI will show a list of available agents. Use arrow keys to navigate and space to select Cursor:
◆ Which agents do you want to install to?
│
│ ── Universal (.agents/skills) ── always included ────
│   • Amp
│   • Antigravity
│   • Cline
│   • Codex
│ ●Cursor(selected)
│   • Cursor
│   • Windsurf
4
Verify installation
Confirm successful installation by checking the skill directory location:
.cursor/skills/golang-architect
Reload or restart Cursor to activate golang-architect. Access the skill through slash commands (e.g., /golang-architect) or your agent's skill management interface.
⚠
Security & Verification Notice
We perform automated surface-level scans (Gen AI Scanner, Socket, Snyk) during installation. These checks detect common vulnerabilities but do not guarantee complete security. Always review skill source code and verify the publisher's reputation before production use.
Skills execute code in your development environment. Always verify the publisher's identity, review recent commits, and test in isolated environments before production deployment.
Additional Resources
›View source code on GitHub›Skills CLI documentation›Learn more about Cursor›What are agent skills?