Skip to content

notque/vexjoy-agent / skills/programming/programming

programming

Flagged

Language rules, workflows, and tooling: Go, Python, Rust, Kotlin, Swift, PHP, TypeScript type checks and debugging, OpenStack Python, MCP local-docs servers, Node.js backend APIs.

FileKindSize
SKILL.mdskill md19.3 KB
references/go/code-review.mdmarkdown12.0 KB
references/go/code-review/common-review-comments.mdmarkdown6.6 KB
references/go/concurrency.mdmarkdown11.5 KB
references/go/concurrency/concurrency-patterns.mdmarkdown5.7 KB
references/go/error-handling.mdmarkdown10.8 KB
references/go/error-handling/patterns.mdmarkdown4.2 KB
references/go/google-style-guide/SHA256SUMSother313 B
references/go/google-style-guide/UPSTREAM_REVISIONother41 B
references/go/google-style-guide/best-practices/part-01.mdmarkdown10.0 KB
references/go/google-style-guide/best-practices/part-02.mdmarkdown15.0 KB
references/go/google-style-guide/best-practices/part-03.mdmarkdown14.1 KB
references/go/google-style-guide/best-practices/part-04.mdmarkdown13.5 KB
references/go/google-style-guide/best-practices/part-05.mdmarkdown10.5 KB
references/go/google-style-guide/best-practices/part-06.mdmarkdown14.4 KB
references/go/google-style-guide/best-practices/part-07.mdmarkdown16.1 KB
references/go/google-style-guide/best-practices/part-08.mdmarkdown11.4 KB
references/go/google-style-guide/best-practices/part-09.mdmarkdown13.7 KB
references/go/google-style-guide/best-practices/part-10.mdmarkdown16.9 KB
references/go/google-style-guide/decisions/part-01.mdmarkdown15.0 KB
references/go/google-style-guide/decisions/part-02.mdmarkdown12.5 KB
references/go/google-style-guide/decisions/part-03.mdmarkdown11.5 KB
references/go/google-style-guide/decisions/part-04.mdmarkdown8.4 KB
references/go/google-style-guide/decisions/part-05.mdmarkdown9.8 KB
references/go/google-style-guide/decisions/part-06.mdmarkdown14.7 KB
references/go/google-style-guide/decisions/part-07.mdmarkdown13.3 KB
references/go/google-style-guide/decisions/part-08.mdmarkdown14.3 KB
references/go/google-style-guide/decisions/part-09.mdmarkdown15.3 KB
references/go/google-style-guide/decisions/part-10.mdmarkdown8.3 KB
references/go/google-style-guide/guide/part-01.mdmarkdown16.3 KB
references/go/google-style-guide/guide/part-02.mdmarkdown3.0 KB
references/go/google-style-guide/index.mdmarkdown8.4 KB
references/go/preferred-patterns.mdmarkdown12.5 KB
references/go/preferred-patterns/code-examples.mdmarkdown11.6 KB
references/go/quality-gate.mdmarkdown7.3 KB
references/go/quality-gate/common-lint-errors.jsonconfig7.6 KB
references/go/quality-gate/examples.mdmarkdown11.0 KB
references/go/quality-gate/makefile-targets.jsonconfig5.1 KB
references/go/sapcc-conventions.mdmarkdown34.6 KB
references/go/sapcc-conventions/api-design-detailed.mdmarkdown22.7 KB
references/go/sapcc-conventions/architecture-patterns.mdmarkdown18.6 KB
references/go/sapcc-conventions/build-ci-detailed.mdmarkdown18.7 KB
references/go/sapcc-conventions/error-handling-detailed.mdmarkdown20.1 KB
references/go/sapcc-conventions/extended-patterns.mdmarkdown7.1 KB
references/go/sapcc-conventions/go-bits-philosophy-detailed.mdmarkdown24.5 KB
references/go/sapcc-conventions/library-reference.mdmarkdown14.0 KB
references/go/sapcc-conventions/pr-mining-insights.mdmarkdown17.5 KB
references/go/sapcc-conventions/review-standards.mdmarkdown10.5 KB
references/go/sapcc-conventions/sapcc-code-patterns.mdmarkdown46.2 KB
references/go/testing.mdmarkdown9.7 KB
references/go/testing/go-benchmark-and-concurrency.mdmarkdown5.6 KB
references/go/testing/go-test-patterns.mdmarkdown9.0 KB
references/golang-general.mdmarkdown8.9 KB
references/golang-general/go-modern-code.mdmarkdown17.2 KB
references/golang-general/go-verification-workflow.mdmarkdown5.0 KB
references/golang-general/go-version-idioms.mdmarkdown6.8 KB
references/kotlin-general.mdmarkdown7.5 KB
references/kotlin-general/kotlin-patterns.mdmarkdown7.9 KB
references/kotlin-general/kotlin-security-testing.mdmarkdown4.4 KB
references/kotlin-general/kotlin-security.mdmarkdown11.1 KB
references/kotlin/concurrency-patterns.mdmarkdown5.4 KB
references/kotlin/kotlin-testing.mdmarkdown7.9 KB
references/mcp-local-docs.mdmarkdown6.9 KB
references/mcp-local-docs/mcp-patterns.mdmarkdown9.6 KB
references/mcp-local-docs/mcp-preferred-patterns.mdmarkdown6.9 KB
references/mcp-local-docs/server-templates.mdmarkdown4.4 KB
references/mcp-local-docs/typescript-async-patterns.mdmarkdown8.9 KB
references/nodejs-api.mdmarkdown7.3 KB
references/nodejs-api/auth-patterns.mdmarkdown10.0 KB
references/nodejs-api/middleware-patterns.mdmarkdown10.5 KB
references/nodejs-api/nodejs-security.mdmarkdown12.3 KB
references/nodejs-api/webhook-patterns.mdmarkdown9.9 KB
references/php-general.mdmarkdown4.7 KB
references/php-general/php-behaviors.mdmarkdown5.2 KB
references/php-general/php-conventions.mdmarkdown5.8 KB
references/php/modern-php-features.mdmarkdown4.4 KB
references/php/testing-patterns.mdmarkdown7.5 KB
references/python-general.mdmarkdown7.7 KB
references/python-general/flask-jinja-webapp.mdmarkdown5.7 KB
references/python-general/python-local-gates.mdmarkdown4.4 KB
references/python-general/python-modern-code.mdmarkdown23.1 KB
references/python-openstack.mdmarkdown5.2 KB
references/python-openstack/error-handling.mdmarkdown658 B
references/python-openstack/hacking-rules.mdmarkdown4.1 KB
references/python-openstack/openstack-patterns.mdmarkdown1.2 KB
references/python-openstack/oslo-patterns.mdmarkdown6.4 KB
references/python-openstack/output-format.mdmarkdown2.4 KB
references/python-openstack/preferred-patterns.mdmarkdown1.9 KB
references/python-openstack/rpc-versioning.mdmarkdown5.3 KB
references/rust-general.mdmarkdown8.2 KB
references/rust-general/rust-modern-code.mdmarkdown13.4 KB
references/rust-general/rust-verification-workflow.mdmarkdown5.5 KB
references/rust-general/rust-version-idioms.mdmarkdown7.0 KB
references/swift-general.mdmarkdown5.7 KB
references/swift-general/swift-patterns.mdmarkdown6.7 KB
references/swift-general/swift-security-testing.mdmarkdown6.6 KB
references/swift-general/swift-security.mdmarkdown13.3 KB
references/swift/preferred-patterns.mdmarkdown2.4 KB
references/swift/swift-testing.mdmarkdown6.6 KB
references/swift/task-patterns.mdmarkdown3.6 KB
references/typescript-debugging.mdmarkdown9.3 KB
references/typescript-debugging/debugging-workflows-async-memory.mdmarkdown5.8 KB
references/typescript-debugging/debugging-workflows.mdmarkdown5.6 KB
scripts/bench-compare.shscript7.1 KB
scripts/check-errors.shscript7.1 KB
scripts/check-interface-compliance.shscript6.4 KB
scripts/check-sapcc-auth-ordering.shscript5.5 KB
scripts/check-sapcc-httptest.shscript4.4 KB
scripts/check-sapcc-identify-endpoint.shscript5.8 KB
scripts/check-sapcc-json-strict.shscript4.9 KB
scripts/check-sapcc-time-now.shscript4.2 KB
scripts/check-sapcc-todo-format.shscript4.1 KB
scripts/gen-table-test.shscript4.2 KB
scripts/quality_checker.pyscript16.2 KB
scripts/sync-google-style-guide.pyscript2.5 KB
scripts/validate.pyscript6.3 KB

references/go/preferred-patterns.md

View on GitHub

# Go Patterns to Detect and Fix

Detect and remediate the 7 core Go failure modes: premature interface abstraction, goroutine overkill, error wrapping without context, channel misuse, generic abuse, context soup, and unnecessary function extraction. Every detection is evidence-based with code location and concrete harm explanation, and every recommendation aligns with Go proverbs and standard library conventions.

## Instructions

### Phase 1: Prepare

Read and follow the repository's CLAUDE.md before reviewing any code. Identify which files are under review and restrict all analysis to those files -- do not flag patterns in files outside the review scope.

If the user requests a full codebase scan or historical git analysis, enable those modes explicitly. Otherwise, stay within the files presented.

<!-- no-pair-required: section-header-only; individual failure modes below carry Do-instead blocks -->
### Phase 2: Scan for Patterns to Fix

Use the Quick Detection Guide to systematically check each file under review. Work through the table row by row against the code.

| Code Smell | Detection Question | If Yes |
|------------|-------------------|--------|
| Interface with one impl | Do you have 2+ implementations? | Remove interface |
| Goroutine + WaitGroup | Is work I/O bound or CPU heavy? | Use sequential loop |
| `fmt.Errorf("error: %w")` | Does wrap add context? | Add operation + ID |
| Channel for return value | Is there actual concurrency? | Use regular return |
| Generic with one type | Used with multiple types? | Use concrete type |
| Context in pure function | Does function do I/O? | Remove context param |
| Tiny extracted function | Called from 2+ places? | Inline it |

Flag complexity only when a simpler idiomatic Go alternative exists. Do not suggest adding complexity (interfaces, generics, channels, goroutines) without 2+ concrete use cases that justify it -- this is the YAGNI principle applied to Go abstractions.

### Phase 3: Classify and Report

For each detected failure mode, produce a structured report entry. Every flagged pattern must cite a specific code location and explain the concrete harm it causes -- never flag without evidence.

```
ANTI-PATTERN DETECTED:
- Pattern: [Name from AP catalog, e.g., AP-1: Premature Interface Abstraction]
- Location: [File:line]
- Issue: [What is wrong with current approach]
- Impact: [Complexity/performance/maintainability cost]
- Severity: [Low/Medium/High based on codebase context]
- Recommendation: [Simpler Go alternative]
```

Rate severity based on the actual codebase context: a single-implementation interface in a small CLI is Low; in a hot path of a shared library it may be High. Address failure modes one at a time rather than proposing bulk rewrites.

### Phase 4: Provide Remediation

For each flagged pattern, show the current code alongside the recommended alternative so the reader can compare directly. Explain WHY the current pattern is harmful, not just that it is -- root cause understanding prevents recurrence.

Reference `${CLAUDE_SKILL_DIR}/references/preferred-patterns/code-examples.md` for extended before/after examples covering all 7 failure modes.

Do not rewrite working code without an explicit request from the user. Flag patterns for awareness and let the user decide whether to act. When the user does request changes, apply them one pattern at a time to keep diffs reviewable.

If metrics collection is requested, count failure mode occurrences by type to identify systemic issues.

---

## Pattern Catalog

### AP-1: Premature Interface Abstraction

**Detection**: Interface exists with exactly one implementation.

**Why it harms Go code**:
- Interfaces should be discovered, not invented upfront
- Go philosophy: "Accept interfaces, return concrete types"
- Adds cognitive overhead without providing flexibility

**Fix**: Start with concrete types. Add interface ONLY when you need 2+ implementations (e.g., adding a mock for tests or a cache layer).

```go
// BAD: Interface before need
type UserRepository interface {
    GetUser(id string) (*User, error)
}
type PostgresUserRepository struct{ db *sql.DB }
// Only one implementation exists

// GOOD: Concrete type first
type UserRepository struct{ db *sql.DB }
func (r *UserRepository) GetUser(id string) (*User, error) { ... }
// Add interface when second implementation appears
```

### AP-2: Goroutine Overkill for Sequential Work

**Detection**: Goroutines + WaitGroup + channels for operations that are not I/O bound or CPU intensive.

**Why it harms Go code**:
- Concurrency overhead may exceed processing time
- Makes debugging harder (race conditions, unpredictable ordering)
- WaitGroup + channel + error handling adds significant complexity

**Fix**: Use a sequential loop. Add concurrency ONLY after profiling proves it helps for I/O-bound or CPU-intensive work.

```go
// BAD: Goroutines for simple iteration
errCh := make(chan error, len(items))
var wg sync.WaitGroup
for _, item := range items {
    wg.Add(1)
    go func(item Item) { defer wg.Done(); ... }(item)
}

// GOOD: Sequential is clearer
for _, item := range items {
    if err := process(item); err != nil {
        return fmt.Errorf("process item %s: %w", item.ID, err)
    }
}
```

### AP-3: Error Wrapping Without Context

**Detection**: Error wraps that add "error", "failed", or no meaningful information.

**Why it harms Go code**:
- Error messages should form a narrative from top to bottom
- Missing context makes debugging require source code inspection
- Vague wraps like "error: %w" or "failed: %w" waste the wrap

**Fix**: Include the operation being performed and relevant identifiers.

```go
// BAD: No context
return nil, fmt.Errorf("error: %w", err)
return nil, fmt.Errorf("failed: %w", err)

// GOOD: Narrative context
return nil, fmt.Errorf("load config from %s: %w", path, err)
return nil, fmt.Errorf("parse config JSON from %s: %w", path, err)
```

### AP-4: Channel Misuse for Simple Communication

**Detection**: Channels used where a return value or direct function call suffices.

**Why it harms Go code**:
- Channels are for communication between goroutines
- Without actual concurrency, channels add ceremony without benefit
- Error handling becomes awkward (need separate error channel)

**Fix**: Use standard return values. Reserve channels for worker pools, fan-out/fan-in, and event streams.

```go
// BAD: Channel for simple return
func GetUserName(id string) <-chan string {
    ch := make(chan string, 1)
    go func() { ch <- fetchUser(id).Name }()
    return ch
}

// GOOD: Direct return
func GetUserName(id string) (string, error) {
    user, err := fetchUser(id)
    if err != nil { return "", err }
    return user.Name, nil
}
```

### AP-5: Generic Abuse for Single-Use Cases

**Detection**: Type parameters used with only one concrete type instantiation.

**Why it harms Go code**:
- Generics add complexity (type parameters, constraints)
- Only valuable when you actually need multiple concrete types
- Go prioritizes simplicity over premature generalization

**Fix**: Use concrete types. Add generics when you have 2+ type instantiations for data structures, algorithms, or shared behavior.

```go
// BAD: Generic with one type
type Container[T any] struct{ value T }
// Only ever used as Container[string]

// GOOD: Concrete type
type StringContainer struct{ value string }
```

### AP-6: Context Soup

**Detection**: `context.Context` parameter in functions that perform no I/O, cancellation, or deadline checks.

**Why it harms Go code**:
- Context is for cancellation, deadlines, and request-scoped values
- In pure computation, context adds noise to signatures
- Suggests the function might do I/O when it does not

**Fix**: Reserve context for functions that do I/O, should be cancellable, or carry request-scoped values.

```go
// BAD: Context in pure function
func CalculateTotal(ctx context.Context, prices []float64) float64 { ... }

// GOOD: No context needed
func CalculateTotal(prices []float64) float64 { ... }
```

### AP-7: Unnecessary Function Extraction

**Detection**: Tiny functions (1-5 lines) called from exactly one place, extracted to satisfy complexity metrics.

**Why it harms Go code**:
- Adds indirection without adding clarity
- Reader must jump between functions to understand a simple flow
- Satisfying cyclomatic complexity tools is not a valid reason

**When TO extract**: Reused in 2+ places, complex enough to warrant its own name, needs independent testing, or represents a distinct logical operation.

**When NOT to extract**: To satisfy metrics tools, for trivial operations called once, or when the function name just describes what the code obviously does.

```go
// BAD: Extracted for metrics
func (opts AuditorOpts) parsePort() (int, error) {
    if opts.Port == "" { return 5672, nil }
    return strconv.Atoi(opts.Port)
}
// Called exactly once from buildConnectionURL

// GOOD: Inline when called once
func (opts AuditorOpts) buildConnectionURL() (string, error) {
    port := 5672
    if opts.Port != "" {
        var err error
        port, err = strconv.Atoi(opts.Port)
        if err != nil { return "", fmt.Errorf("parse port %q: %w", opts.Port, err) }
    }
    return fmt.Sprintf("amqp://%s:%d", opts.Host, port), nil
}
```

---

### AP-8: Vendored Library Contract Reversal on Major-Version Bump

**Symptom**: A bug appears immediately after bumping a vendored library across a major version. Same option name, opposite behavior between versions.

**Concrete case**: `tablewriter` v0 vs v1. `WithColumnMax(N)` means *per-cell content cap* in v0 but *fixed width per column* in v1. With many columns and a small `N`, the v1 normalizer compresses each column to 1-3 chars. Symptom: nearly-empty table with single characters visible. Fix requires `Config.Row.ColMaxWidths.Global` / `Config.Header.ColMaxWidths.Global` instead.

**Failure mode**: Assuming the option name preserves semantics across the major-version boundary. The go doc for the new version *looks* familiar, so the fix appears one-line. It isn't.

**Detection**: Any bug that appears within one commit of `go get lib@vN+1`. If the code compiled and the test suite passed but runtime output is subtly wrong (layout, formatting, ordering, unit conversions), read `$(go env GOMODCACHE)/path/to/lib@vN+1/option.go` end-to-end BEFORE patching. Do not rely on memory of the old contract; do not rely on the option name.

**Remediation**:
1. Read the option-defining file end-to-end in GOMODCACHE.
2. Enumerate every option whose name overlaps with the old version's — the ones that stayed named but changed contract are the traps.
3. Build a `/tmp` reproducer with a minimal call site to observe actual v1 behavior.
4. Confirm before/after output byte-for-byte in the reproducer before touching production code.

**Universal rule**: Option semantics live in source, not in memory. Cross-major-version bumps demand re-reading the option file.

---

## Error Handling

### Error: "False Positive -- Pattern Is Intentional"
**Cause**: Detected failure mode is actually justified by context (e.g., interface for testing boundary, generic for library API).
**Solution**: Check for 2+ implementations or concrete future need. If justified, note as acceptable trade-off and move on.

### Error: "Refactoring Breaks Tests"
**Cause**: Tests depended on the failure mode structure (e.g., mocking an interface that gets removed).
**Solution**: Update tests to use the concrete type. If removal would require major test rewrite, flag as tech debt rather than fixing immediately.

### Error: "Team Disagrees on Pattern"
**Cause**: Different Go style preferences or legacy conventions in the codebase.
**Solution**: Defer to existing codebase conventions. Flag in review comments rather than changing unilaterally. Cite Go proverbs or standard library examples as evidence.

---

## Examples

### Example 1: Code Review Detection
User says: "Review this Go service for failure modes"
Actions:
1. Scan using Quick Detection Guide table
2. Flag each detected pattern with location and severity
3. Provide before/after for highest-severity items
4. Document findings in structured report format
Result: Prioritized list of failure modes with remediation guidance

### Example 2: Specific Pattern Question
User says: "Should I add an interface for this repository?"
Actions:
1. Check how many implementations exist or are planned
2. If only one: recommend concrete type (AP-1)
3. If testing boundary: suggest consumer-side interface
4. Explain Go's "accept interfaces, return structs" philosophy
Result: Evidence-based recommendation with Go idiom context

---

## References

- `${CLAUDE_SKILL_DIR}/references/preferred-patterns/code-examples.md`: Extended before/after examples for all 7 failure modes
rea-changelog-updatemorluto/reaPrepare or rewrite REA release changelogs and GitHub release notes from pinned Git history, with verified contributor thanks and Release Please synchronization.Stars: 469kUpdated Claude CodeCodexVerifiedInstall
academy-guideanthropics/skillsStop and check this skill before finishing any reply to a question about how to use Claude or a Claude product — it recommends matching courses, tutorials, and use cases from Claude Academy (academy.claude.com), Anthropic's learning hub. Trigger on: "how do I", "how can I", "getting started with", "what can Claude do", "teach me", "learn to use"; questions about artifacts, projects, skills, plugins, connectors, MCP; requests about rolling Claude out to a team, class, or organization; and any ask for training materials, onboarding content, or learning resources. Use it when the user is learning how to use a feature or product — not when they are mid-task and just want the task done. This skill composes with other skills: after consulting product documentation to answer how a Claude feature works, also check here for a matching course or tutorial — a docs-grounded answer and an Academy recommendation belong together. Only recommend on a strong match; never invent Academy content.Stars: 197kUpdated Claude CodeCodexVerifiedInstall
claude-apianthropics/skillsReference for the Claude API / Anthropic SDK — model ids, pricing, params, streaming, tool use, MCP, agents, caching, token counting, model migration. TRIGGER — read BEFORE opening the target file; don't skip because it "looks like a one-liner" — whenever: the prompt names Claude/Anthropic in any form (Claude, Anthropic, Fable, Opus, Sonnet, Haiku, `anthropic`, `@anthropic-ai`, `claude-*`, `us.anthropic.*`, `[1m]`); the user asks about an LLM (pricing/model choice/limits/caching) — never answer from memory; OR the task is LLM-shaped with provider unstated (agent/MCP/tool-definition/multi-agent/RAG/LLM-judge/computer-use; generate/summarize/extract/classify/rewrite/converse over NL; debugging refusals/cutoffs/streaming/tool-calls/tokens). SKIP only when another provider is being worked on (overrides all triggers): OpenAI/GPT/Gemini/Llama/Mistral/Cohere/Ollama named in the query; OR `grep -rE 'openai|langchain_openai|google.generativeai|genai|mistralai|cohere|ollama'` over the project hits (run this grep FIRST if no provider named — don't Read the file).Stars: 197kUpdated Claude CodeCodexUnverifiedInstall
doc-coauthoringanthropics/skillsGuide users through a structured workflow for co-authoring documentation. Use when user wants to write documentation, proposals, technical specs, decision docs, or similar structured content. This workflow helps users efficiently transfer context, refine content through iteration, and verify the doc works for readers. Trigger when user mentions writing docs, creating proposals, drafting specs, or similar documentation tasks.Stars: 197kUpdated Claude CodeCodexVerifiedInstall