1---2name: go-ecosystem-23description: This skill should be used when the user asks to "write go", "golang", "go.mod", "go module", "go test", "go build", or works with Go language development. Provides comprehensive Go ecosystem patterns and best practices.4---56<purpose>7Provide comprehensive patterns for Go language development, modules, testing, and idiomatic coding practices.8</purpose>910<tools>11<tool>Read - Analyze go.mod and Go source files</tool>12<tool>Edit - Modify Go code and module configuration</tool>13<tool>Bash - Run go build, go test, go mod commands</tool>14<tool>mcp__context7__get-library-docs - Fetch latest Go documentation</tool>15</tools>1617<concepts>18<concept name="error_values">Errors are values, not exceptions; handle explicitly at each call site with if err != nil</concept>19<concept name="interfaces">Accept interfaces, return concrete types; define interfaces where used, not implemented</concept>20<concept name="goroutines_channels">Use goroutines for concurrency, channels for communication, context.Context for cancellation</concept>21<concept name="zero_values">Zero values are meaningful (0, "", nil, false); design types so zero value is useful</concept>22</concepts>2324<go_language>25<naming_conventions>26<pattern name="packages">27<description>Lowercase, single-word names. No underscores or mixedCaps.</description>28<example>29package httputil30</example>31</pattern>3233<pattern name="exported">34<description>PascalCase for exported (public) identifiers.</description>35<example>36func ReadFile()37type Handler38var MaxRetries39</example>40</pattern>4142<pattern name="unexported">43<description>camelCase for unexported (private) identifiers.</description>44<example>45func parseConfig()46type handler47var maxRetries48</example>49</pattern>5051<pattern name="interfaces">52<description>Single-method interfaces: method name + "er" suffix.</description>53<example>54Reader, Writer, Closer, Stringer, Handler55</example>56</pattern>5758<pattern name="acronyms">59<description>Keep acronyms uppercase: URL, HTTP, ID, API.</description>60<example>61func ServeHTTP()62type HTTPClient63var userID64</example>65</pattern>6667<pattern name="getters">68<description>No "Get" prefix for getters.</description>69<example>70func (u *User) Name() string // not GetName()71</example>72</pattern>73</naming_conventions>7475<formatting>76<rules priority="standard">77<rule>Use gofmt/goimports - no manual formatting debates</rule>78<rule>Tabs for indentation, spaces for alignment</rule>79<rule>No semicolons except in for loops and multi-statement lines</rule>80<rule>Opening brace on same line as declaration</rule>81</rules>82</formatting>8384<type_system>85<pattern name="zero_values">86<description>Zero values are meaningful: 0, "", nil, false.</description>87<example>88var buf bytes.Buffer // ready to use, no initialization needed89</example>90</pattern>9192<pattern name="type_assertion">93<description>Safe type assertion with ok pattern vs unsafe panic.</description>94<example>95value, ok := x.(Type) // safe96value := x.(Type) // panics if wrong type97</example>98</pattern>99100<pattern name="type_switch">101<description>Type switch for handling multiple types.</description>102<example>103switch v := x.(type) {104case string: // v is string105case int: // v is int106default: // v is interface{}107}108</example>109</pattern>110</type_system>111</go_language>112113<error_handling>114<principles>115<principle>Errors are values, not exceptions</principle>116<principle>Handle errors explicitly at each call site</principle>117<principle>Return errors, don't panic</principle>118<principle>Add context when propagating errors</principle>119</principles>120121<pattern name="basic_check">122<description>Basic error checking pattern with context wrapping.</description>123<example>124result, err := doSomething()125if err != nil {126 return fmt.Errorf("failed to do something: %w", err)127}128</example>129</pattern>130131<pattern name="wrap_with_context">132<description>Use %w verb to wrap errors for later inspection</description>133<example>134if err != nil {135 return fmt.Errorf("processing user %s: %w", userID, err)136}137</example>138<decision_tree name="when_to_use">139<question>Do callers need to inspect or unwrap the error?</question>140<if_yes>Use %w to wrap errors for errors.Is and errors.As</if_yes>141<if_no>Use %v to format error without wrapping</if_no>142</decision_tree>143</pattern>144145<pattern name="sentinel_errors">146<description>Define package-level error variables</description>147<example>148var ErrNotFound = errors.New("not found")149var ErrInvalidInput = errors.New("invalid input")150</example>151</pattern>152153<pattern name="custom_error_type">154<description>Define custom error types implementing the error interface for structured error information.</description>155<example>156type ValidationError struct {157 Field string158 Message string159}160161func (e \*ValidationError) Error() string {162return fmt.Sprintf("validation failed for %s: %s", e.Field, e.Message)163}164</example>165</pattern>166167<pattern name="error_inspection">168<description>Inspect and unwrap errors using errors.Is and errors.As for type-safe error handling.</description>169<example>170// Check for specific error171if errors.Is(err, ErrNotFound) { ... }172173// Extract custom error type174var valErr \*ValidationError175if errors.As(err, &valErr) {176log.Printf("field: %s", valErr.Field)177}178</example>179</pattern>180181<pattern name="multiple_errors">182<description>Go 1.20+ errors.Join</description>183<example>184err := errors.Join(err1, err2, err3)185</example>186</pattern>187</error_handling>188189<interfaces>190<principles>191<principle>Accept interfaces, return concrete types</principle>192<principle>Keep interfaces small (1-3 methods)</principle>193<principle>Define interfaces where they are used, not implemented</principle>194<principle>Implicit satisfaction - no "implements" keyword</principle>195</principles>196197<common_interfaces>198<interface name="io.Reader">Read(p []byte) (n int, err error)</interface>199<interface name="io.Writer">Write(p []byte) (n int, err error)</interface>200<interface name="io.Closer">Close() error</interface>201<interface name="error">Error() string</interface>202<interface name="fmt.Stringer">String() string</interface>203</common_interfaces>204205<pattern name="interface_definition">206<description>Define interfaces with method signatures.</description>207<example>208type Handler interface {209 Handle(ctx context.Context, req Request) (Response, error)210}211</example>212<decision_tree name="when_to_use">213<question>Do you have multiple implementations or need to decouple packages?</question>214<if_yes>Define interface where it is used for abstraction</if_yes>215<if_no>Use concrete types until abstraction is needed</if_no>216</decision_tree>217</pattern>218219<pattern name="interface_composition">220<description>Compose larger interfaces from smaller ones.</description>221<example>222type ReadWriteCloser interface {223 io.Reader224 io.Writer225 io.Closer226}227</example>228</pattern>229230<pattern name="empty_interface">231<description>interface{} or any (Go 1.18+) accepts all types. Avoid when possible - loses type safety.</description>232<example>233func process(data any) { ... }234</example>235</pattern>236</interfaces>237238<modules>239<pattern name="go_mod_structure">240<description>Standard go.mod file structure with module, go version, toolchain, and dependencies.</description>241<example>242module github.com/user/project243244go 1.23245246toolchain go1.23.0247248require (249github.com/pkg/errors v0.9.1250golang.org/x/sync v0.3.0251)252253require (254golang.org/x/sys v0.10.0 // indirect255)256</example>257</pattern>258259<commands>260<tool name="go mod init">261<description>Initialize new module</description>262<use_case>Start a new Go project with module support</use_case>263</tool>264<tool name="go mod tidy">265<description>Add missing, remove unused dependencies</description>266<use_case>Clean up go.mod and go.sum files</use_case>267</tool>268<tool name="go get">269<description>Add or update dependency</description>270<param name="package-name@version">Package name and optional version</param>271<use_case>Install or update a specific package version</use_case>272</tool>273<tool name="go mod download">274<description>Download dependencies to cache</description>275<use_case>Pre-download modules for offline work</use_case>276</tool>277<tool name="go mod vendor">278<description>Create vendor directory</description>279<use_case>Copy dependencies into vendor/ for vendoring</use_case>280</tool>281<tool name="go mod verify">282<description>Verify dependencies</description>283<use_case>Check that downloaded modules haven't been modified</use_case>284</tool>285</commands>286287<pattern name="toolchain_directive">288<description>Suggest specific Go toolchain version (Go 1.21+). Used when module requires newer toolchain than default.</description>289<example>290toolchain go1.23.0291</example>292</pattern>293294<versioning>295<pattern name="semantic_import">296<description>v0.x.x and v1.x.x: no path suffix.</description>297<example>298import "github.com/user/project"299</example>300</pattern>301<pattern name="v2_plus">302<description>v2+: include version in import path.</description>303<example>304import "github.com/user/project/v2"305</example>306</pattern>307</versioning>308309<pattern name="replace_directive">310<description>Override module location for local development.</description>311<example>312replace github.com/user/lib => ../lib313replace github.com/user/lib v1.0.0 => ./local-lib314</example>315</pattern>316</modules>317318<project_structure>319<standard_layout>320<directory name="cmd/">Main applications (cmd/myapp/main.go)</directory>321<directory name="internal/">Private packages, not importable externally</directory>322<directory name="pkg/">Public library code (optional, controversial)</directory>323<directory name="api/">API definitions (OpenAPI, protobuf)</directory>324<directory name="configs/">Configuration files</directory>325<directory name="scripts/">Build/install scripts</directory>326<directory name="testdata/">Test fixtures</directory>327</standard_layout>328329<best_practices>330<practice priority="critical">cmd/myapp/main.go should be minimal - call into internal packages</practice>331<practice priority="critical">internal/ packages cannot be imported from outside parent module</practice>332<practice priority="high">Each directory = one package (except \_test packages)</practice>333</best_practices>334</project_structure>335336<testing>337<file_naming>338<pattern name="test_files">339<description>foo.go → foo_test.go</description>340</pattern>341<pattern name="test_functions">342<description>Test functions: func TestXxx(t *testing.T)</description>343</pattern>344<pattern name="benchmark_functions">345<description>Benchmark functions: func BenchmarkXxx(b *testing.B)</description>346</pattern>347<pattern name="example_functions">348<description>Example functions: func ExampleXxx()</description>349</pattern>350</file_naming>351352<pattern name="table_driven_tests">353<description>Table-driven tests for comprehensive test coverage with multiple test cases.</description>354<example>355func TestAdd(t *testing.T) {356 tests := []struct {357 name string358 a, b int359 expected int360 }{361 {"positive", 1, 2, 3},362 {"negative", -1, -2, -3},363 {"zero", 0, 0, 0},364 }365 for _, tt := range tests {366 t.Run(tt.name, func(t *testing.T) {367 if got := Add(tt.a, tt.b); got != tt.expected {368 t.Errorf("Add(%d, %d) = %d, want %d", tt.a, tt.b, got, tt.expected)369 }370 })371 }372}373</example>374<decision_tree name="when_to_use">375<question>Do you need to test same logic with multiple inputs and outputs?</question>376<if_yes>Use table-driven tests for comprehensive coverage</if_yes>377<if_no>Write simple individual test functions</if_no>378</decision_tree>379</pattern>380381<pattern name="test_helpers">382<description>Test helper functions with t.Helper() and t.Cleanup() for better test organization.</description>383<example>384func setupTestDB(t *testing.T) *DB {385 t.Helper()386 db := NewDB()387 t.Cleanup(func() { db.Close() })388 return db389}390</example>391</pattern>392393<pattern name="testdata_directory">394<description>testdata/ directory is ignored by go build and used for test fixtures.</description>395<example>396mypackage/397├── main.go398├── main_test.go399└── testdata/400 ├── input.json401 └── expected.txt402</example>403</pattern>404405<commands>406<tool name="go test">407<description>Run tests in current package</description>408<use_case>Execute tests for the current directory</use_case>409</tool>410<tool name="go test ./...">411<description>Run all tests recursively</description>412<use_case>Test entire project including subpackages</use_case>413</tool>414<tool name="go test -v">415<description>Verbose output</description>416<use_case>See detailed test execution output</use_case>417</tool>418<tool name="go test -run">419<description>Run specific test</description>420<param name="TestName">Name pattern to match</param>421<use_case>Run only tests matching the pattern</use_case>422</tool>423<tool name="go test -cover">424<description>Show coverage percentage</description>425<use_case>Get quick coverage summary</use_case>426</tool>427<tool name="go test -coverprofile">428<description>Generate coverage profile</description>429<param name="c.out">Output file path</param>430<use_case>Create detailed coverage report for analysis</use_case>431</tool>432<tool name="go test -bench">433<description>Run benchmarks</description>434<param name=".">Pattern to match (. for all)</param>435<use_case>Execute performance benchmarks</use_case>436</tool>437<tool name="go test -race">438<description>Enable race detector</description>439<use_case>Detect data races during test execution</use_case>440</tool>441</commands>442</testing>443444<concurrency>445<goroutines>446<pattern name="launch">447<description>Launch a goroutine for concurrent work.</description>448<example>449go func() {450 // concurrent work451}()452</example>453</pattern>454455<pattern name="with_waitgroup">456<description>Use sync.WaitGroup to wait for multiple goroutines to complete.</description>457<example>458var wg sync.WaitGroup459for _, item := range items {460 wg.Add(1)461 go func(item Item) {462 defer wg.Done()463 process(item)464 }(item)465}466wg.Wait()467</example>468</pattern>469</goroutines>470471<channels>472<pattern name="unbuffered">473<description>Unbuffered channels provide synchronous communication.</description>474<example>475ch := make(chan int)476</example>477</pattern>478479<pattern name="buffered">480<description>Buffered channels allow asynchronous communication up to buffer size.</description>481<example>482ch := make(chan int, 10)483</example>484</pattern>485486<pattern name="receive_only">487<description>Receive-only channel parameter.</description>488<example>489func consumer(ch <-chan int)490</example>491</pattern>492493<pattern name="send_only">494<description>Send-only channel parameter.</description>495<example>496func producer(ch chan<- int)497</example>498</pattern>499500<pattern name="select">501<description>Select statement for multiplexing channel operations.</description>502<example>503select {504case msg := <-ch1:505 handle(msg)506case ch2 <- value:507 // sent508case <-ctx.Done():509 return ctx.Err()510default:511 // non-blocking512}513</example>514</pattern>515516<pattern name="close_channel">517<description>Closing channels signals no more values will be sent.</description>518<example>519close(ch)520for v := range ch { } // receive until closed521</example>522</pattern>523</channels>524525<pattern name="context_usage">526<description>Use context.Context for cancellation and timeouts.</description>527<example>528ctx, cancel := context.WithTimeout(ctx, 5*time.Second)529defer cancel()530531select {532case result := <-doWork(ctx):533return result, nil534case <-ctx.Done():535return nil, ctx.Err()536}537</example>538</pattern>539540<sync_package>541<concept name="sync.Mutex">542<description>Mutual exclusion lock</description>543</concept>544<concept name="sync.RWMutex">545<description>Read-write lock</description>546</concept>547<concept name="sync.Once">548<description>Execute exactly once</description>549</concept>550<concept name="sync.WaitGroup">551<description>Wait for goroutine completion</description>552</concept>553<concept name="sync.Map">554<description>Concurrent map (specialized use cases)</description>555</concept>556</sync_package>557</concurrency>558559<best_practices>560<practice priority="high">Use gofmt/goimports for consistent code formatting</practice>561<practice priority="high">Handle errors explicitly at each call site</practice>562<practice priority="high">Accept interfaces, return concrete types</practice>563<practice priority="high">Keep interfaces small (1-3 methods)</practice>564<practice priority="high">Use context.Context for cancellation and timeouts</practice>565<practice priority="medium">Prefer table-driven tests for comprehensive coverage</practice>566<practice priority="medium">Use t.Helper() in test helper functions</practice>567<practice priority="medium">Run tests with -race flag to detect data races</practice>568<practice priority="medium">Define interfaces where they are used, not implemented</practice>569<practice priority="medium">Use go mod tidy regularly to maintain clean dependencies</practice>570</best_practices>571572<rules priority="critical">573<rule>Handle all errors explicitly; never ignore returned errors</rule>574<rule>Run go vet and go test before committing</rule>575<rule>Use context.Context for cancellation and timeouts in concurrent code</rule>576</rules>577578<rules priority="standard">579<rule>Use gofmt/goimports for consistent formatting</rule>580<rule>Follow Go naming conventions (exported vs unexported)</rule>581<rule>Prefer table-driven tests for comprehensive coverage</rule>582<rule>Run tests with -race flag to detect data races</rule>583</rules>584585<anti_patterns>586<avoid name="init_overuse">587<description>Overusing init() functions makes code harder to test and reason about.</description>588<instead>Prefer explicit initialization functions that can be called with parameters.</instead>589</avoid>590<avoid name="global_state">591<description>Package-level mutable variables create hidden dependencies and concurrency issues.</description>592<instead>Pass dependencies explicitly through function parameters or struct fields.</instead>593</avoid>594<avoid name="interface_pollution">595<description>Defining interfaces prematurely adds unnecessary abstraction.</description>596<instead>Define interfaces when you have multiple implementations or need to decouple packages.</instead>597</avoid>598<avoid name="naked_returns">599<description>Naked returns in long functions reduce code clarity.</description>600<instead>Use explicit return statements for functions longer than a few lines.</instead>601</avoid>602<avoid name="panic_for_errors">603<description>Using panic for recoverable errors violates Go's error handling philosophy.</description>604<instead>Return errors as values and handle them explicitly at each call site.</instead>605</avoid>606<avoid name="goroutine_leak">607<description>Goroutines that never exit waste resources and can cause memory leaks.</description>608<instead>Use context.Context or done channels to ensure goroutines can be cancelled.</instead>609</avoid>610<avoid name="data_race">611<description>Data races lead to unpredictable behavior and bugs.</description>612<instead>Use sync primitives (Mutex, RWMutex) or channels, and always run tests with -race flag.</instead>613</avoid>614<avoid name="empty_interface_overuse">615<description>Overusing interface{}/any loses type safety and requires type assertions.</description>616<instead>Use concrete types or small, focused interfaces when possible.</instead>617</avoid>618</anti_patterns>619620<context7_integration>621<description>Use Context7 MCP for up-to-date Go documentation</description>622623<go_libraries>624<library name="Go Website" id="/golang/website" trust="8.3" />625<library name="Go Tools" id="/golang/tools" trust="8.3" />626</go_libraries>627628<usage_patterns>629<pattern name="module_reference">630<description>Retrieve Go module documentation from Context7.</description>631<example>632get-library-docs context7CompatibleLibraryID="/golang/website" topic="go.mod modules"633</example>634</pattern>635</usage_patterns>636</context7_integration>637638<build_commands>639<tool name="go build">640<description>Compile package</description>641<use_case>Build executable from current package</use_case>642</tool>643<tool name="go build -o">644<description>Specify output name</description>645646<param name="name">Output binary name</param>647<use_case>Build with custom binary name</use_case>648</tool>649<tool name="go install">650<description>Compile and install to GOPATH/bin</description>651<use_case>Install package for global use</use_case>652</tool>653<tool name="go run">654<description>Compile and run</description>655<param name="main.go">Go file to execute</param>656<use_case>Quick compile and execute for development</use_case>657</tool>658<tool name="go fmt">659<description>Format all code</description>660<param name="./...">All packages recursively</param>661<use_case>Standardize code formatting</use_case>662</tool>663<tool name="go vet">664<description>Static analysis</description>665<param name="./...">All packages recursively</param>666<use_case>Detect suspicious code constructs</use_case>667</tool>668<tool name="go generate">669<description>Run code generators</description>670<use_case>Execute //go:generate directives</use_case>671</tool>672<tool name="cross-compile">673<description>Cross-compile for different platforms</description>674<example>675GOOS=linux GOARCH=amd64 go build676</example>677<use_case>Build binaries for different operating systems and architectures</use_case>678</tool>679</build_commands>680681<workflow>682<phase name="analyze">683<objective>Understand Go code requirements</objective>684<step>1. Check go.mod for module and dependencies</step>685<step>2. Review existing code patterns in project</step>686<step>3. Identify interface and struct designs</step>687</phase>688<phase name="implement">689<objective>Write idiomatic Go code</objective>690<step>1. Follow Go naming conventions</step>691<step>2. Use interfaces for abstraction</step>692<step>3. Handle errors explicitly</step>693</phase>694<phase name="validate">695<objective>Verify Go code correctness</objective>696<step>1. Run go build for compilation</step>697<step>2. Run go vet for static analysis</step>698<step>3. Run go test for testing</step>699</phase>700</workflow>701702<related_agents>703<agent name="design">Project architecture, interface design, and package structure planning</agent>704<agent name="execute">Go implementation with proper error handling and concurrency patterns</agent>705<agent name="code-quality">Run go vet, go fmt, and ensure idiomatic Go code</agent>706</related_agents>707708<related_skills>709<skill name="serena-usage">Navigate Go packages and symbol definitions efficiently</skill>710<skill name="context7-usage">Access latest Go standard library and toolchain documentation</skill>711<skill name="investigation-patterns">Debug goroutine leaks, race conditions, and performance issues</skill>712</related_skills>713714<error_escalation>715<level severity="low">716<example>Golint style warning</example>717<action>Fix style issue, maintain idiomatic code</action>718</level>719<level severity="medium">720<example>Compilation error</example>721<action>Fix error, verify with go build</action>722</level>723<level severity="high">724<example>Breaking change in exported API</example>725<action>Stop, present migration options to user</action>726</level>727<level severity="critical">728<example>Data race or unsafe memory operation</example>729<action>Block operation, require safe implementation</action>730</level>731</error_escalation>732733<constraints>734<must>Handle all errors explicitly</must>735<must>Follow Go naming conventions (exported vs unexported)</must>736<must>Use interfaces for testability</must>737<avoid>Ignoring returned errors</avoid>738<avoid>Using init() without strong justification</avoid>739<avoid>Overusing global variables</avoid>740</constraints>
majiayu000