Skip to content

henriqueatila/golang-gin-best-practices / skills/golang-gin-architect

golang-gin-architect

Verified

Software architect for Go Gin APIs. Use when making architecture decisions, evaluating complexity, designing systems, choosing patterns, or coordinating across gin skills.

FileKindSize
SKILL.mdskill md10.7 KB
metadata.jsonconfig466 B
references/adr-format-and-templates.mdmarkdown4.1 KB
references/adr-service-extraction-and-example.mdmarkdown4.0 KB
references/api-design-error-contract-docs.mdmarkdown1.8 KB
references/api-design-filtering-bulk-evolution.mdmarkdown3.8 KB
references/api-design-versioning-pagination.mdmarkdown4.3 KB
references/clean-architecture-feature-module.mdmarkdown4.5 KB
references/clean-architecture-layers-di.mdmarkdown5.2 KB
references/complexity-assessment-budget.mdmarkdown5.6 KB
references/complexity-assessment-gates.mdmarkdown4.2 KB
references/complexity-assessment-patterns.mdmarkdown5.0 KB
references/cross-cutting-health-checks.mdmarkdown1.7 KB
references/cross-cutting-observability.mdmarkdown3.9 KB
references/cross-cutting-security-config.mdmarkdown4.4 KB
references/data-ownership-boundaries.mdmarkdown4.5 KB
references/data-ownership-sync-migration.mdmarkdown4.3 KB
references/data-patterns-cqrs.mdmarkdown3.8 KB
references/data-patterns-event-sourcing-aggregate.mdmarkdown2.2 KB
references/data-patterns-event-store.mdmarkdown3.7 KB
references/data-patterns-outbox.mdmarkdown3.7 KB
references/data-patterns-read-replicas.mdmarkdown2.6 KB
references/data-patterns-saga.mdmarkdown3.6 KB
references/error-flow-domain-layers.mdmarkdown5.3 KB
references/error-flow-handler-chain.mdmarkdown4.7 KB
references/golden-main-medium-project.mdmarkdown3.0 KB
references/golden-main-medium-startup.mdmarkdown2.8 KB
references/golden-main-small-project.mdmarkdown4.0 KB
references/grpc-interop-gateway-docker.mdmarkdown2.1 KB
references/grpc-interop-server-client.mdmarkdown2.7 KB
references/grpc-interop-setup.mdmarkdown3.6 KB
references/messaging-consumer-docker.mdmarkdown1.6 KB
references/messaging-consumer-workqueues.mdmarkdown3.6 KB
references/messaging-dlq-idempotency.mdmarkdown3.1 KB
references/messaging-dlq-setup.mdmarkdown2.4 KB
references/messaging-pubsub-exchanges.mdmarkdown3.6 KB
references/messaging-rabbitmq-connection.mdmarkdown3.2 KB
references/messaging-rabbitmq-producer.mdmarkdown2.4 KB
references/object-storage-download-presign.mdmarkdown3.5 KB
references/object-storage-multipart-minio.mdmarkdown2.2 KB
references/object-storage-setup-upload.mdmarkdown4.2 KB
references/redis-cache-warming-pubsub.mdmarkdown3.2 KB
references/redis-caching-patterns.mdmarkdown4.3 KB
references/redis-session-distributed-lock.mdmarkdown3.9 KB
references/resilience-circuit-breaker-bulkhead.mdmarkdown4.3 KB
references/resilience-retry-rate-limiting.mdmarkdown4.0 KB
references/skill-orchestration-overview.mdmarkdown3.2 KB
references/skill-orchestration-workflows.mdmarkdown5.4 KB
references/system-design-bounded-contexts.mdmarkdown4.1 KB
references/system-design-c4-model.mdmarkdown4.6 KB
references/system-design-dependency-graphs.mdmarkdown2.6 KB
references/system-design-domain-modeling.mdmarkdown3.5 KB
references/system-design-project-structure.mdmarkdown4.2 KB
references/tech-debt-identification-prioritization.mdmarkdown5.1 KB
references/tech-debt-refactoring-communication.mdmarkdown4.0 KB

references/tech-debt-refactoring-communication.md

View on GitHub
# Tech Debt — Refactoring Strategies and Stakeholder Communication

Companion to `tech-debt-identification-prioritization.md` (identification, categorization, measuring, prioritizing).

---

## Refactoring Strategies

### The Boy Scout Rule

> Leave the code better than you found it.

When touching a file for a feature, fix small debt items in the same PR. Don't make a separate "cleanup PR" for trivial changes.

**Applies to:** Code quality debt (naming, dead code, small duplications).

### The Strangler Fig Pattern

Gradually replace old code with new code, routing traffic between them.

```go
// Phase 1: New handler alongside old one
r.POST("/api/v1/orders", oldHandler.CreateOrder)
r.POST("/api/v2/orders", newHandler.CreateOrder)

// Phase 2: Route percentage of traffic to new
r.POST("/api/v1/orders", func(c *gin.Context) {
    if shouldUseNew(c) { // feature flag or percentage
        newHandler.CreateOrder(c)
        return
    }
    oldHandler.CreateOrder(c)
})

// Phase 3: All traffic to new, remove old
r.POST("/api/v1/orders", newHandler.CreateOrder)
```

**Applies to:** Large rewrites where you can't do a big-bang switch.

### The Parallel Change Pattern

1. Add new code alongside old code
2. Migrate callers one by one
3. Remove old code when no callers remain

```go
// Step 1: Add new method, keep old
// Deprecated: use GetByIDV2 which returns proper errors
func (r *UserRepo) GetByID(id string) *User { ... }

func (r *UserRepo) GetByIDV2(ctx context.Context, id string) (*User, error) { ... }

// Step 2: Migrate callers to GetByIDV2
// Step 3: Delete GetByID when all callers migrated
```

**Applies to:** Interface changes, function signature changes, data model migrations.

### Dedicated Debt Sprints

Allocate 10-20% of sprint capacity to tech debt embedded in every sprint — not a separate sprint.

---

## Communicating to Stakeholders

| Tech Debt Term | Business Translation |
|---|---|
| "We have tech debt" | "New features will take longer to build" |
| "We need to refactor" | "We're investing in speed for the next 6 months" |
| "Missing tests" | "We can't guarantee changes won't break existing features" |
| "Architecture debt" | "Adding the next 3 features will cost 2x what they should" |
| "Security debt" | "We have known vulnerabilities that could be exploited" |

### Quarterly Debt Report Template

```markdown
# Tech Debt Report — Q1 2026

## Summary
- Total debt items: 23 (down from 28 last quarter)
- Critical items: 2 (security: 0, reliability: 2)
- Estimated total effort: 15 dev-days
- Items resolved this quarter: 8

## Top 5 Items (by priority score)

| # | Description | Impact | Effort | Plan |
|---|---|---|---|---|
| 1 | No tests for payment flow | High (revenue risk) | 2d | Sprint 4 |
| 2 | Manual deployment process | High (slow releases) | 3d | Sprint 5 |
| 3 | No rate limiting | High (abuse risk) | 1d | Sprint 4 |

## Recommendation
Allocate 15% of Sprint 4-5 capacity to address items #1-3.
Expected outcome: faster feature delivery and reduced incident risk.
```

---

## Prevention

### At Code Review Time

- Does this PR add complexity that isn't needed now?
- Are there tests for the happy path AND error cases?
- Is the new code consistent with existing patterns?
- Are secrets hardcoded? (auto-check with `gitleaks`)
- Does this touch a file already in the debt inventory?

### At Design Time

- Use complexity assessment before building
- Write an ADR for non-obvious decisions
- Start with the simplest pattern that works
- Set up CI/CD and tests from day one

### Automated Guards

```yaml
# .golangci.yml — catches common debt patterns
linters:
  enable:
    - errcheck      # unchecked errors
    - govet         # suspicious constructs
    - staticcheck   # bugs, simplifications
    - unused        # unused code
    - gocognit      # cognitive complexity (threshold: 30)
    - funlen        # function length (default: 60 lines)
```

**Rule:** If a linter catches it automatically, you don't need to track it as debt. Fix it or configure the linter to accept it.
brainstormingobra/superpowersYou MUST use this before any creative work - creating features, building components, adding functionality, modifying behavior, or planning anything new, in software or out of it (a talk, a business, a renovation).Stars: 323kUpdated Claude CodeCodexVerifiedInstall
brand-guidelinesanthropics/skillsApplies Anthropic's official brand colors and typography to any sort of artifact that may benefit from having Anthropic's look-and-feel. Use it when brand colors or style guidelines, visual formatting, or company design standards apply.Stars: 198kUpdated Claude CodeCodexVerifiedInstall
frontend-designanthropics/skillsGuidance for distinctive, intentional visual design when building new UI or reshaping an existing one. Helps with aesthetic direction, typography, and making choices that don't read as templated defaults.Stars: 198kUpdated Claude CodeCodexVerifiedInstall
mcp-builderanthropics/skillsGuide for creating high-quality MCP (Model Context Protocol) servers that enable LLMs to interact with external services through well-designed tools. Use when building MCP servers to integrate external APIs or services, whether in Python (FastMCP) or Node/TypeScript (MCP SDK).Stars: 198kUpdated Claude CodeCodexVerifiedInstall