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/golang-general.md

View on GitHub
---
description: "General Go development: features, debugging, code review, performance. Modern Go 1.26+ (and 1.27 when go.mod allows) rules, gopls order, five-phase workflow."
type: reference
---

# General Go Development

Rules and workflow for idiomatic, production-ready Go (Go 1.26+, plus Go 1.27
idioms when `go.mod` allows them). Covers features, debugging, code review, and
performance. Task-specific depth lives in `go/` (testing, concurrency, errors,
review, SAPCC, quality gate, Google style).

Not for: "go" used as a verb ("go ahead", "go fix this"); Kotlin coroutine work
(load `kotlin-general.md`).

## Hard rules

- **Write modern Go.** Before you write or edit Go code, load
  [go-modern-code.md](golang-general/go-modern-code.md) and follow it. Code that
  builds and passes tests still fails review when it uses the old idioms listed
  there. The rules most often missed:
  - A `// Package x ...` comment in every package (including `main`) and a doc
    comment on every exported name, starting with the name.
  - `os.Exit` skips defers: `main` calls `os.Exit(run())` and `run` holds the defers.
  - Tests: `t.Context()`, never `context.Background()`; `synctest.Test` for
    anything with goroutines or time, never `time.Sleep` (import path in
    go-modern-code.md section 10).
  - `wg.Go(f)`, not `wg.Add(1)` + `go` + `defer wg.Done()`.
  - `errors.Is` for sentinels (never `==`), `errors.AsType[*T](err)` for types
    (never `errors.As` on 1.26+), typed driver errors (never string matching).
  - Standard `uuid` package on 1.27, never hand-rolled UUIDs; `slices.SortFunc`
    + `cmp.Or`, never `sort.Slice`; `slog.DiscardHandler`.
  - Let `http.ServeMux` answer 405 (it sets `Allow`); after a failed `Shutdown`,
    call `Close`.
- **Precedence over older examples.** Some `go/` deep-reference examples still
  show `wg.Add(1)` + `go`, `context.Background()` in tests, or `interface{}`.
  When `go.mod` allows the modern form, the rules above and
  go-modern-code.md win; those examples show the pattern, not the idiom.
- **Format with `gofmt -w`.** Non-negotiable: run it on every edited `.go` file.
- **After a clean `go build`, run `go vet`** to catch subtle issues.
- **Errors carry useful context.** Return an error unchanged when it is already
  clear. Add actionable context when it helps. Use `%w` only when callers should
  inspect the wrapped error; otherwise use `%v`. This Google-guide decision
  takes precedence over the blanket "always `%w`" wording in
  `go/error-handling.md`.
- **Use `any`, not `interface{}`** (Go 1.18+).
- **Pre-handoff checklist.** Before you report done, run the command sequence
  and tick the checklist in go-modern-code.md section 12. Without tools, check
  the code against each checklist line.
- **Show complete command output.** Paste actual `go test` output instead of
  "tests pass".
- **Table-driven tests** when many cases share similar test logic; keep
  distinct scenarios in separate tests when that is clearer.
- **Version-aware code.** Detect the Go version from `go.mod` and use only
  features available in that version or earlier.
- **Verify library behavior from source.** When a change depends on specific
  behavior of an imported library (commit semantics, retry logic, connection
  lifecycle, error types), read the library source in GOMODCACHE or use
  `go doc`, not protocol-level reasoning from training data. The question is not
  "how does Kafka work?" but "how does segmentio/kafka-go v0.4.47 implement this
  method?" Use `cat $(go env GOMODCACHE)/path/to/lib@version/file.go`.
- **gopls MCP first.** In a Go workspace with gopls MCP available, use its tools
  in this order, because they answer with type information grep cannot:
  1. `go_workspace` at session start, to detect the workspace
  2. `go_file_context` after the first read of any `.go` file
  3. `go_symbol_references` before modifying a symbol definition
  4. `go_diagnostics` after each edit to `.go` files
  5. `go_vulncheck` after any `go.mod` dependency change

  Fall back to the LSP tool or grep only when gopls MCP is not configured.

## Reference loading table

| Signal | Load | Why |
|---|---|---|
| go_workspace, go_diagnostics, go_symbol_references, GOMODCACHE, stale binary, stat, deadcode, render-time output, tree-sitter, cleanup, refactoring prep | [go-verification-workflow.md](golang-general/go-verification-workflow.md) | gopls MCP ordering, library-source verification, rebuilt-binary stat check, /tmp reproducer rule, deadcode false-positive fixes, hermes/log-router A/B result |
| Any task that writes or edits Go code: new package, handler, CLI, worker pool, iterator, repository, tests | [go-modern-code.md](golang-general/go-modern-code.md) | Measured failure patterns with before/after code: doc comments, errors, context, `wg.Go`, bounded pools, HTTP serve/shutdown, `uuid`, CLI flags, iterators, synctest, database/sql, pre-handoff checklist |
| interface{}, any, omitzero, omitempty, wg.Go, b.Loop, t.Context, errors.AsType, new(val), SplitSeq, uuid, CutLast, generic methods, json/v2, go.mod version, undefined:, requires go1.N | [go-version-idioms.md](golang-general/go-version-idioms.md) | Go 1.18–1.27 idiom replacement table, hard gates with fixes, error-message-to-version map |
| Testing, concurrency, error handling, review, SAPCC, `make check`, Google style | `go/*.md` (see the Go table in `SKILL.md`) | Task-specific deep references |
| Hard-gate framework | [forbidden-patterns-template.md](../../../shared-patterns/forbidden-patterns-template.md) | Shared gate format |

## Workflow

Follow these phases for every Go task. Skipping phases is the dominant cause of
regressions and death-loop debugging.

### Phase 1: Discover

Call `go_workspace` first, because gopls must index the project before any other
MCP call returns meaningful data. Then call `go_file_context` on every `.go` file
before reading it, because a stale model of package dependencies leads to the
wrong edit location.

**Gate:** `go_workspace` returned workspace metadata, and `go_file_context`
results exist for all read files.

### Phase 2: Plan

Check `go.mod` for the Go version: `for range n` on a project pinned to Go 1.21
breaks the build, and `uuid.New` on a project pinned to 1.26 fails with
`requires go1.27 or later`. Identify the failing test or compilation error,
because jumping to implementation before reproducing the failure almost always
fixes the wrong thing.

**Gate:** Go version identified; reproduction steps or failing test captured.

### Phase 3: Implement

Apply minimum-viable edits; over-engineering beyond the request is the most
common Go review rejection. Follow the Google guide's error decision: add useful
context, avoid empty wrappers such as `fmt.Errorf("failed: %w", err)`, and
expose an error chain with `%w` only when that is part of the API.

**Gate:** `go_diagnostics` returns zero errors for edited files.

### Phase 4: Verify

- Run `gofmt -w` on every edited file; unformatted Go fails CI before any logic
  review runs.
- Run `go fix -diff ./...` (Go 1.26+) and apply what it reports; modernizer
  findings mean an outdated idiom shipped.
- Run `go test -race ./...` and paste the actual output. Summarizing "tests
  pass" without evidence is the dominant rationalization that ships broken code.
- For cleanup, review, or refactoring tasks, run `deadcode ./...` after
  `go vet` to find unreachable functions. See
  [go-verification-workflow.md](golang-general/go-verification-workflow.md) for
  usage and false-positive guidance.

**Render-time fixes need render-time verification.** Bugs that show at output
render time (table layout, template output, log formatting) are not caught by
compile + `go test`. Build a small standalone reproducer under `/tmp` with
realistic fake data, run it, and compare before/after output byte for byte. Use
the module cache, not vendor pollution. No backend credentials needed.

**Rebuilt binary check.** When testing a fix to a CLI binary, confirm the binary
you run matches the fix. Compare `stat -f %m ./bin/foo` (BSD; `stat -c %Y` on
Linux) against the fix commit time, or compare the embedded version SHA against
`git rev-parse HEAD`. A stale binary silently passes tests against the old,
broken code path.

**Gate:** `go test ./...` output shown in full, `go vet ./...` clean. For
render-time fixes: reproducer output shown with a before/after diff.

### Phase 5: Report

Report exit status with real command output. No "should work": either the gates
passed or they didn't.

**Gate:** the completion report includes command output, not summaries.

## Preferred patterns

See [go-version-idioms.md](golang-general/go-version-idioms.md) for the modern
idiom replacement table, hard gates with fixes, and the error-message-to-version
map.

## Error handling

Standard Go failure modes (goroutine leaks, races, nil pointers, context
deadlines) are base-model knowledge: diagnose with `go vet`, `-race`, and
`go_diagnostics`. Verification workflows and gopls fallback guidance live in
[go-verification-workflow.md](golang-general/go-verification-workflow.md).
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: 471kUpdated 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: 198kUpdated 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: 198kUpdated 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: 198kUpdated Claude CodeCodexVerifiedInstall