07 · Assessment

07 — Assessment

Versión: 0.1 Última actualización: 2026-04-23 Status: 🟡 Draft

“Un certificado que se da por asistencia no vale nada.” — principle #10.

El sistema de assessment es lo que diferencia Academia Agentes de un podcast o un blog. Hay 4 capas.

Las 4 capas de assessment

Lesson-level                    Course-level
═══════════════                 ════════════

Capa 1: Quiz ──→ pass/fail      Capa 3: Proyecto de módulo
                                  (N lessons completadas)
Capa 2: Exercise ──→ score
                                Capa 4: Capstone final
                                  (course completo)

Promoción:

Pass a una lesson = pasar quiz + entregar exercise
Pass un módulo = pasar proyecto de módulo
Pass un course = pasar capstone + bar de completion global

Capa 1: Quiz (per lesson)

Specs

5 preguntas multiple choice por lesson
Formato: A/B/C/D (pocas veces true/false o multi-select)
Auto-graded instantáneo
Pass: ≥4/5 (80%)
Re-takes: ilimitados (pero con cooldown de 5 min entre intentos para obligar a revisar)
Feedback por pregunta: por qué la correcta es correcta, por qué las otras no

Structure de cada pregunta

{
  "id": "b1-l3-q2",
  "lesson_id": "b1-l3",
  "question": "¿Cuál setting tiene precedencia sobre los demás?",
  "options": [
    {
      "id": "a",
      "text": "~/.claude/settings.json",
      "correct": false,
      "explanation": "Este es el nivel global — tiene la precedencia más baja."
    },
    {
      "id": "b",
      "text": ".claude/settings.json (project)",
      "correct": false,
      "explanation": "Project-level tiene precedencia sobre global pero no sobre local."
    },
    {
      "id": "c",
      "text": ".claude/settings.local.json",
      "correct": true,
      "explanation": "Correct — local override es el último que gana y no se commitea."
    },
    {
      "id": "d",
      "text": "Variables de entorno",
      "correct": false,
      "explanation": "Env vars aplican en algunos casos pero no overridean settings hierarchy."
    }
  ],
  "difficulty": "medium",
  "learning_objective": "Entender hierarchy de settings.json"
}

Tipos de preguntas permitidas

Conceptual: qué es X, cuándo usar Y
Comparative: cuál de estos es más apropiado para caso Z
Diagnostic: ves este error / comportamiento, ¿qué es probable?
Decision: dada situación X, ¿qué haces?

Evitar:

Preguntas de memoria pura (nombre exacto de parámetro)
Preguntas ambiguas con múltiples respuestas “correctas”
Trick questions que dependen de leer fino
Preguntas sobre detalles que cambian cada 6 meses (versiones SDK)

Generación de quiz

El quiz se genera con Claude CLI junto con el lesson script:

Input: lesson.md + learning_objectives
Output: quiz.json con 5 preguntas diversificadas
Review: pipeline valida que:
  - Todas las opciones son plausibles
  - La correcta tiene justificación fundamentada en la lesson
  - Las incorrectas tienen explicación educativa
  - Difficulty spread: al menos 1 easy, 1 medium, 1 hard

Capa 2: Exercise (per lesson)

Specs

1 exercise por lesson (algunos lessons pueden no tener — ej: lesson intro conceptual pura)
Time estimate: 20-60 min
Deliverable: concreto y verificable
Scored 0-100 por evaluator agent
Pass: ≥70
Re-submit: permitido con cooldown de 1 día

Tipos de exercises

Tipo	Cómo se verifica
File submission	Upload o link a gist/pastebin; agent revisa contenido
Git commit	Learner pega commit hash; agent checkea el repo
Config change	Learner pega el archivo resultante (ej: settings.json)
Prompt design	Learner pega prompt + screenshot de output; agent evalúa
Workflow description	Learner describe en texto cómo armó algo; agent evalúa coherencia
Screenshot/video	Upload; agent (con vision) evalúa evidencia

Evaluator agent

Cada exercise tiene un evaluator prompt específico con rubrics. Este prompt vive en content/{course}/{lesson}/evaluator.md:

# Evaluator — B1 Lesson 3 Exercise

You are evaluating a submission for:
"Configurar .claude/settings.json para uno de tus proyectos reales con permisos inteligentes"

## Rubric (score 0-100)

### Completeness (40 points)
- File exists and is valid JSON (10)
- Has permissions section (15)
- Has at least 1 env var or hook configured (15)

### Quality (40 points)
- Permissions are *intelligent* (not just "allow everything" nor "deny everything") (20)
- Evidence of thought — comments or structure that shows reasoning (10)
- No security risks (leaked tokens, overly broad permissions) (10)

### Applicability (20 points)
- File is realistic — fits a real project, not toy (10)
- Learner explains in submission why these choices (10)

## Deliverable
Score 0-100, and:
- If < 70: specific feedback on what to improve
- If ≥ 70: brief validation + 1 suggestion for going further

Output format: JSON with {score, feedback, suggestion}

Manual review option

Para exercises complejos o subjetivos, el learner puede optar a revisión manual (por mí, inicialmente; eventualmente peer review o cohort-based).

Costo: no simulated ($0 si no se comercializa; $20-50 si se vendiera).

Capa 3: Proyecto de módulo

Aplica solo a courses largos (3+ semanas). Los de 2 semanas van directo a capstone.

Specs

1 proyecto entre módulos (cada ~4-5 lessons)
Time estimate: 2-4 horas
Integra conceptos de todo el módulo
Evaluado por agent + opcional manual review
Pass: ≥75%

Ejemplo (si B3 MCP Servers tuviera módulos)

Módulo 1 (lessons 1-4): “MCP Protocol Fundamentals” → Proyecto: build a toy MCP server que expone 1 tool. Ejecuta localmente, responde a protocol correctly.

Capa 4: Capstone (per course)

Specs

1 capstone por course
Time estimate: 3-8 días (un proyecto grande)
Deliverable: artefacto sustancial (repo + write-up, o app desplegada)
Evaluated con 4-axis rubric

4-axis rubric (ejemplo de B1)

Axis	%	Qué mide	Quién evalúa
Completeness	40%	# elementos aplicados vs. total (mínimo 7/9)	Agent
Quality	30%	Artefactos usables en día-a-día (no toy)	Agent con rubrics
Reflection	20%	Write-up muestra comprensión, no solo ejecución	Agent (text analysis)
Production-ready	10%	Funcionaría en 3 meses sin atención	Agent simulation (“3 months later”)

Pass: ≥75% total.

Capstone submission

Submission includes:
- Link a repo/branch (GitHub o equivalente)
- Write-up markdown (300-500 palabras)
- Screenshots o demo video (opcional)
- Declaración: ¿qué elementos aplicaste de los 9?
- Self-assessment: score que tú te das en cada axis

El evaluator agent:

Lee el write-up
Revisa el repo/artefacto (si público) o los pastes (si privado)
Compara vs. rubric específico del course
Output: JSON {scores_per_axis, total, feedback, go/no-go}

Certificación automática

Completion de un course requiere:

100% lessons completadas (audio consumed + quiz passed)
100% exercises entregados con score ≥70
Capstone pass (≥75%)

Al cumplir: micro-certificate generated automáticamente.

Detalles de specs de cert → 14-credentials-system.md.

Integridad académica

Qué permitimos

✅ Usar Claude Code / otros AI para hacer los exercises (es el punto — estamos enseñando a usarlos)
✅ Consultar docs, foros, Stack Overflow
✅ Pedir ayuda en comunidad
✅ Mirar solutions de otros learners post-entrega

Qué NO permitimos

❌ Copiar la solution de otro learner literal antes de entregar
❌ Pedirle a Claude el exercise completo sin entender qué hace
❌ Usar mismo repo/code para múltiples exercises (cada uno debe ser nuevo work)

Detección

Evaluator agent flags suspicious similarities (code fingerprint comparisons)
Write-ups generic (sin reflexión personal) = flag para manual review
Git commits todos con mismo timestamp = red flag

Si se detecta: warning privado primero, luego revocation del cert si persiste.

Data del assessment (para análisis agregado)

Cada evento genera row en Supabase:

quiz_attempts (
  id, user_id, lesson_id, question_id,
  answer, correct, attempt_n, timestamp
)

exercise_submissions (
  id, user_id, lesson_id,
  submission_url, score, feedback,
  evaluator_version, submitted_at, graded_at
)

capstone_submissions (
  id, user_id, course_id,
  repo_url, writeup, self_assessment,
  agent_scores (json 4-axis),
  agent_feedback, final_score,
  manual_reviewed, reviewer_notes,
  submitted_at, graded_at
)

Esto permite:

Detectar lessons con quiz que todos fallan (lesson mal escrita?)
Detectar exercises con entrega baja (muy difícil / mal spec?)
Medir completion rates
Mejorar rubrics basado en data real

Open questions

¿Quizzes tienen tiempo límite o son libres? — propongo libres
¿Exercises tienen fecha límite o son self-paced? — self-paced (subscription model)
¿Capstone puede re-submitted con cuánta frecuencia? — ilimitado pero con cooldown de 7 días
¿Peer review eventual? (futura feature, no MVP)
¿Cohort mode con deadlines firmes? (premium tier future)