Przejdź do treści
Biblioteka skilli
Programowanie · Budowanie i kod

go-refactoring

/go-refactoring

Prowadzi bezpieczną refaktoryzację Go bez zmiany zachowania: zmiany sprawdzane kompilatorem, wydzielanie pakietów, rozbijanie cyklicznych zależności i migracje strangler, zawsze przy zielonych testach.

Licencja
MIT
Ostatnia zmiana repozytorium
15.10.2026

Ocena i bezpieczeństwo

100/ 100Klasa: dobry
Format25 / 25
Frontmatter z nazwą i opisem, poprawna nazwa, opis do 1024 znaków, nazwa zgodna z folderem.
Odkrywalność25 / 25
Opis mówi, kiedy użyć skilla, ma sensowną długość i jest w 3. osobie.
Treść35 / 35
Co najmniej 150 słów i do 500 linii, nagłówki, listy kroków, przykłady albo kod.
Higiena15 / 15
Bez zaślepek typu TODO, bez ścieżek Windows, z licencją.
Ryzykobrak sygnałów w skanie
Pliki w paczce
2
Skrypty
0
Komentarze HTML
0
Adresy URL w SKILL.md
0
Przestarzałość

Brak sygnałów. Repozytorium zmienione 15.10.2026, bez odwołań do wycofanych modeli i API.

Licencja

MIT, otwarta: można używać i zmieniać, z zachowaniem informacji o autorze.

Co robi i kiedy

Prowadzi bezpieczną refaktoryzację Go bez zmiany zachowania: zmiany sprawdzane kompilatorem, wydzielanie pakietów, rozbijanie cyklicznych zależności i migracje strangler, zawsze przy zielonych testach.

Wyzwalacze z opisu

refactor thisrename across the codebaseextract a packagebreak this circular dependencysplit this god packagemigrate callersclean up without changing behavior
Oryginalny opis (EN)

Safe refactoring workflow for Go: behavior-preserving steps, compiler-checked renames, extracting packages, breaking circular dependencies, and strangler migrations — always behind green tests. Use when: "refactor this", "rename across the codebase", "extract a package", "break this circular dependency", "split this god package", "migrate callers", "clean up without changing behavior". Not for: choosing the target architecture (go-architecture-review), adopting new language features (go-modernize), performance rewrites (go-performance-review).

Jak działa

  1. 0. Risk, Checkpoints, and When Not To
  2. 1. The Loop
  3. 2. Renames — Let Tools Do Them
  4. 3. Extract Package
  5. 4. Break a Circular Dependency
  6. 5. Change a Function Signature Safely
  7. 6. Strangler Migration for Subsystems
  8. 7. Bulk Mechanical Rewrites
  9. 8. What Is NOT a Refactor
  10. Verification Checklist
Sekcje z nagłówków SKILL.md, w oryginale · 160 linii, 1 094 słów
Podgląd SKILL.md
---
name: go-refactoring
description: >
  Safe refactoring workflow for Go: behavior-preserving steps,
  compiler-checked renames, extracting packages, breaking circular
  dependencies, and strangler migrations — always behind green tests. Use
  when: "refactor this", "rename across the codebase", "extract a package",
  "break this circular dependency", "split this god package", "migrate
  callers", "clean up without changing behavior".
  Not for: choosing the target architecture (go-architecture-review),
  adopting new language features (go-modernize), performance rewrites
  (go-performance-review).
user-invocable: true
license: MIT
compatibility: Designed for Claude Code or similar AI coding agents working on Go projects. Requires the Go toolchain. Requires git. gopls is optional, for semantic rename.
allowed-tools: Read Edit Write Glob Grep Bash(go:*) Bash(gofmt:*) Bash(git:*) Bash(gopls:*)
metadata:
  author: eduardo-sl
  version: "1.2.0"
---

# Go Refactoring Workflow

A refactor changes structure, never behavior. The definition of done is
mechanical: same tests pass before and after every step, and every step
is small enough to revert alone.

Detailed reference material, loaded on demand:

- `references/bulk-rewrites.md` — `gofmt -r`, `//go:fix inline`, `eg`,
  `gopatch` and custom analyzers, with the verification to run after.

Read a reference file only when the summary below is not enough.

## 0. Risk, Checkpoints, and When Not To

| Risk | Transformations | Before you start |
|---|---|---|
| Low | gopls rename, extract/inline variable, organize imports | Green build and tests |
| Medium | Extract function or method, inline a call across packages, add/remove a parameter | Tests that cover every changed call site |
| High | Move types across packages, split or merge packages, break cycles, change exported API | Full safety net, and the developer's sign-off |

Stop for the developer's approval before any cross-package move, exported
API change, deletion, or change to code with no tests. Question the
refactor itself when the code is stable and nothing planned touches it,
when it is critical and untested, or when no concrete next change gets
easier.

## 1. The Loop

1. **Baseline:** `go build ./... && go test ./...` must be green before
   touching anything. If tests are missing around the target code,
   write characterization tests FIRST — they pin current behavior,
   even if that behavior looks wrong.
2. **One transformation** from the catalog below.
3. **Verify:** build + tests + `go vet ./...`.
4. **Commit.** Never mix a refactor commit with a behavior change —
   reviewers can skim a `refactor:` commit; they must scrutinize a
   mixed one.
5. Repeat.

If step 3 fails and the fix isn't obvious in a minute, revert the step
rather than debugging a half-applied transformation.

## 2. Renames — Let Tools Do Them

```bash
# Preferred: gopls (understands types, interfaces, embedding)
gopls rename -w internal/service/user.go:#offset newName

# Module path or package import path changes:
# update go.mod, then rewrite imports mechanically
find . -name '*.go' -exec sed -i 's|github.com/acme/old|github.com/acme/new|g' {} +
go build ./...   # the compiler is the reviewer
```

After a rename, grep for the old name in struct tags, templates, SQL and
anything reflection reads — gopls guards compilation, not those. Renaming
a field silently desyncs it from its `json`/`db` tag.

Never rename an exported identifier of a published library without a
deprecation cycle: add the new name, mark the old one
`// Deprecated: use NewName.`, delete in the next major version.

## 3. Extract Package

Moving code out of a god package, in compiler-checked steps:

1. Create the new package; **move one type and its methods** (`gopls`
   or cut/paste), leaving everything else.
2. In the old package, add type aliases so nothing breaks:
   `type User = user.User` (aliases, `=`, not definitions).
3. Build. Migrate importers to the new path in batches; build each batch.
4. Delete the aliases when no importer remains.

This keeps every commit green with an arbitrarily large caller base.

## 4. Break a Circular Dependency

Packages `a → b` and `b → a` won't compile; near-cycles show up as
god packages. Three escapes, in order of preference:

1. **Extract the shared core:** both `a` and `b` actually depend on a
   type — move it to a third package `c` that imports nothing.
2. **Invert with an interface:** if `store` calls back into `service`,
   define the callback interface IN `store` (consumer side) and let
   `service` implement it. The arrow flips at compile time.
3. **Merge:** if two packages can't be described without each other,
   they were one package all along.

## 5. Change a Function Signature Safely

For exported functions with many callers:

```go
// Step 1 — add the new form alongside the old
func (s *Service) ProcessCtx(ctx context.Context, id string) error { ... }

// Step 2 — old form delegates; mark deprecated
// Deprecated: use ProcessCtx.
func (s *Service) Process(id string) error {
    return s.ProcessCtx(context.Background(), id)
}

// Step 3 — migrate callers batch by batch, building each batch
// Step 4 — delete the old form (same module) or keep until next major (library)
```

On Go 1.26+, add `//go:fix inline` above the deprecated wrapper and step 3
becomes `go fix ./...` — for your module now, and for every downstream
module when it next runs `go fix`.

Inside a single module, prefer atomic signature changes when the
compiler can find every caller for you: change it, then chase the
build errors — that's the compiler enumerating your TODO list.

## 6. Strangler Migration for Subsystems

Replacing a subsystem (old store, legacy client) too big for one PR:

1. Define the consumer-side interface the callers actually need.
2. Make the OLD implementation satisfy it; wire callers to the interface.
3. Build the new implementation behind the same interface; test both
   implementations against one shared conformance test suite.
4. Switch the wiring in the composition root (one line, one commit,
   trivially revertible). Feature-flag it if risk warrants.
5. Delete the old implementation in its own commit.

## 7. Bulk Mechanical Rewrites

When the same change lands at many sites, encode it once and let a tool
apply it: `gofmt -r` for syntactic expressions, `//go:fix inline` + `go fix`
for callers of your own APIs, `eg` for type-aware expression rewrites,
`gopatch` for statements and imports, a `go/analysis` fixer for migrations
you will run again. A tool's rewrite is reviewable and re-runnable; forty
hand edits are neither. Examples: `references/bulk-rewrites.md`.

## 8. What Is NOT a Refactor

- "While I'm here" bug fixes — separate commit before or after.
- Reordering struct fields used with positional literals, changing
  exported error strings callers match on, changing JSON tags —
  these are behavior changes wearing refactor clothes.
- Rewrites without tests. If you can't pin behavior first, you're not
  refactoring; you're gambling.

## Verification Checklist

1. Baseline build + tests green before the first change
2. Characterization tests added where coverage was missing
3. Each commit is one transformation; `refactor:` commits contain no behavior change
4. Renames done via gopls/compiler, not find-and-replace on identifiers
5. Package extractions used type aliases to stay green mid-flight
6. No new dependency cycles (`go build ./...` proves it)
7. Public API changes follow the deprecation cycle
8. `go vet ./...` and the full test suite pass at every commit, not just the last
9. git log reads as a sequence of safe, revertible steps
10. High-risk steps approved by the developer before they start
11. Struct tags, templates and SQL grepped after every rename
Pliki w paczce (2)
  • SKILL.md 8 KB
  • references/bulk-rewrites.md 2 KB

Wersje

W bazie nie ma innych skilli o nazwie go-refactoring.

Identyczna treść występuje jeszcze w 1 innych folderach na GitHubie. Tu pokazujemy jedną, najlepiej ocenioną kopię.

Migawka bazy z 13.11.2026 · wersja paczki e3ef33ffc72c (skrót SHA-256 całej paczki)

Pobrania w ostatnich 30 dniach: 1 · ranking

Zgłoś problem z tym skillem: szkodliwa treść, błędny opis albo prośba autora o usunięcie.

Podobne skille

  • 100refactoring-expert
    Przeprowadza bezpieczną refaktoryzację krok po kroku z zachowaniem działania: code smells, wydzielanie funkcji, zmiany nazw, inline, odsprzęganie, uproszczenia, guard clause, kod legacy i god class.
  • 90refactor
    Przeprowadza refaktoryzację z zachowaniem działania: punkt kontrolny, wydzielanie, testy i audyt zmian.
  • 100safe-refactor
    Przebudowuje kod bez zmiany zachowania: najpierw zapisuje testy charakteryzujące, potem małe kroki sprawdzane osobno. Przydaje się przy refaktoryzacji, upraszczaniu i dzieleniu dużych plików.
  • 95refactor
    Wykonuje precyzyjną refaktoryzację kodu bez zmiany zachowania: wydzielanie funkcji, zmiana nazw, rozbijanie dużych funkcji, bezpieczeństwo typów, usuwanie zapachów kodu i wzorce projektowe, w małych krokach.
  • 95refactor
    Wykonuje precyzyjną refaktoryzację kodu bez zmiany zachowania: wydzielanie funkcji, zmiana nazw, rozbijanie dużych funkcji, bezpieczeństwo typów, usuwanie zapachów kodu i wzorce projektowe, w małych krokach.
  • 95refactoring
    Przebudowuje kod bez zmiany zachowania, sprawdzając testy przed i po każdym kroku: zmiany nazw, wydzielanie i przenoszenie.

Uwagi i zgłoszenia

Wiadomość trafi do Bartosza Sokolińskiego. Adres e-mail jest potrzebny tylko do odpowiedzi. Szczegóły w polityce prywatności.