Bruno-Cunha-Souza/ValarMindSkills / skills/clean-code
clean-code
VerifiedClean code lifecycle for Go/Rust/TypeScript/Bun/Python — writing, reviewing, refactoring. Naming, functions, DRY, code smells, duplication (literal/logical/structural), dead-code removal with false-positive guardrails, safe refactoring. Triggers: 'clean code', 'código limpo', 'refactor', 'refatorar', 'remove duplication', 'remover duplicação', 'dead code', 'código morto', 'code smells', '/clean-code'.
| File | Kind | Size |
|---|---|---|
| SKILL.md | skill md | 16.9 KB |
| references/BUN.md | markdown | 9.7 KB |
| references/DEAD_CODE.md | markdown | 11.0 KB |
| references/DUPLICATION.md | markdown | 6.9 KB |
| references/GOLANG.md | markdown | 7.3 KB |
| references/PATTERNS.md | markdown | 7.8 KB |
| references/PRINCIPLES.md | markdown | 3.0 KB |
| references/PYTHON.md | markdown | 13.6 KB |
| references/RUST.md | markdown | 9.3 KB |
| references/TYPESCRIPT.md | markdown | 10.8 KB |
references/GOLANG.md
View on GitHub# Go — Clean Code Reference
> Language-specific companion for the [clean-code](../SKILL.md) skill. Covers Go idioms, tooling, smells, and refactoring patterns.
## Tools
| Tool | Purpose | Install / Run |
|------|---------|---------------|
| `golangci-lint` | Meta-linter (runs 50+ linters) | `go install github.com/golangci/golangci-lint/cmd/golangci-lint@latest` |
| `staticcheck` | Advanced static analysis | `go install honnef.co/go/tools/cmd/staticcheck@latest` |
| `go vet` | Built-in correctness checks | Included with Go |
| `gofumpt` | Stricter `gofmt` | `go install mvdan.cc/gofumpt@latest` |
| `gocritic` | Opinionated style linter | Included in `golangci-lint` |
| `govulncheck` | Known vulnerability scanner | `go install golang.org/x/vuln/cmd/govulncheck@latest` |
### Quick Audit
```bash
# Full lint sweep
golangci-lint run ./...
# Static analysis
staticcheck ./...
# Built-in vet checks (shadow, printf, structtag, etc.)
go vet ./...
# Find unused code
go install golang.org/x/tools/cmd/deadcode@latest
deadcode ./...
# Check test coverage
go test -coverprofile=cover.out ./...
go tool cover -func=cover.out | tail -1
```
## Go-Specific Smells
### 1. Stuttering Names
Package name is repeated in the exported symbol.
```diff
# Bad — user.UserName stutters
- package user
- type UserService struct{}
- func (s *UserService) GetUserByID(userID string) (*UserRecord, error)
# Good — package provides context
+ package user
+ type Service struct{}
+ func (s *Service) ByID(id string) (*Record, error)
```
**Detect:** `rg 'type [A-Z]\w+' --type go -o | while read -r line; do pkg=$(dirname "$line" | xargs basename); type=$(echo "$line" | grep -oP 'type \K\w+'); echo "$pkg → $type"; done | grep -i -E '(\w+).*\1'`
### 2. Empty Interface Abuse
Using `interface{}` / `any` when a concrete type or constrained generic exists.
```diff
# Bad — loses type safety
- func Process(data any) any {
# Good — typed
+ func Process(data Request) Response {
# Good — constrained generic
+ func Process[T Processable](data T) Result[T] {
```
**Detect:** `rg 'interface\{\}|func.*\bany\b' --type go`
### 3. init() Abuse
Hidden side effects that run at import time — hard to test, hard to reason about.
```diff
# Bad — global state set at import
- var db *sql.DB
- func init() {
- var err error
- db, err = sql.Open("postgres", os.Getenv("DB_URL"))
- if err != nil { log.Fatal(err) }
- }
# Good — explicit initialization
+ func NewDB(dsn string) (*sql.DB, error) {
+ return sql.Open("postgres", dsn)
+ }
```
**Detect:** `rg 'func init\(\)' --type go`
### 4. Naked Returns
Named return values with bare `return` — obscures what's being returned.
```diff
# Bad — what does this return?
- func parse(input string) (result int, err error) {
- // ... 40 lines ...
- return
- }
# Good — explicit
+ func parse(input string) (int, error) {
+ // ... 40 lines ...
+ return result, nil
+ }
```
**Detect:** `rg -U 'func \w+\([^)]*\)\s*\([^)]*\)\s*\{[\s\S]*?\breturn\s*\n' --type go --multiline`
### 5. Error String Formatting
Error strings should not be capitalized or end with punctuation (they compose with `fmt.Errorf`).
```diff
# Bad — capitalized, punctuation
- return fmt.Errorf("Failed to connect to database.")
# Good — lowercase, no punctuation
+ return fmt.Errorf("connecting to database: %w", err)
```
**Detect:** `rg 'fmt\.Errorf\("[A-Z]' --type go` and `rg 'errors\.New\("[A-Z]' --type go`
### 6. Package-Level Mutable Globals
Shared mutable state makes testing and concurrency unsafe.
```diff
# Bad — mutable global
- var config = loadConfig()
- var logger = log.New(os.Stdout, "", log.LstdFlags)
# Good — dependency injection
+ type Server struct {
+ config Config
+ logger *slog.Logger
+ }
```
**Detect:** `rg '^var \w+ =' --type go | grep -v '_test.go' | grep -v 'const\|sync\.Once\|Mutex'`
### 7. Oversized Interfaces
Interfaces with too many methods — violates Interface Segregation Principle.
```diff
# Bad — consumers forced to implement 10 methods
- type Repository interface {
- Create(ctx context.Context, u User) error
- Update(ctx context.Context, u User) error
- Delete(ctx context.Context, id string) error
- FindByID(ctx context.Context, id string) (*User, error)
- FindByEmail(ctx context.Context, email string) (*User, error)
- List(ctx context.Context, filter Filter) ([]User, error)
- Count(ctx context.Context) (int, error)
- // ... more
- }
# Good — small, focused interfaces
+ type UserReader interface {
+ FindByID(ctx context.Context, id string) (*User, error)
+ FindByEmail(ctx context.Context, email string) (*User, error)
+ }
+ type UserWriter interface {
+ Create(ctx context.Context, u User) error
+ Update(ctx context.Context, u User) error
+ }
```
**Detect:** `rg -U 'type \w+ interface \{' --type go -A 20 | awk '/interface \{/{name=$2; count=0} /^\s+\w+\(/{count++} /\}/{if(count>5) print name": "count" methods"}'`
## Go Refactoring Patterns
### Table-Driven Tests
Eliminates duplicated test logic.
```diff
# Before: duplicated test functions
- func TestAdd_positives(t *testing.T) {
- if Add(1, 2) != 3 { t.Error("expected 3") }
- }
- func TestAdd_negatives(t *testing.T) {
- if Add(-1, -2) != -3 { t.Error("expected -3") }
- }
- func TestAdd_zero(t *testing.T) {
- if Add(0, 0) != 0 { t.Error("expected 0") }
- }
# After: table-driven
+ func TestAdd(t *testing.T) {
+ tests := []struct {
+ name string
+ a, b int
+ want int
+ }{
+ {"positives", 1, 2, 3},
+ {"negatives", -1, -2, -3},
+ {"zero", 0, 0, 0},
+ }
+ for _, tt := range tests {
+ t.Run(tt.name, func(t *testing.T) {
+ if got := Add(tt.a, tt.b); got != tt.want {
+ t.Errorf("Add(%d, %d) = %d, want %d", tt.a, tt.b, got, tt.want)
+ }
+ })
+ }
+ }
```
### Functional Options
Replaces long constructor parameter lists.
```diff
# Before: constructor with 6 parameters
- func NewServer(addr string, port int, timeout time.Duration,
- maxConns int, logger *slog.Logger, tls *tls.Config) *Server {
# After: functional options
+ type Option func(*Server)
+
+ func WithTimeout(d time.Duration) Option {
+ return func(s *Server) { s.timeout = d }
+ }
+ func WithMaxConns(n int) Option {
+ return func(s *Server) { s.maxConns = n }
+ }
+ func WithLogger(l *slog.Logger) Option {
+ return func(s *Server) { s.logger = l }
+ }
+
+ func NewServer(addr string, opts ...Option) *Server {
+ s := &Server{addr: addr, timeout: 30 * time.Second, maxConns: 100}
+ for _, opt := range opts {
+ opt(s)
+ }
+ return s
+ }
+
+ // Usage
+ srv := NewServer(":8080", WithTimeout(5*time.Second), WithLogger(logger))
```
### Accept Interfaces, Return Structs
Decouples callers from concrete implementations.
```diff
# Bad — accepts concrete type
- func SaveReport(db *sql.DB, r Report) error {
# Good — accepts interface defined by consumer
+ type ReportWriter interface {
+ ExecContext(ctx context.Context, query string, args ...any) (sql.Result, error)
+ }
+ func SaveReport(w ReportWriter, r Report) error {
```
## Go Verification Commands
```bash
# Run tests
go test ./...
# Run tests with race detector
go test -race ./...
# Check exported API hasn't changed
go doc ./pkg/...
# Vet for correctness
go vet ./...
# Full lint
golangci-lint run ./...
```
Related skills
| Skill | Stars | Updated | Works with | Status | Install |
|---|---|---|---|---|---|
| receiving-code-reviewobra/superpowersUse when receiving code review feedback, before implementing suggestions, especially if feedback seems unclear or technically questionable - requires technical rigor and verification, not performative agreement or blind implementation | Stars: 322k | Updated | Claude CodeCodex | Verified | Install |
| requesting-code-reviewobra/superpowersUse when completing tasks, implementing major features, or before merging to verify work meets requirements | Stars: 322k | Updated | Claude CodeCodex | Verified | Install |
| using-git-worktreesobra/superpowersUse when starting feature work that needs isolation from current workspace or before executing implementation plans - ensures an isolated workspace exists via native tools or git worktree fallback | Stars: 322k | Updated | Claude CodeCodex | Verified | Install |
| verification-before-completionobra/superpowersUse when about to claim work is complete, fixed, or passing, before committing or creating PRs - requires running verification commands and confirming output before making any success claims; evidence before assertions always | Stars: 322k | Updated | Claude CodeCodex | Verified | Install |