83 lines
4.0 KiB
Markdown
83 lines
4.0 KiB
Markdown
|
---
|
||
|
|
name: language-go
|
||
|
|
description: "Go-specific code design reference for the Code Design Agent. Load only when the architecture or repository indicates Go. Covers package layout, interfaces, errors, configuration, testing, and build conventions without changing system architecture."
|
||
|
|
---
|
||
|
|
|
||
|
|
This skill provides Go-specific guidance for code-level design.
|
||
|
|
|
||
|
|
**Announce at start:** "I'm using the language-go skill to apply Go-specific code design conventions."
|
||
|
|
|
||
|
|
## When To Load
|
||
|
|
|
||
|
|
Load this skill only when one or more of the following is true:
|
||
|
|
- The architecture explicitly names Go or Golang
|
||
|
|
- The repository contains `go.mod`
|
||
|
|
- The repository contains Go packages under paths such as `cmd/`, `internal/`, or `pkg/`
|
||
|
|
|
||
|
|
Do not load this skill for non-Go projects.
|
||
|
|
|
||
|
|
## Purpose
|
||
|
|
|
||
|
|
Translate system architecture into idiomatic Go code design. This skill helps choose package boundaries, interface conventions, struct design, error handling, dependency injection, testing patterns, and build structure for Go services.
|
||
|
|
|
||
|
|
## Go Design Rules
|
||
|
|
|
||
|
|
1. Prefer small packages with clear ownership over deep technical layering
|
||
|
|
2. Prefer constructor injection and explicit dependencies
|
||
|
|
3. Keep interfaces close to the consumer when possible; do not create interfaces purely for decoration
|
||
|
|
4. Use `context.Context` as the first parameter for request-scoped operations
|
||
|
|
5. Return `error` explicitly; do not rely on panics for control flow
|
||
|
|
6. Keep domain entities free of transport and persistence concerns unless the project already uses shared structs intentionally
|
||
|
|
|
||
|
|
## Project Structure Guidance
|
||
|
|
|
||
|
|
- Use `cmd/{service}/main.go` for application entrypoints
|
||
|
|
- Use `internal/` for application-private packages
|
||
|
|
- Use `pkg/` only for genuinely reusable packages shared across binaries or modules
|
||
|
|
- Prefer feature-oriented directories when the feature has multiple layers that evolve together
|
||
|
|
- Keep generated code, mocks, and migrations in clearly named top-level or feature-local directories
|
||
|
|
|
||
|
|
## Interface Guidance
|
||
|
|
|
||
|
|
- Repository and service methods should usually accept `context.Context`
|
||
|
|
- Prefer narrow interfaces such as `UserReader` and `UserWriter` when consumers need partial behavior
|
||
|
|
- Do not define interfaces for concrete helpers unless they cross a meaningful boundary or improve testability
|
||
|
|
- Return concrete domain values from repositories/services unless pointer semantics are required by mutation or nilability
|
||
|
|
|
||
|
|
## Model Guidance
|
||
|
|
|
||
|
|
- Use domain structs for business logic, DTO structs for transport, and persistence structs only when storage mapping differs materially
|
||
|
|
- Use `time.Time` for timestamps and explicit ID types where the codebase already has a convention
|
||
|
|
- Keep JSON tags on DTOs; keep DB tags on persistence structs
|
||
|
|
- If a single struct is used across layers, justify it explicitly in the code design doc
|
||
|
|
|
||
|
|
## Error Guidance
|
||
|
|
|
||
|
|
- Prefer wrapped errors with `%w` when adding context
|
||
|
|
- Define stable error codes separately from human-readable messages
|
||
|
|
- Reserve sentinel errors for branchable states such as not found, conflict, unauthorized, and invalid input
|
||
|
|
- Map service-layer errors to transport-layer status codes explicitly
|
||
|
|
|
||
|
|
## Dependency Injection Guidance
|
||
|
|
|
||
|
|
- Default to constructor injection
|
||
|
|
- Prefer manual wiring in `cmd/` or a small `bootstrap` package unless the project already standardizes on a DI tool
|
||
|
|
- Keep wiring shallow and explicit
|
||
|
|
|
||
|
|
## Testing Guidance
|
||
|
|
|
||
|
|
- Default to table-driven tests for pure logic
|
||
|
|
- Prefer standard library testing plus a small assertion helper set unless the repository already standardizes on a framework
|
||
|
|
- Use mocks only at true boundaries such as repositories, outbound clients, or queues
|
||
|
|
- Prefer integration tests with real infrastructure for repositories and migrations when feasible
|
||
|
|
|
||
|
|
## Build Guidance
|
||
|
|
|
||
|
|
- Use a multi-stage Docker build for services
|
||
|
|
- Keep Makefile targets small and composable, for example `fmt`, `lint`, `test`, `build`, `run`
|
||
|
|
- Document required Go version from `go.mod`
|
||
|
|
|
||
|
|
## Output Constraint
|
||
|
|
|
||
|
|
This skill is reference-only. It does not create files by itself. Apply its guidance inside `docs/code-design/{date}-{feature}.md` only.
|