Claude Code en acción

Este capítulo te guía desde abrir la terminal hasta poner en marcha una API REST de Todo completa, impulsada en todo momento por Claude Code + DeepSeek V4.

Referencia de configuración de Claude Code + DeepSeek V4:Configuración de Claude Code con DeepSeek

Primero veamos la interfaz de operación básica de Claude Code y los comandos de uso frecuente.

Inicia tu primera sesión de Claude Code

Abre la terminal, entra en cualquier directorio de trabajo (o crea una carpeta vacía) y luego escribe:

$ mkdir ejemplo-todo-api
$ cd ejemplo-todo-api
$ claude

En el primer inicio verás la pantalla de bienvenida, la información de versión y la configuración de variables de entorno de DeepSeek.

Si no estás seguro de que la configuración esté activa, escribe inmediatamente después de entrar/status, confirma que la URL base apunta ahttps://api.deepseek.com/anthropic。

Tabla de referencia rápida de comandos de barra diagonal comunes

En el cuadro de diálogo de Claude Code, los que empiezan con/son comandos integrados y no se envían al modelo.

ComandoFunción
/statusVer el modelo actual, la URL base y las estadísticas de la sesión
/helpMostrar todos los comandos disponibles
/clearBorrar el contexto de la conversación actual (no elimina archivos)
/exit o Ctrl+CSalir de Claude Code
/undoDeshacer la última modificación de archivos
/diffVer el git diff de la última modificación

Mecanismo de avisos de permisos

Cuando Claude Code se dispone a escribir archivos o ejecutar comandos, primero se detiene, enumera las operaciones que va a realizar y espera tu confirmación.

Este es el mecanismo de seguridad más importante de Claude Code; los principiantes no deben preocuparse de que la IA se descontrole y haga cambios no deseados.

Verás un aviso similar a este:

┌─────────────────────────────────────────────────┐
│  Claude wants to create the following files:     │
│                                                  │
│  • src/index.js                                  │
│  • src/routes/todos.js                           │
│  • package.json                                  │
│                                                  │
│  Allow? [Y/n]                                    │
└─────────────────────────────────────────────────┘

Presiona directamenteEntero escribeypara confirmar; escribenpara omitir.


Proyecto práctico: construye una API de Todo desde cero con IA

Esta sección te guía para que uses lenguaje natural y controles Claude Code, generando desde cero una API REST de Node.js funcional.

Objetivo del proyecto

Vamos a construir una API REST con las siguientes funciones:

EndpointFunción
GET /todosObtener todas las tareas pendientes
POST /todosCrear una nueva tarea pendiente
PUT /todos/:idActualizar una tarea pendiente (marcar como completada/modificar contenido)
DELETE /todos/:idEliminar una tarea pendiente

Stack tecnológico:Node.js + Express, los datos se guardan temporalmente en memoria (no se necesita base de datos, lo que reduce la complejidad).

Paso 1: Describe los requisitos en lenguaje natural

Escribe el siguiente contenido en el cuadro de diálogo de Claude Code (puedes copiarlo y pegarlo directamente):

请帮我从零创建一个 Node.js + Express 的 Todo REST API 项目。

要求:
- 支持 GET /todos、POST /todos、PUT /todos/:id、DELETE /todos/:id 四个接口
- 数据先存在内存数组里,不需要数据库
- 每个 todo 包含:id、title、completed(布尔值)、createdAt 字段
- 请求和响应都使用 JSON 格式
- 加上基础的错误处理(404、400 等)
- 生成一份 README.md,说明如何启动和测试接口

项目结构建议:
my-todo-api/
├── src/
│   ├── index.js       # 入口文件
│   └── routes/
│       └── todos.js   # Todo 路由
├── package.json
└── README.md

Los tres elementos para escribir un buen prompt:Contexto(informar a la IA sobre el stack tecnológico y el contexto del proyecto),Restricciones(dejar claro lo que no quieres),Salida esperada(proporcionar requisitos específicos de estructura de archivos o formato).

Paso 2: Claude Code genera la estructura de archivos

Una vez confirmados los permisos, Claude Code creará los siguientes archivos uno tras otro.

Durante el proceso de generación hay muchas confirmaciones de permisos; normalmente basta con elegir Yes:

Si tiene éxito, se mostrará una salida como la siguiente, que incluye el contenido generado, la información de inicio, etc.; es muy detallada:

Observa la estructura del proyecto generado:

package.json

Ejemplo

{
  "name": "my-todo-api",
  "version": "1.0.0",
  "description": "A simple Todo REST API built with Express",
  "main": "src/index.js",
  "scripts": {
    "start": "node src/index.js",
    "dev": "nodemon src/index.js"
  },
  "dependencies": {
    "express": "^4.18.2"
  },
  "devDependencies": {
    "nodemon": "^3.0.1"
  }
}

src/index.js (archivo de entrada)

Ejemplo

// Ruta del archivo: src/index.js
// Archivo de entrada de la API de Todo; se encarga de la configuración e inicio de la aplicación Express

const express = require('express');
const todosRouter = require('./routes/todos');

const app = express();
// Número de puerto: usa preferentemente la variable de entorno PORT; valor predeterminado 3000
const PORT = process.env.PORT || 3000;

// Middleware: analiza el cuerpo JSON de la solicitud (obligatorio; de lo contrario, req.body es undefined)
app.use(express.json());

// Registra las rutas de Todo; todas las solicitudes a las rutas /todos las gestiona todosRouter
app.use('/todos', todosRouter);

// Ruta raíz: devuelve el mensaje de bienvenida y el número de versión
app.get('/', (req, res) => {
  res.json({ message: 'Todo API is running!', version: '1.0.0' });
});

// Middleware global de manejo de errores (obligatorio; captura excepciones no controladas)
app.use((err, req, res, next) => {
  console.error(err.stack);
  res.status(500).json({ error: 'Internal Server Error' });
});

// Inicia el servicio HTTP
app.listen(PORT, () => {
  console.log(`Server is running on http://localhost:${PORT}`);
});

src/routes/todos.js (archivo de ruta principal)

Ejemplo

// Ruta del archivo: src/routes/todos.js
// Módulo de rutas de Todo, con la lógica de negocio CRUD completa

const express = require('express');
const router = express.Router();

// Almacenamiento en memoria: se usa un array para simular la base de datos
// Los datos se pierden al reiniciar el servicio; más adelante se puede sustituir por una solución persistente como SQLite
let todos = [];
// Contador de ID autoincremental
let nextId = 1;

// GET /todos — Obtener todas las tareas pendientes
router.get('/', (req, res) => {
  res.json(todos);
});

// POST /todos — Crear una nueva tarea pendiente
router.post('/', (req, res) => {
  const { title } = req.body;

  // Validación de parámetros: title es un campo obligatorio, el tipo debe ser string y no estar vacío
  if (!title || typeof title !== 'string' || title.trim() === '') {
    return res.status(400).json({ error: 'el campo title no puede estar vacío' });
  }

  // Construye un nuevo objeto todo
  const newTodo = {
    id: nextId++,                         // ID autoincremental
    title: title.trim(),                   // Elimina los espacios al inicio y al final
    completed: false,                      // El nuevo todo queda sin completar por defecto
    createdAt: new Date().toISOString(),   // Marca de tiempo con formato ISO 8601
  };

  todos.push(newTodo);
  // 201 Created indica que el recurso se creó correctamente
  res.status(201).json(newTodo);
});

// PUT /todos/:id — Actualizar una tarea pendiente
router.put('/:id', (req, res) => {
  // Convierte el parámetro de ruta de string a número
  const id = parseInt(req.params.id);
  const todo = todos.find(t => t.id === id);

  // 404: el recurso no existe
  if (!todo) {
    return res.status(404).json({ error:`Tarea pendiente con el id ${id}no encontrada`});
  }

  const { title, completed } = req.body;
  // Solo actualiza los campos recibidos; los no recibidos conservan su valor original
  if (title !== undefined) todo.title = title.trim();
  // Boolean() garantiza que completed sea siempre de tipo booleano
  if (completed !== undefined) todo.completed = Boolean(completed);

  res.json(todo);
});

// DELETE /todos/:id — Eliminar una tarea pendiente
router.delete('/:id', (req, res) => {
  const id = parseInt(req.params.id);
  const index = todos.findIndex(t => t.id === id);

  if (index === -1) {
    return res.status(404).json({ error:`Tarea pendiente con el id ${id}no encontrada`});
  }

  // Elimina del array el elemento en la posición especificada
  todos.splice(index, 1);
  // 204 No Content indica que el borrado fue correcto; el cuerpo de la respuesta está vacío
  res.status(204).send();
});

module.exports = router;

Paso 3: Revisa y confirma los cambios

Después de que Claude Code genere el código, no te apresures a ejecutarlo; adquiere el hábito de revisar.

Puedes seguir haciendo preguntas en la conversación:

你帮我生成的代码我看了一下,有几个问题想确认:
1. POST /todos 时,如果 title 是数字类型会怎么处理?
2. PUT 接口能同时更新 title 和 completed 吗?
3. 有没有对 id 不是数字的情况做处理?

Claude Code responderá una por una y puede corregir el código en el acto.

Este ciclo de «generar → cuestionar → corregir» es el ritmo esencial de la colaboración con la IA.

Paso 4: Instala las dependencias e inicia el servicio

Escribe en el cuadro de diálogo de Claude Code:

请帮我安装依赖并启动项目,然后告诉我怎么用 curl 测试每个接口

Claude Code realizará las siguientes operaciones (te pedirá confirmación en cada paso).

Instalar dependencias

$ npm install

Ejemplo de salida:

added 64 packages in 2.3s

Iniciar el servicio

$ npm start

Salida:

Server is running on http://localhost:3000

Comandos de prueba

Abre una nueva ventana de terminal y ejecuta los siguientes comandos curl en orden:

# 创建第一条 Todo
$ curl -X POST http://localhost:3000/todos \
  -H "Content-Type: application/json" \
  -d '{"title": "学习 Claude Code"}'

# 创建第二条 Todo
$ curl -X POST http://localhost:3000/todos \
  -H "Content-Type: application/json" \
  -d '{"title": "完成 DeepSeek 配置"}'

# 获取所有 Todos
$ curl http://localhost:3000/todos

# 把第一条标记为完成
$ curl -X PUT http://localhost:3000/todos/1 \
  -H "Content-Type: application/json" \
  -d '{"completed": true}'

# 删除第二条
$ curl -X DELETE http://localhost:3000/todos/2

# 再次查看列表,确认删除成功
$ curl http://localhost:3000/todos

Salida esperada (resultado final de GET /todos)

[
  {
    "id": 1,
    "title": "学习 Claude Code",
    "completed": true,
    "createdAt": "2026-05-20T10:30:00.000Z"
  }
]

¡Felicidades! Tu primera API desarrollada con asistencia de IA ya está en marcha.

Desafío avanzado: haz que Claude Code te ayude a añadir nuevas funciones

Una vez que la API esté funcionando, intenta usar lenguaje natural para que Claude Code amplíe sus funciones:

请给 Todo API 加上以下功能:
1. GET /todos 支持 ?completed=true/false 的查询参数过滤
2. GET /todos 支持 ?sort=createdAt&order=desc 的排序参数
3. 同时更新 README.md 里的接口文档

Observa cómo Claude Code entiende la estructura del código existente e inserta con precisión la nueva lógica en la posición correcta, en lugar de reescribir todo el archivo.

Esto es exactamente donde es superior a las herramientas comunes de generación de código.


CLAUDE.md: el archivo de memoria del proyecto

CLAUDE.md es el archivo de memoria a nivel de proyecto de Claude Code, que permite que la IA comprenda automáticamente las especificaciones del proyecto en cada inicio.

¿Por qué es necesario?

Claude Code se inicia "desde cero" cada vez: no recuerda lo que se dijo en la sesión anterior.

Pero si en el directorio raíz del proyecto hay unCLAUDE.mdarchivo, Claude Code lo leerá automáticamente en cada inicio, lo que equivale a darle a la IA un "manual del proyecto".

Puntos débiles sin CLAUDE.md:

  • Tener que volver a explicar cada vez "usamos Express, no Koa"
  • La IA olvida tus convenciones de nomenclatura y vuelve a generar archivos con nombres en camelCase
  • Cada miembro del equipo le dice a la IA convenciones diferentes y el estilo del código se vuelve caótico

Plantilla para escribir CLAUDE.md

Crea en el directorio raíz del proyectoCLAUDE.md, con el contenido referido a la siguiente plantilla:

# 项目说明(CLAUDE.md)

## 项目概述
这是一个 Node.js + Express 的 Todo REST API 项目。
当前阶段:数据存在内存中,下一步会迁移到 SQLite。

## 技术栈
- 运行时:Node.js 18+
- 框架:Express 4.x
- 测试:(暂无,后续加 Jest)
- 代码风格:ESLint + Prettier(配置见 .eslintrc)

## 目录结构
src/
├── index.js        # 入口,只做 app 配置和监听
└── routes/
    └── todos.js    # Todo 业务逻辑全在这里

## 命名规范
- 文件名:kebab-case(如 todo-service.js)
- 变量/函数:camelCase
- 常量:UPPER_SNAKE_CASE
- 路由文件按资源名命名(如 users.js、products.js)

## 重要约定
- 所有接口返回 JSON,错误统一格式:{ "error": "错误描述" }
- HTTP 状态码语义要准确:创建成功用 201,删除成功用 204
- 禁止在路由文件里直接操作数据库(现在是内存数组,将来是 DB)
- 每个路由文件只处理一种资源

## 禁止事项
- 不要用 var,只用 const/let
- 不要用回调风格,统一用 async/await
- 不要在代码里写中文注释(英文注释即可)
- 不要安装 lodash,原生 JS 方法够用

## 启动方式
npm start          # 生产模式
npm run dev        # 开发模式(nodemon 热重载)

## 测试接口
见 README.md 的 curl 示例

Haz que Claude Code genere CLAUDE.md automáticamente

¿No quieres escribirlo a mano? Pídele directamente a la IA que lo genere por ti:

请根据当前项目的代码结构和我们的对话记录,
帮我生成一份 CLAUDE.md 文件,
内容包括项目概述、技术栈、目录结构、命名规范和重要约定。

Claude Code analizará todos los archivos generados y organizará automáticamente un CLAUDE.md adecuado para este proyecto.

Ritmo de mantenimiento de CLAUDE.md

MomentoQué hacer
Introducir nuevas dependenciasActualizar la sección «Pila tecnológica»
Modificar la estructura de archivosActualizar la sección «Estructura de directorios»
Establecer nuevas convenciones de codificaciónAñadir a «Convenciones importantes»
Descubrir que la IA comete repetidamente el mismo errorAñadir a «Prohibiciones»

Haz commit de CLAUDE.md a Git, y así todos los miembros del equipo y la IA compartirán la misma especificación.

Esta es la infraestructura para la colaboración de equipo asistida por IA.


Resumen del capítulo

Qué aprendisteContenido correspondiente
Iniciar Claude Code y confirmar la configuración de DeepSeekIniciar una sesión y /status
Usar un prompt de tres elementos para describir los requisitosPaso 1: descripción en lenguaje natural
Revisar el código generado por la IAPaso 3: revisión y cuestionamiento
Instalar dependencias, iniciar y probar la interfaz con curlPaso 4: ejecución y pruebas
Usar CLAUDE.md para gestionar la memoria del proyectoConfiguración de CLAUDE.md
Otras extensiones