Agent-Skills.md

Agent Skills: Backend Development

Use this skill for ANY task in a Node.js/TypeScript or Go backend codebase — adding features, fixing bugs, refactoring, adding flows, modifying handlers, changing business logic, or writing new code. Trigger even when the task is vague like "add the flow to this", "implement this feature", "fix this", or "add X like Y" — if the project has go.mod, nest-cli.json, express routes, or server-side TypeScript, this skill applies. Covers REST APIs, PostgreSQL, Redis, authentication, job queues, events, microservices, Docker, CI/CD, Clean Architecture, SOLID, DRY, and code reuse patterns. When in doubt whether this is backend work, use this skill.

UncategorizedID: carvalab/k-skills/backend-development

Repository

carvalab/k-skills
carvalab

Install this agent skill to your local

pnpm dlx add-skill https://github.com/carvalab/k-skills/tree/HEAD/skills/backend-development

Skill Files

Browse the full folder contents for backend-development.

Download Skill

Loading file tree…

skills/backend-development/SKILL.md

Skill Metadata

Name
backend-development
Description
Use this skill for ANY task in a Node.js/TypeScript or Go backend codebase — adding features, fixing bugs, refactoring, adding flows, modifying handlers, changing business logic, or writing new code. Trigger even when the task is vague like "add the flow to this", "implement this feature", "fix this", or "add X like Y" — if the project has go.mod, nest-cli.json, express routes, or server-side TypeScript, this skill applies. Covers REST APIs, PostgreSQL, Redis, authentication, job queues, events, microservices, Docker, CI/CD, Clean Architecture, SOLID, DRY, and code reuse patterns. When in doubt whether this is backend work, use this skill.

Backend Development

Backend engineering guidance for Node.js/TypeScript and Go projects. Covers everything from adding a small feature to designing a new microservice — including vague tasks where you need to figure out the right approach from context.

Related Skills:

  • kavak-documentation — for Kavak-specific patterns (kbroker, STS, GitLab CI, Docker)
  • test-driven-development — use for new features and bug fixes (Red-Green-Refactor)
  • Check .claude/CLAUDE.md or .cursor/rules/* for project-specific conventions

MCP: Use kavak-platform/platform_docs_search to query Kavak internal docs and kavak-platform/search_resource for workload/infrastructure info before implementing.

First: Understand the Codebase

Before writing any code, explore the project to understand its structure, patterns, and existing implementations. This matters because the biggest source of wasted effort is reimplementing something that already exists — or writing code that clashes with the project's established patterns.

  1. Read the project structure — identify the architecture, naming conventions, and patterns in use
  2. Search for similar code — extract keywords from your task (verbs, nouns, domain concepts) and search. You're looking for code you can reuse, extend, or extract shared logic from
  3. Document your reuse decision — REUSE (>70% similar), EXTEND (50-70%), EXTRACT (shared helper), or NEW (<30% similar)

Full process, search templates, and decision matrix: references/code-reuse-analysis.md

Core Principles

Architecture: Clean Architecture (4-layer) for new projects → references/architecture.md

  • SOLID — each module does one thing, depends on abstractions not implementations
  • DRY — every piece of business logic has ONE source of truth → references/dry-detection.md
  • YAGNI — only build what the task requires right now, not hypothetical future needs
  • KISS — the simplest solution that works is the right one

Code should be self-documenting. Comments explain "why", not "what". See references/code-quality.md for examples.

Existing Projects Rule

Follow the project's established patterns — if it uses flat structure, keep flat structure. If it uses callbacks, use callbacks. Don't force Clean Architecture on a codebase that doesn't use it. Apply good practices to new code you write, but match the project's conventions.

Clean Architecture applies to: new greenfield projects, new modules (when it fits), or explicit refactoring requests.

Quick Start

| Language | Test | Lint | | -------- | --------------- | ------------------- | | Node/TS | npm test | npm run lint | | Go | go test ./... | golangci-lint run |

Technology Selection

| Need | Choose | | ------------------ | ---------------------------------- | | TypeScript API | NestJS | | High concurrency | Go + Chi | | Go database | pgx/v5 + sqlc | | Node database | Drizzle (new), keep existing | | Go Redis | rueidis (new), keep existing | | Go job queue | River (PostgreSQL-backed) | | Node job queue | pg-boss (PostgreSQL-backed) | | Events (Kavak) | kbroker (Kafka-by-REST) | | Rate limiting | pg-boss throttle / River snooze | | Testing | Vitest (new Node), Jest (existing) | | Tracing | OpenTelemetry + dd-trace |

Note: Use kbroker for events between services. Use pg-boss (Node) or River (Go) for job queues.

Common Workflows

New API Endpoint (TDD Approach)

Use test-driven-development skill for Red-Green-Refactor cycle

  1. Write failing test first → test-driven-development skill
  2. Design endpoint → references/api-design.md
  3. Set up handler → references/go/http-handlers.md or references/node/frameworks.md
  4. Add database access → references/go/database.md or references/node/database.md
  5. Implement auth → references/authentication.md
  6. Refactor with tests passing → references/code-quality.md

Add Similar Feature (DRY-First)

When the task says "do X like Y" or "add similar to existing":

  1. Find the existing implementation first — search for the feature mentioned
  2. >70% similar: inject existing service, call its method (5-10 lines)
  3. 50-70% similar: extract shared helper, refactor both old and new to use it
  4. <50% similar: OK to create new, keep it minimal
  5. Test both old and new paths — ensure refactoring didn't break existing

If your new code exceeds 50 lines, you likely missed a reuse opportunity.

Fix Slow Query

  1. Profile query → references/debugging.md (EXPLAIN ANALYZE)
  2. Add indexes → references/performance.md
  3. Add caching → references/go/redis-queues.md or references/node/database.md

Deploy New Service

  1. Write Dockerfile → references/devops/docker.md
  2. Set up CI/CD → references/devops/ci-cd.md

Debug Production Issue

  1. Check logs/traces → references/debugging.md
  2. Profile if slow → references/debugging.md (pprof/clinic.js)
  3. Check DB queries → references/debugging.md (pg_stat_statements)

References

| Reference | When to Use | | --------------------------------------- | ---------------------------------------------------------- | | Go | | | references/go/http-handlers.md | Set up Chi routes, handlers, middleware | | references/go/database.md | Implement pgx/v5, sqlc queries | | references/go/patterns.md | Apply error handling, validation, testing | | references/go/redis-queues.md | Add rueidis caching, River job queue | | Node.js | | | references/node/frameworks.md | Set up NestJS, Express, Fastify | | references/node/database.md | Implement Drizzle, Prisma, caching | | references/node/patterns.md | Apply validation, errors, testing | | DevOps | | | references/devops/docker.md | Write Dockerfiles, compose, health checks, DataDog metrics | | references/devops/ci-cd.md | Configure GitLab CI pipelines | | Cross-Cutting | | | references/architecture.md | Clean Architecture (4-layer), microservices, events | | references/code-quality.md | SOLID, DRY, YAGNI, KISS, design patterns | | references/code-reuse-analysis.md | MANDATORY - Code reuse gate, decision matrix | | references/dry-detection.md | MANDATORY - DRY detection, code reuse patterns | | references/api-design.md | Design REST endpoints, versioning | | references/authentication.md | Implement OAuth 2.1, JWT, RBAC | | references/security.md | Apply OWASP Top 10, input validation | | references/performance.md | Optimize caching, queries, pooling | | references/testing.md | Write unit, integration, E2E tests | | references/debugging.md | Debug with logs, profilers, tracing | | Kavak | | | references/kavak/kbroker.md | Publish/subscribe events between services | | references/kavak/queues-ratelimit.md | Job queues, rate limiting with River/pg-boss | | references/kavak/microservice-auth.md | Authenticate between services (STS) | | references/kavak/gitlab-ci.md | Set up kavak-it/ci-jobs v3 pipelines | | references/kavak/docker-images.md | Build with docker-debian base | | references/kavak/workload-config.md | Configure .kavak/ dir, cron jobs | | references/kavak/logging-metrics.md | Use kvklog, kvkmetric SDKs |