Backend Development

Related Skills:

• kavak-documentation

  - USE FIRST for Kavak-specific patterns, kbroker, STS, GitLab CI, Docker templates

• test-driven-development

  - USE PROACTIVELY for new features and bug fixes (Red-Green-Refactor)
• Check

  .claude/CLAUDE.md

  or

  .cursor/rules/*

  for project-specific conventions

MCP: Use

kavak-platform/plati_query

tool to query Kavak internal documentation before implementing.

🔴 MANDATORY: Code Reuse Analysis (GATE)

Why This Matters

• Bugs that need fixing in multiple places
• Inconsistent behavior across the codebase
• Maintenance nightmare for humans

Step 1: Search Comprehensively

1. VERBS - What actions? (create, save, send, process, calculate, update, delete, etc.)
2. NOUNS - What domain concepts? (the entities mentioned in your task)
3. OUTPUT - What type of result? (Model, Response, Event, etc.)

# Search pattern - replace KEYWORD with your actual task keywords:
grep -rn "KEYWORD" --include="*.go" --include="*.ts" . | head -50

# Search for existing services/usecases with your domain term:
grep -rn "func.*KEYWORD\|KEYWORD.*Service\|KEYWORD.*Repository" --include="*.go" . | head -30

# Use codebase_search for semantic search:
codebase_search "how does existing code [your task action]"
codebase_search "where is [your domain concept] implemented"

Step 2: Read and Evaluate Found Code

Step 3: Document Your Decision (MANDATORY - Must Output This)

┏━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━┓
┃ REUSE ANALYSIS                                                  ┃
┣━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━┫
┃ Task: [brief description of what you need to implement]         ┃
┃                                                                 ┃
┃ Keywords searched:                                              ┃
┃   - Verbs: [actual verbs you searched]                          ┃
┃   - Nouns: [actual domain terms you searched]                   ┃
┃                                                                 ┃
┃ Existing code found:                                            ┃
┃   1. [file:line] - [function name] - [what it does]             ┃
┃   2. [file:line] - [function name] - [what it does]             ┃
┃                                                                 ┃
┃ Similarity assessment:                                          ┃
┃   - [file1]: [X]% similar because [reason]                      ┃
┃                                                                 ┃
┃ Decision: [REUSE | EXTEND | EXTRACT | NEW]                      ┃
┃ Rationale: [1-2 sentences why]                                  ┃
┃ Action: [specific action - e.g., "inject existing service"]     ┃
┗━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━┛

Step 4: Apply Decision Matrix

🔴 Failure Conditions

• You create a new file >100 lines without documenting reuse analysis
• You duplicate >50% of logic from an existing file
• You copy-paste code instead of calling existing functions
• You create a new method that does the same thing as an existing one

Core Principles

references/architecture.md

• SOLID - Single Responsibility, Open/Closed, Liskov, Interface Segregation, Dependency Inversion
• DRY - Don't Repeat Yourself (extract reusable code) →

  references/dry-detection.md

• YAGNI - You Aren't Gonna Need It (don't build unused features)
• KISS - Keep It Simple, Stupid (simplest solution that works)

• Logic is complex/non-obvious (explain "why", not "what")
• Workarounds or edge cases need context
• Public API documentation (JSDoc/GoDoc)

// ❌ BAD: Obvious comment
const age = user.age; // Get user age

// ✅ GOOD: Explains WHY
// Add 1 day buffer for timezone edge cases in billing cycle
const billingDate = addDays(cycleEnd, 1);

references/code-quality.md

⚠️ Existing Projects Rule

1. Read first - Explore the codebase before making changes
2. Follow existing patterns - If project uses a pattern, continue using it
3. Don't force architecture - Don't refactor to Clean Architecture unless asked
4. Incremental improvement - Apply good practices to NEW code you write
5. Ask if unclear - When patterns conflict, ask the user

Existing project has flat structure? → Keep flat structure
Existing project has no interfaces? → Don't add interfaces everywhere
Existing project uses callbacks? → Use callbacks (unless migrating)

• New greenfield projects
• New modules/features in existing projects (when it fits)
• When explicitly asked to refactor

Quick Start

npm test

npm run lint

go test ./...

golangci-lint run

Technology Selection

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 Approach)

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

1. Find existing implementation first - search for the feature mentioned in the task
2. Analyze similarity → Is >50% of logic the same?
3. If similar, REUSE or EXTRACT:
   • >70% similar: Inject existing service, call its method
   • 50-70% similar: Extract shared helper, refactor existing to use it
   • <50% similar: OK to create new, but keep it small
4. New code should be <50 lines - if more, you probably missed reuse opportunity
5. Test both old and new paths → Ensure refactoring didn't break existing

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

references/go/http-handlers.md

references/go/database.md

references/go/patterns.md

references/go/redis-queues.md

references/node/frameworks.md

references/node/database.md

references/node/patterns.md

references/devops/docker.md

references/devops/ci-cd.md

references/architecture.md

references/code-quality.md

references/dry-detection.md

references/api-design.md

references/authentication.md

references/security.md

references/performance.md

references/testing.md

references/debugging.md

Kavak-Only References

references/kavak/kbroker.md

references/kavak/queues-ratelimit.md

references/kavak/microservice-auth.md

references/kavak/gitlab-ci.md

references/kavak/docker-images.md

references/kavak/workload-config.md

.kavak/

references/kavak/logging-metrics.md