Backend Development

Node.js/TypeScript and Go. PostgreSQL, Redis. REST APIs.

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)

This is a GATE. You cannot write new code until you complete this analysis.

Why This Matters

AI-generated code often duplicates existing logic because the model doesn’t “see” all relevant files. This creates:

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

Your job: Find existing code FIRST, reuse it, extend it, or extract shared logic.

Step 1: Search Comprehensively

STOP and think: Before searching, extract keywords from YOUR task:

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

Then search using YOUR task’s actual keywords:

# 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"

The goal: Find ANY existing code that does something similar to what your task needs.

Step 2: Read and Evaluate Found Code

For EACH potentially relevant file, read it and answer:

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

Before writing ANY code, you MUST output this analysis in your response:

┏━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━┓
┃ 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"]     ┃
┗━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━┛

If you skip this analysis or create code without it, the task FAILS.

Step 4: Apply Decision Matrix

🔴 Failure Conditions

Your implementation FAILS the Code Reuse Analysis if:

• 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

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

Design Principles:

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

Comments Rule: Code should be self-documenting. Only add comments when:

• 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);

See references/code-quality.md for detailed examples.

⚠️ Existing Projects Rule

ALWAYS respect existing project structure and patterns:

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)

Only apply Clean Architecture patterns to:

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

Quick Start

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

WRONG vs RIGHT:

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

Kavak-Only References

Use when working on Kavak projects.