Tu laptop lista para la tesis: guía de entorno en 6 pasos

Son las once de la noche, mañana sustentas y tu proyecto da un error que ayer no daba. Esa noche no se arregla esa noche: se evita preparando bien tu entorno desde el primer día.

Esta guía es para Windows 10 u 11. Cada paso deja algo funcionando y termina con una prueba, así sabes que puedes pasar al siguiente.

Antes de empezar

Ten a mano lo siguiente:

• Permiso para instalar programas. Si la laptop es de tu trabajo, confírmalo hoy.
• Una cuenta de GitHub con el correo verificado.
• La clave de la API del modelo de lenguaje que vayas a usar.
• Los datos de tu base: host, puerto, servicio y un usuario de solo lectura.

1. Instala Git, Python y VS Code

Abre PowerShell y comprueba que tienes winget:

winget --version

Instala las tres herramientas:

winget install --id Git.Git -e --source winget
winget install --id Python.Python.3.14 -e --source winget
winget install --id Microsoft.VisualStudioCode -e --source winget

Si winget no está disponible o tu laptop lo bloquea, usa los instaladores oficiales de Git, Python y VS Code.

Prueba: cierra PowerShell, ábrelo de nuevo y ejecuta estos comandos. Cada uno debe responder con un número de versión.

git --version
python --version
code --version

Si python abre la Microsoft Store, busca en Configuración Alias de ejecución de aplicaciones y apaga los de Python.

2. Prepara VS Code

Crea un perfil para que tus extensiones y ajustes de tesis no se mezclen con otros proyectos:

1. En el engranaje de abajo a la izquierda, entra a Profiles y luego a New Profile.
2. Ponle de nombre Tesis, elige Empty Profile y crea el perfil.

Con Ctrl+Shift+X, instala estas tres extensiones:

• ms-python.python: Python, de Microsoft.
• ms-toolsai.jupyter: Jupyter, de Microsoft.
• charliermarsh.ruff: Ruff, para ordenar tu código.

Con Ctrl+Shift+P, abre Preferences: Open User Settings (JSON) y agrega:

{
  "files.autoSave": "onFocusChange",
  "[python]": {
    "editor.defaultFormatter": "charliermarsh.ruff",
    "editor.formatOnSave": true
  }
}

Usa onFocusChange y no afterDelay, porque con afterDelay VS Code solo formatea cuando guardas a mano.

Prueba: crea hola.py con la línea de abajo y ejecútalo con el triángulo de arriba a la derecha. Si te pide un intérprete, elige Python 3.14.

print("Mi taller está listo")

Si trabajas con R, revisa cómo crear un perfil de VS Code para R.

3. Crea tu repositorio

En GitHub, crea un repositorio llamado mi-tesis. Márcalo como Private, activa el README y elige la plantilla de .gitignore para Python. Esa plantilla ya ignora .env y .venv.

Clónalo en tu laptop y ábrelo en VS Code:

git config --global user.name "Tu Nombre"
git config --global user.email "tu-correo@ejemplo.com"
git clone https://github.com/tu-usuario/mi-tesis.git
cd mi-tesis
code .

En la terminal de VS Code, crea y activa tu entorno virtual:

python -m venv .venv
.\.venv\Scripts\Activate.ps1

Si PowerShell dice que los scripts están deshabilitados, ejecuta esto y vuelve a activar el entorno:

Set-ExecutionPolicy -Scope Process -ExecutionPolicy Bypass

Instala tus librerías y guarda la lista exacta de versiones:

pip install oracledb python-dotenv pandas matplotlib ipykernel
pip freeze | Out-File requirements.txt -Encoding utf8

Crea las carpetas del proyecto:

mkdir data, docs, notebooks, src, tests

Agrega data/ al final de .gitignore para que tus datos no se suban. Git no guarda carpetas vacías, así que cada carpeta aparecerá en GitHub cuando tenga su primer archivo.

mi-tesis/
├── data/              # no se sube
├── docs/
├── notebooks/
├── src/
├── tests/
├── .env               # no se sube
├── .env.example
├── .gitignore
├── README.md
└── requirements.txt

Sube tu trabajo y lee git status antes de confirmar:

git add .
git status
git commit -m "Estructura inicial de la tesis"
git push

La primera vez, Git abre el navegador para que inicies sesión.

Prueba: refresca la página de tu repositorio y confirma que ves tus archivos, pero no .env, .venv ni data/.

Desde hoy, antes de cerrar la laptop: add, commit y push. Para practicar, tienes un ejercicio de Git paso a paso. Si prefieres autenticarte con llaves, revisa cómo usar SSH con GitHub.

4. Protege tus credenciales y prueba Oracle

Una contraseña subida a un repositorio queda en su historial, aunque luego la borres. Por eso tus credenciales van en un archivo .env en la raíz del proyecto:

ORACLE_USER=tu_usuario_de_solo_lectura
ORACLE_PASSWORD=tu_contraseña
ORACLE_DSN=host:1521/servicio
LLM_API_KEY=tu_clave

Crea también .env.example con los mismos nombres y sin valores. Ese archivo sí se sube. Luego comprueba que Git ignora el .env:

git check-ignore .env

Si el comando no responde .env, corrige tu .gitignore antes de seguir.

Mantén estas tres reglas:

• Usuario de solo lectura: una consulta equivocada no debe poder borrar nada.
• La clave de API es dinero: si tu proveedor lo permite, ponle un límite de gasto. Si se filtra, revócala y crea otra.
• Datos autorizados: antes de enviar datos a una API externa, confirma que sean públicos o que tengas autorización.

Crea src/probar_conexion.py:

import os

import oracledb
from dotenv import load_dotenv

load_dotenv()

with oracledb.connect(
    user=os.environ["ORACLE_USER"],
    password=os.environ["ORACLE_PASSWORD"],
    dsn=os.environ["ORACLE_DSN"],
) as conexion:
    print("Conectado a Oracle", conexion.version)

Prueba: con el entorno activado, ejecuta el script. Debe mostrar Conectado a Oracle y la versión de tu base.

python src/probar_conexion.py

python-oracledb se conecta en modo Thin a Oracle 12.1 o superior, sin instalar Oracle Client. Si la conexión falla, el mensaje indica por dónde empezar:

5. Agrega Claude Code con reglas

La extensión de Claude Code para VS Code necesita VS Code 1.94 o superior y un plan pago de Claude o una cuenta de Console. El plan gratuito no la incluye. Si prefieres empezar sin costo, GitHub Copilot tiene un plan gratis con límites, y estas mismas reglas te sirven.

1. Con Ctrl+Shift+X, busca Claude Code, confirma que el publicador sea Anthropic e instálala.
2. Abre un archivo, haz clic en el ícono de la chispa de arriba a la derecha e inicia sesión.
3. En el selector de modo de la caja de texto, elige Manual. Así te pedirá permiso antes de editar archivos y de correr la mayoría de comandos.

Crea un archivo CLAUDE.md en la raíz de tu proyecto. Claude lo lee al empezar cada conversación:

# Reglas del proyecto de tesis

- Explica tu plan antes de cambiar código y espera mi confirmación.
- El acceso a la base de datos es solo lectura. Nunca propongas INSERT, UPDATE, DELETE ni DDL.
- No inventes cifras: todo dato debe salir de una consulta.
- No leas ni muestres el archivo .env.
- Haz cambios pequeños y explícame cómo probarlos.
- Yo redacto la tesis. Tú no escribes capítulos.

Crea .claude/settings.json para bloquear la lectura de tus credenciales:

{
  "permissions": {
    "deny": ["Read(./.env)"]
  }
}

Esta regla reduce el riesgo, pero no cubre todos los comandos. Tus contraseñas nunca van en el chat.

Prueba: pídele que explique en tres líneas qué hace src/probar_conexion.py.

La regla de trabajo es simple: si no puedes explicar un cambio con tus palabras, no lo aceptes. Revisa también qué permite tu universidad sobre el uso de IA y decláralo si te lo piden.

6. Busca fuentes reales y cita con Zotero

Un chat general puede inventar una referencia que parece perfecta. Por eso, nada entra a tu tesis si no lo abriste.

Busca en inglés y en español, y revisa cuántos años de antigüedad acepta tu universidad.

Para instalar Zotero:

1. Cierra Word.
2. Instala la aplicación y el conector de tu navegador. El plugin de Word viene incluido.
3. Crea tu cuenta y activa la sincronización para respaldar tu biblioteca.
4. Crea las colecciones Antecedentes y Bases teóricas. Dentro de Antecedentes, crea Nacionales e Internacionales.

Para guardar una fuente, ábrela en el navegador y haz clic en el conector. Revisa su ficha: si el título o el autor entraron mal, la cita saldrá mal.

Para citar en Word:

1. En la pestaña Zotero, elige Add/Edit Citation.
2. La primera vez, selecciona American Psychological Association 7th edition.
3. Escribe el apellido del autor y presiona Enter.
4. Pon el cursor donde va tu lista de referencias y elige Add/Edit Bibliography.

Prueba: inserta una cita y genera la bibliografía. Agrega otra cita y confirma que la lista se actualiza.

Lista final

• git, python y code responden con su versión
• VS Code tiene el perfil Tesis y sus tres extensiones
• Tu repositorio privado está en GitHub, sin .env ni data/
• requirements.txt tiene las versiones exactas
• git check-ignore .env responde .env
• src/probar_conexion.py muestra Conectado a Oracle
• Claude Code tiene CLAUDE.md y el modo Manual
• Zotero inserta citas y bibliografía en APA 7

Si vas a usar Conda, por ejemplo para trabajar con R, revisa cómo crear un environment para ciencia de datos.

Fuentes

• Claude Code en VS Code y permisos de Claude Code
• Solución de errores de python-oracledb
• Perfiles de VS Code
• Plantilla .gitignore de Python
• Integración de Zotero con procesadores de texto