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-identification-prioritization.md

View on GitHub
# Tech Debt — Identification, Categorization, and Prioritization

Practical framework for managing technical debt in Go Gin API projects.

---

## What Is Tech Debt (And What Isn't)

**Tech debt IS:** code shortcuts taken with awareness for speed; outdated patterns that slow new feature development; missing tests for critical paths; hardcoded values; tight coupling.

**Tech debt is NOT:** code you don't like the style of; a different approach than you'd have chosen; code written by someone less experienced; features not built yet.

**Rule:** If it doesn't slow down current development or create real risk, it's not debt worth tracking.

---

## The Debt Quadrant

```
                    Deliberate                    Inadvertent
              ┌─────────────────────┬─────────────────────┐
  Reckless    │ "We know this is    │ "What's a           │
              │  wrong but ship"    │  repository pattern?"│
              │ → High priority fix │ → Training + refactor│
              ├─────────────────────┼─────────────────────┤
  Prudent     │ "Simple now,        │ "Now we know how    │
              │  refactor later"    │  it should've been" │
              │ → Schedule when     │ → Refactor when     │
              │   pain is real      │   touching the code │
              └─────────────────────┴─────────────────────┘
```

Prudent deliberate debt is OK — document it (ADR) and move on. Reckless deliberate debt compounds — fix it.

---

## Identifying Debt

### Code Signals

| Signal | Debt Type | Severity |
|---|---|---|
| `// TODO`, `// HACK`, `// FIXME` | Explicit | Check each one |
| Duplicated code blocks | DRY violation | Medium |
| Functions > 50 lines | Complexity | Low-Medium |
| No tests for business logic | Safety | High |
| Hardcoded URLs, secrets, magic numbers | Configuration | Medium-High |
| Error ignored: `_ = someFunc()` | Reliability | High |
| `fmt.Println` instead of `slog` | Observability | Low |

### Architecture Signals

| Signal | Debt Type | Severity |
|---|---|---|
| Handler contains SQL queries | Layer violation | High |
| Circular package dependencies | Coupling | High |
| No database migrations (manual DDL) | Process | High |
| No health check endpoint | Operations | Medium |
| Secrets in code or git | Security | Critical |
| No rate limiting on public endpoints | Security | High |

### Process Signals

| Signal | What It Means |
|---|---|
| Same bug appears twice | Missing test coverage |
| New devs take > 2 weeks to be productive | Poor docs or complex code |
| "Don't touch that, it works" | Technical tombstone — debt is severe |
| Deploy takes > 30 minutes | Build/CI debt |

---

## Categorizing Debt

| Category | Examples | Priority |
|---|---|---|
| **Security** | Hardcoded secrets, SQL injection, missing auth | Fix immediately |
| **Reliability** | Missing error handling, ignored errors | Sprint priority |
| **Testing** | No tests for critical paths, flaky tests | Sprint priority |
| **Architecture** | Layer violations, circular deps, coupling | Plan & schedule |
| **Code Quality** | Duplicated code, long functions, naming | Boy scout rule |
| **Documentation** | Missing API docs, no ADRs | Ongoing |

---

## Measuring Debt

### Lightweight Debt Inventory

```markdown
| ID | Description | Category | Severity | Effort | Files Affected |
|---|---|---|---|---|---|
| TD-001 | No tests for payment flow | Testing | High | 2d | internal/payment/* |
| TD-002 | User handler has SQL queries | Architecture | High | 1d | internal/handler/user.go |
| TD-003 | Duplicated validation logic | Code Quality | Medium | 0.5d | internal/handler/*.go |
```

### Effort Scoring

| Score | Meaning |
|---|---|
| XS (< 1h) | Remove dead code, fix TODO, add missing error check |
| S (1h-4h) | Extract function, add input validation, add test |
| M (1d-2d) | Split large file, add test suite, implement middleware |
| L (3d-5d) | Restructure package, implement missing layer |
| XL (1w+) | Change architecture pattern, migrate database |

---

## Prioritizing Debt

```
                High Impact
                    │
        ┌───────────┼───────────┐
        │  SCHEDULE  │  FIX NOW  │
  Low ──┼───────────┼───────────┼── High Effort
  Effort│  BOY SCOUT│  EVALUATE │
        └───────────┼───────────┘
                    │
                Low Impact
```

**Priority score = (Frequency + Severity + Spread) - Effort** — higher = fix sooner.

Score each item 1-5 on: Frequency (how often it slows someone down), Severity (how bad when it bites), Effort (how hard to fix), Spread (how many files/features affected).

---

## See Also

- `tech-debt-refactoring-communication.md` — refactoring strategies (boy scout, strangler fig, parallel change), stakeholder communication, prevention
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: 322kUpdated 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