Plantilla de Onboarding — Guía de incorporación

Plantilla genérica del método para incorporar a un dev nuevo en CUALQUIER proyecto (placeholders {{DEV_NAME}}, {{PROJECT_NAME}}, etc. que rellena el lead siguiendo el lead-checklist).

Implementación concreta de CreaRackSL — fuente única: [[workspace—onboarding—setup-equipo-nuevo]] (instalación desde cero) + las fichas por rol onboarding-edu / onboarding-dani / onboarding-txell (contenido específico de cada uno, sin duplicar el setup).

Antes de empezar

Necesitarás:

• Acceso de colaborador en GitHub al repo del proyecto y al repo claude-method (lectura).
• Cuenta Claude Code (Max o similar).
• Acceso al workspace MCP del equipo (se configurará en Paso 5).

Pide al lead del proyecto que te invite a los dos repos y confirme tu acceso MCP.

Paso 1 — Herramientas necesarias

1. Git: https://git-scm.com/download/win
2. Docker Desktop: https://www.docker.com/products/docker-desktop/
3. Node.js 18+: https://nodejs.org/
4. pnpm: npm install -g pnpm
5. PowerShell 7+: winget install Microsoft.PowerShell
6. GitHub CLI: winget install GitHub.cli
7. Claude Code CLI: npm install -g @anthropic-ai/claude-code
8. Editor: VS Code recomendado

Verificar:

git --version
docker --version
node --version
pnpm --version
pwsh --version
gh --version
claude --version

Paso 2 — Clonar repositorios

mkdir C:\dev
cd C:\dev
git clone {{REPO_URL}}
git clone {{WORKSPACE_URL}}
git clone https://github.com/{{ORG}}/claude-method.git

Deberías tener tres carpetas:

• C:\dev\{{PROJECT_NAME}} — proyecto
• C:\dev\{{WORKSPACE_NAME}} — workspace con shared-memory específico
• C:\dev\claude-method — harness reusable

Paso 3 — Ejecutar onboarding automatizado

El lead del proyecto te habrá dado un Bearer token personal. Este token permite que Claude Code sincronice el hot cache del proyecto al arrancar cada sesión.

Opción A — Bootstrap desde máquina vacía (recomendado en Windows Proxmox nuevas)

Si no has clonado los repos todavía, un solo comando lo hace todo: prereqs check + clone 3 repos + setup Claude Code + install hooks en ambos repos.

irm https://raw.githubusercontent.com/{{ORG}}/claude-method/main/onboarding/bootstrap-profile.ps1 -OutFile $env:TEMP\bootstrap-profile.ps1

& $env:TEMP\bootstrap-profile.ps1 `
    -DevName "{{DEV_NAME}}" `
    -DevRole "{{DEV_ROLE}}" `
    -BibToken "TU_BEARER_TOKEN_AQUI" `
    -GitUserName "{{DEV_NAME}}" `
    -GitUserEmail "{{GIT_EMAIL}}" `
    -GitHubUsername "{{GITHUB_USERNAME}}"

-GitUserName/-GitUserEmail configuran la identidad de git. Sin ella git commit falla en silencio y el backup de memoria queda staged sin subir (lección s82).

Opción B — Setup directo (si ya tienes los repos clonados)

cd C:\dev\claude-method\onboarding
.\setup-claude-code.ps1 `
    -DevName "{{DEV_NAME}}" `
    -ProjectDir "C:\dev\{{PROJECT_NAME}}" `
    -WorkspaceDir "C:\dev\{{WORKSPACE_NAME}}" `
    -DevRole "{{DEV_ROLE}}" `
    -McpUrl "https://workspace.crearack.com/api/mcp" `
    -BibToken "TU_BEARER_TOKEN_AQUI" `
    -GitUserName "{{DEV_NAME}}" `
    -GitUserEmail "{{GIT_EMAIL}}" `
    -GitHubUsername "{{GITHUB_USERNAME}}"

Qué hace el setup

• Configura settings.json de Claude Code: permisos completos, 4 hooks SessionStart (s60) [auto-pull + hot-cache + timezone-sync + claude-method auto-sync], language, effortLevel, additionalDirectories, skipDangerousModePermissionPrompt.
• Copia memorias genéricas de claude-method/ a tu perfil.
• Copia memorias específicas del workspace (override en caso de colisión).
• Crea tu perfil de usuario + MEMORY.md.
• Guarda BIB_MCP_TOKEN (+ desde s57 CF_ACCESS_CLIENT_ID/SECRET) en variables User de Windows.
• Añade 4º hook SessionStart claude-method auto-sync (s60): pulea claude-method y propaga global-agents/ + global-skills/ a ~/.claude/ en cada sesión.
• Copia global-agents/ (design-collaborator) + global-skills/ (14 skills design-*) a ~/.claude/{agents,skills} (paso 4c).
• Registra el MCP server via .mcp.json local con 3 headers (Bearer + 2 CF Access).
• Instala el harness pre-commit (4 checks: arquitectural + Biblioteca + wiki schema + astro schemas).
• Limpia plugins obsoletos.

Paso 4 — Arrancar el entorno local

cd C:\dev\{{PROJECT_NAME}}
{{START_CMD}}

Verificar en {{DEV_URL}}.

Paso 5 — Primera sesión con Claude Code

cd C:\dev\{{PROJECT_NAME}}
claude

Claude leerá CLAUDE.md automáticamente. Verifica:

Pregunta: ¿has cargado las memorias del equipo al iniciar? ¿Qué hay en el MCP?

Si algo falla:

• claude mcp list — verifica el MCP registrado.
• ~/.claude/settings.json para confirmar hooks.
• ~/.claude/projects/*/memory/MEMORY.md para confirmar memorias.

Paso 6 — Harness Engineering

Cuatro controles automáticos antes de cada commit:

• Check arquitectural (pre_commit_check.py): LOC, SQL injection, |safe en templates, settings críticos, formatter gemelo del CI (Regla 18).
• Check de Biblioteca (bib_report_check.py): exige bib_report_change en últimos 10 min para archivos de código modificados. Bloquea commit si falta.
• Check wiki schema (wiki_front_matter_check.py): páginas Supercontexto deben tener front-matter válido.
• Check Astro schema (check_astro_schemas.py): si cambia content.config.ts o src/content/, corre pnpm astro sync.

Bypass puntual (con motivo documentado en mensaje commit):

$env:BIB_SKIP=1; git commit -m "..."

Reinstalar:

cd C:\dev\{{PROJECT_NAME}}
bash C:/dev/claude-method/harness/install_hooks.sh

Paso 7 — Supercontexto del workspace

Panel compartido: https://workspace.crearack.com/biblioteca/pulse

Vista en vivo de actividad 24h, tareas, alertas activas, salud del grafo, commits 7 días.

Hot cache personal: Claude entra “caliente” a cada sesión gracias al hook SessionStart.

Comandos MCP desde Claude:

• bib_context_query(topic="X") — briefing.
• bib_impact_query(file_path="X") — qué docs afecta un cambio.
• bib_report_change(file_path, change_type) — antes de commitear código modificado.

Paso 8 — Flujo de trabajo diario

Inicio de sesión

cd C:\dev\{{PROJECT_NAME}}
claude

Los 4 hooks SessionStart (s60) se ejecutan en orden: (1) git pull --rebase origin main del repo activo. (2) hot-cache-sync.ps1 refresca project_hot_cache.md. (3) timezone-sync inyecta [Local time] + TZ Europe/Madrid. (4) claude-method-sync.ps1 -SkipHook -SkipMemory pulea claude-method y propaga global-agents/ + global-skills/ a ~/.claude/. Si Edu o Dani subieron un agente/skill nuevo via claude-method-promote.ps1, lo recibes ahora.

Reglas duras

1. Biblioteca primero — primera llamada bib_ask(question="..."). No grep asumiendo significado.
2. Verificar CI tras push — gh run list --limit 1. Si rojo, arreglar antes de cerrar tarea.
3. HTTP 200 != éxito — al llamar APIs, desenvolver body y detectar errors[].
4. [skip ci] solo en commits 100% docs — si toca código, nunca.
5. Infraestructura nunca en el PC personal — SPOF, migrar a servidor compartido.
6. Pre-commit y CI validan lo mismo — si aparece check en CI, debe estar en claude-method/harness/pre_commit_check.py (fuente única: el hook lo ejecuta desde ahí).

Tests

{{TEST_CMD}}

Backup de memorias (dual: OneDrive + GitHub)

Tu carpeta ~/.claude/projects/<project>/memory/ NO está en git. Backup dual automático (ritual “Apaga”, paso 8):

powershell -ExecutionPolicy Bypass -File C:/dev/claude-method/harness/claude-backup.ps1 -PushGit

.zip a OneDrive (CLAUDE_BACKUP_ROOT) + memoria en texto al repo {{ORG}}/claude-backups (carpeta por persona). Recuperar en PC nuevo: claude-backup.ps1 -Restore -FromGit -Name <persona>.

Sincronizar claude-method

Desde s60 es automático: el 4º hook SessionStart ejecuta claude-method-sync.ps1 -SkipHook -SkipMemory al arrancar cada sesión Claude Code. Pulea claude-method y propaga global-agents/ + global-skills/. No tienes que hacer nada.

Si necesitas forzar el sync fuera de una sesión Claude Code:

powershell -ExecutionPolicy Bypass -File C:/dev/claude-method/harness/claude-method-sync.ps1

Ascender un agente o skill local al método central (s60)

Si creaste un agente en ~/.claude/agents/ o una skill en ~/.claude/skills/ y lo quieres compartir con el resto del staff:

pwsh -NoProfile -File C:/dev/claude-method/harness/claude-method-promote.ps1 `
    -Type {agent|skill} -Name <slug>

Detecta CREATE/UPDATE/IDENTICAL, valida frontmatter, copia + commit + push directo a claude-method/main. Los demás miembros reciben en su próxima sesión via el 4º hook. Modos: -DryRun, -NoCommit, -NoPush, -Force. Convención humana: antes de invocar, “¿esto es transversal o solo del proyecto?” — si es del proyecto, va en <repo>/.claude/skills/.

Problemas frecuentes

Véase también

• [[ia-tech—metodo—lead-checklist]]
• [[ia-tech—metodo—quick-start]]
• [[ia-tech—metodo—harness-engineering]]
• [[ia-tech—metodo—biblioteca-architecture]]
• [[feature—method—onboarding-v2]]
• [[workspace—onboarding—onboarding-edu]]