Práctica Guiada: Health Endpoint con Kilocode CLI

Autor/a

Diego Saavedra

Fecha de publicación

24 de febrero de 2026

🎓 Práctica: Implementar Health Endpoint con SDD

👨‍🏫 Del Instructor: Aprender SDD leyendo es como aprender a nadar viendo videos. Vamos a practicar con un caso real: agregar un health endpoint a una API usando Kilocode CLI y Neovim.

💭 Mentalidad de Practicante: “La teoría sin práctica es entretenimiento. La práctica sin teoría es rutina. Juntas forman maestría.”

🎭 El Escenario

Eres desarrollador en un equipo que mantiene una API REST en Node.js/Express. El equipo de DevOps necesita un endpoint /health para:

Kubernetes health checks
Load balancer probes
Monitoring alerts

Tu misión: Implementar el endpoint siguiendo SDD con Kilocode CLI y Nvim.

📋 Prerrequisitos

# Crear proyecto de prueba
mkdir sdd-practice
cd sdd-practice

# Inicializar proyecto Node.js
npm init -y

# Instalar Express
npm install express

# Instalar dependencias de desarrollo
npm install --save-dev jest supertest

# Configurar script de test
npm pkg set scripts.test="jest"

Archivo Inicial: `src/app.js`

mkdir -p src
cat > src/app.js << 'EOF'
const express = require("express");
const app = express();

module.exports = app;
EOF

🔄 Fase 1: INIT

Comando CLI

kilocode "Initialize SDD in this project with openspec mode"

Output de Kilocode

Detecting project context...
- Found: package.json
- Tech stack: Node.js, Express.js
- Testing: Jest
- Architecture: REST API (minimal)

Creating openspec/ structure...
✓ openspec/config.yaml
✓ openspec/specs/
✓ openspec/changes/
✓ openspec/changes/archive/

## SDD Initialized

**Project**: sdd-practice
**Stack**: Node.js, Express.js
**Location**: openspec/

### Next Steps
Ready to start a change: kilocode "Start SDD change for <name>"

Revisar en Nvim

nvim openspec/config.yaml

🔄 Fase 2: PROPOSE

Comando CLI

kilocode "Start SDD change for add-health-endpoint"

Output

Creating change proposal...

✓ Created: openspec/changes/001-add-health-endpoint/proposal.md

## Proposal: Add Health Endpoint

### Intent
Add a /health endpoint for Kubernetes health checks.

### Scope
In: GET /health, JSON response
Out: Database checks, authentication

### Next Steps
Review proposal.md and run: kilocode "Write SDD specs"

Revisar y Editar en Nvim

nvim openspec/changes/001-add-health-endpoint/proposal.md

Contenido generado:

# Proposal: Add Health Endpoint

## Intent
Add a /health endpoint for Kubernetes health checks, load balancer 
probes, and monitoring systems.

## Scope

### In scope
- GET /health endpoint
- JSON response with status
- Basic test coverage

### Out of scope
- Database connectivity check
- External service dependencies
- Authentication

## Approach
1. Add health route to app.js
2. Return { status: "ok", timestamp }
3. Add Jest test

## Risks
- Low risk: Simple endpoint, no side effects

## Rollback
Remove the route and test if issues arise.

🔄 Fase 3: SPEC

Comando CLI

kilocode "Write SDD specs for health endpoint"

Output

Reading proposal...
Generating specifications...

✓ Created: openspec/changes/001-add-health-endpoint/spec.delta.md

## Specs Generated

- REQ-1: Health Endpoint Availability
- REQ-2: Health Response Format
- REQ-3: HTTP Status Code
- SCENARIO-1: Successful Health Check
- SCENARIO-2: Health Check Includes Timestamp

### Next Steps
Review spec.delta.md and run: kilocode "Create SDD design"

Revisar en Nvim

nvim openspec/changes/001-add-health-endpoint/spec.delta.md

Contenido:

# Spec Delta: Add Health Endpoint

## Requirements

### REQ-1: Health Endpoint Availability
The system SHALL provide a GET /health endpoint.
MUST satisfy: Endpoint responds to GET requests at /health.

### REQ-2: Health Response Format
The system SHALL return a JSON response.
MUST satisfy: Response includes status field with value "ok".
MUST satisfy: Response includes timestamp in ISO 8601 format.

### REQ-3: HTTP Status Code
The system SHALL return HTTP 200 when healthy.

## Scenarios

### SCENARIO-1: Successful Health Check
**Given** the API is running
**When** a client requests GET /health
**Then** the response status code is 200
**And** the response body contains {"status": "ok"}

### SCENARIO-2: Health Check Includes Timestamp
**Given** the API is running
**When** a client requests GET /health
**Then** the response includes a valid ISO 8601 timestamp

🔄 Fase 4: DESIGN

Comando CLI

kilocode "Create SDD design for health endpoint"

Output

Reading specs...
Creating technical design...

✓ Created: openspec/changes/001-add-health-endpoint/design.md

## Design Summary

- ADR-1: Inline route in app.js
- Response: { status: "ok", timestamp: ISO8601 }
- No authentication required

Revisar en Nvim

nvim openspec/changes/001-add-health-endpoint/design.md

🔄 Fase 5: TASKS

Comando CLI

kilocode "Break down SDD tasks for health endpoint"

Output

Generating implementation tasks...

✓ Created: openspec/changes/001-add-health-endpoint/tasks.md

## Tasks

### Phase 1: Implementation
- [ ] 1.1 Add GET /health route
- [ ] 1.2 Return JSON response

### Phase 2: Testing
- [ ] 2.1 Create test file
- [ ] 2.2 Test scenario 1
- [ ] 2.3 Test scenario 2

### Phase 3: Verification
- [ ] 3.1 Run tests
- [ ] 3.2 Verify against specs

🔄 Fase 6: APPLY

Comando CLI

kilocode "Implement SDD task 1.1 and 1.2"

Output

Implementing Phase 1 tasks...

✓ Modified: src/app.js
  - Added GET /health route
  - Returns { status: "ok", timestamp }

✓ Updated: tasks.md
  - [x] 1.1 Add GET /health route
  - [x] 1.2 Return JSON response

Revisar Código en Nvim

nvim src/app.js

Código generado:

const express = require("express");
const app = express();

app.get("/health", (req, res) => {
  res.status(200).json({
    status: "ok",
    timestamp: new Date().toISOString()
  });
});

module.exports = app;

Implementar Tests

kilocode "Implement SDD tasks 2.1, 2.2, 2.3"

Output:

Creating tests...

✓ Created: tests/health.test.js

✓ Updated: tasks.md
  - [x] 2.1 Create test file
  - [x] 2.2 Test scenario 1
  - [x] 2.3 Test scenario 2

Revisar Tests en Nvim

nvim tests/health.test.js

Contenido:

const request = require("supertest");
const app = require("../src/app");

describe("Health Endpoint", () => {
  describe("SCENARIO-1: Successful Health Check", () => {
    it("should return 200 status code", async () => {
      const response = await request(app).get("/health");
      expect(response.status).toBe(200);
    });

    it("should return status ok in response body", async () => {
      const response = await request(app).get("/health");
      expect(response.body.status).toBe("ok");
    });
  });

  describe("SCENARIO-2: Health Check Includes Timestamp", () => {
    it("should return a valid ISO 8601 timestamp", async () => {
      const response = await request(app).get("/health");
      const timestamp = response.body.timestamp;
      
      expect(timestamp).toBeDefined();
      expect(new Date(timestamp).toISOString()).toBe(timestamp);
    });
  });
});

🔄 Fase 7: VERIFY

Ejecutar Tests

npm test

Output

PASS tests/health.test.js
  Health Endpoint
    SCENARIO-1: Successful Health Check
      ✓ should return 200 status code (8 ms)
      ✓ should return status ok in response body (3 ms)
    SCENARIO-2: Health Check Includes Timestamp
      ✓ should return a valid ISO 8601 timestamp (1 ms)

Test Suites: 1 passed, 1 total
Tests:       3 passed, 3 total

Comando CLI

kilocode "Verify SDD implementation against specs"

Output

Running verification...

✓ Created: openspec/changes/001-add-health-endpoint/verification.md

## Verification Report

| Requirement | Status |
|-------------|--------|
| REQ-1 | ✅ PASS |
| REQ-2 | ✅ PASS |
| REQ-3 | ✅ PASS |

| Scenario | Status |
|----------|--------|
| SCENARIO-1 | ✅ PASS |
| SCENARIO-2 | ✅ PASS |

**Status: ✅ VERIFIED**

🔄 Fase 8: ARCHIVE

Comando CLI

kilocode "Archive SDD change"

Output

Archiving change...

✓ Merged spec.delta.md → openspec/specs/health.spec.md
✓ Moved to: openspec/changes/archive/001-add-health-endpoint/

## Archive Complete

Source of truth: openspec/specs/health.spec.md
Archive: openspec/changes/archive/001-add-health-endpoint/

📁 Estructura Final del Proyecto

tree -I node_modules

sdd-practice/
├── openspec/
│   ├── config.yaml
│   ├── specs/
│   │   └── health.spec.md          ← Source of truth
│   └── changes/
│       └── archive/
│           └── 001-add-health-endpoint/
│               ├── proposal.md
│               ├── spec.delta.md
│               ├── design.md
│               ├── tasks.md
│               └── verification.md
├── src/
│   └── app.js                      ← Implementation
├── tests/
│   └── health.test.js              ← Tests
├── package.json
└── package-lock.json

🎯 Atajos Nvim para SDD

Si configuraste los comandos de Neovim:

" Flujo rápido
<leader>si    " SDD Init
<leader>sn    " SDD New (pedirá nombre)
<leader>ss    " SDD Spec
<leader>sp    " SDD Plan/Design
<leader>st    " SDD Tasks
<leader>sm    " SDD Implement
<leader>sv    " SDD Verify
<leader>sa    " SDD Archive

🧪 Verificar el Endpoint

Crear servidor de prueba

cat > server.js << 'EOF'
const app = require("./src/app");
const PORT = 3000;

app.listen(PORT, () => {
  console.log(`Server: http://localhost:${PORT}`);
  console.log(`Health: http://localhost:${PORT}/health`);
});
EOF

Ejecutar y probar

# Terminal 1: Iniciar servidor
node server.js

# Terminal 2: Probar endpoint
curl http://localhost:3000/health | jq .

Output esperado:

{
  "status": "ok",
  "timestamp": "2026-02-24T10:30:00.000Z"
}

📊 Resumen del Flujo CLI

Fase	Comando Kilocode	Artefacto
INIT	`kilocode "Initialize SDD"`	config.yaml
PROPOSE	`kilocode "Start SDD change..."`	proposal.md
SPEC	`kilocode "Write SDD specs"`	spec.delta.md
DESIGN	`kilocode "Create SDD design"`	design.md
TASKS	`kilocode "Break down SDD tasks"`	tasks.md
APPLY	`kilocode "Implement SDD..."`	código + tests
VERIFY	`kilocode "Verify SDD..."`	verification.md
ARCHIVE	`kilocode "Archive SDD change"`	specs/ + archive/

Total: ~20 minutos para un cambio simple

🎯 Ejercicio: Tu Turno

Ahora practica tú mismo:

# Crear nuevo proyecto
mkdir sdd-practice-2 && cd sdd-practice-2
npm init -y
npm install express

# Implementar: GET /ready endpoint
# Debe verificar conexión a base de datos
# (simular con variable de entorno DB_CONNECTED=true)

# Flujo SDD completo
kilocode "Initialize SDD"
kilocode "Start SDD change for add-ready-endpoint"
# ... continuar el flujo

🎓 Lo Que Aprendiste

Kilocode CLI ejecuta SDD desde terminal
Nvim revisa y edita artefactos generados
Cada fase tiene comandos específicos
El flujo es rápido y repetible
La trazabilidad es automática

🚀 Siguiente Paso

Continúa con Módulo 6: Integración MCP para potenciar SDD con servidores MCP.

Módulo 4.0 | Duración: 60 min | Dificultad: 🟡 Intermedio

🎓 Práctica: Implementar Health Endpoint con SDD

🎭 El Escenario

📋 Prerrequisitos

Archivo Inicial: src/app.js

🔄 Fase 1: INIT

Comando CLI

Output de Kilocode

Revisar en Nvim

🔄 Fase 2: PROPOSE

Comando CLI

Output

Revisar y Editar en Nvim

🔄 Fase 3: SPEC

Comando CLI

Output

Revisar en Nvim

🔄 Fase 4: DESIGN

Comando CLI

Output

Revisar en Nvim

🔄 Fase 5: TASKS

Comando CLI

Output

🔄 Fase 6: APPLY

Comando CLI

Output

Revisar Código en Nvim

Implementar Tests

Revisar Tests en Nvim

🔄 Fase 7: VERIFY

Ejecutar Tests

Output

Comando CLI

Output

🔄 Fase 8: ARCHIVE

Comando CLI

Output

📁 Estructura Final del Proyecto

🎯 Atajos Nvim para SDD

🧪 Verificar el Endpoint

Crear servidor de prueba

Ejecutar y probar

📊 Resumen del Flujo CLI

🎯 Ejercicio: Tu Turno

🎓 Lo Que Aprendiste

🚀 Siguiente Paso

Archivo Inicial: `src/app.js`