Checklist de auditoría inicial de repo con Claude Code

La primera sesión de Claude Code en un repositorio existente no debería empezar editando. Debería empezar con un mapa. El agente lee rápido, pero esa velocidad solo ayuda si conoce entradas, zonas protegidas, comandos de prueba y rutas de negocio.

La intención de búsqueda es clara: una persona principiante quiere usar Claude Code en un código real sin perder control. El objetivo no es crear una feature todavía, sino hacer visibles alcance, riesgo, verificación y CTA de revenue en 20 minutos.

Lecturas relacionadas: claude-code-getting-started-complete, claude-code-existing-codebase-map, claude-code-harness-lite-workflow.

Por qué este patrón va antes de la primera edición

Claude Code funciona mejor cuando la tarea tiene límites. Un buen límite nombra archivos que puede leer, archivos que puede editar, operaciones prohibidas y la prueba que cierra el trabajo. Sin ese límite, un prompt pequeño de principiante puede convertirse en una reescritura amplia, y un cambio de contenido puede romper la ruta a PDF, Gumroad o consulta.

Este patrón también ayuda a revenue porque conecta prueba técnica con prueba para el lector. Una página que builda en local pero manda al lector al producto equivocado no está terminada. Si guardas scope, command, URL pública y CTA, mañana mejoras desde evidencia, no desde memoria.

Flujo práctico de trabajo

1. Leer primero solo README, package.json y entradas de routing
2. Marcar generated, billing, auth, migrations y .env como zonas protegidas
3. Limitar la primera superficie editable a tres archivos o menos
4. Elegir un comando de prueba antes de cualquier patch
5. En contenido o landing pages, incluir PDF gratuito, Gumroad y consulta en la auditoría

Situación	Movimiento seguro	Prueba
Sitio Astro de contenido	Antes de crear un artículo, revisa collection, reglas de slug, uso de heroImage y patrón de CTA. El cuerpo y la ruta pagada son parte de la auditoría.	build, diff, URL
Dashboard React	Para un fallo pequeño de layout, limita el trabajo al componente, CSS y captura. Auth y billing quedan protegidos.	screenshot, test
Repositorio API	Empieza leyendo la ruta y el comando de test. Migrations y secretos quedan fuera del primer trabajo.	log, command, handoff

La primera pasada debe ser corta. La auditoría debe crear una decisión, no un informe gigante. Si después de 20 minutos la decisión sigue borrosa, el siguiente paso seguro es pedir leer un archivo más, no empezar a editar.

Prompt y código copiables

Audita este repositorio antes de la primera edición. No edites todavía. Devuelve archivos de entrada, zonas protegidas, archivos seguros, comando mínimo de prueba y checks de URL pública y CTA.

const audit = {
  repo: "customer-portal",
  intent: "first safe Claude Code session",
  scope: ["README.md", "package.json", "src/routes"],
  protected: [".env", "billing/", "migrations/"],
  proof: ["npm.cmd run build", "git diff --stat"],
};

export function readyForFirstEdit(report) {
  return report.scope.length > 0 &&
    report.protected.length > 0 &&
    report.proof.some((command) => command.includes("build"));
}

console.log(readyForFirstEdit(audit));

El código es pequeño a propósito. Convierte una idea operativa en un objeto verificable: existe scope, existen zonas protegidas y existe al menos un comando de prueba. Puedes adaptarlo para publicar artículos, desarrollar apps, depurar o hacer handoff de equipo.

Tres ejemplos reales

Sitio Astro de contenido

Antes de crear un artículo, revisa collection, reglas de slug, uso de heroImage y patrón de CTA. El cuerpo y la ruta pagada son parte de la auditoría.

Lo importante es la prueba. Deja un comando, una página visible o una nota que demuestre que el trabajo llegó al lector.

Dashboard React

Para un fallo pequeño de layout, limita el trabajo al componente, CSS y captura. Auth y billing quedan protegidos.

Lo importante es la prueba. Deja un comando, una página visible o una nota que demuestre que el trabajo llegó al lector.

Repositorio API

Empieza leyendo la ruta y el comando de test. Migrations y secretos quedan fuera del primer trabajo.

Lo importante es la prueba. Deja un comando, una página visible o una nota que demuestre que el trabajo llegó al lector.

Fallos que conviene evitar

• Pedir que arregle todo mezcla auditoría e implementación.
• Un build local no basta si la URL pública o el CTA apuntan a la página equivocada.
• Sin zonas protegidas por escrito, una edición útil puede convertirse en incidente.

Otro fallo sutil es el drift de localización. El artículo en inglés puede explicar la ruta correcta, mientras otro idioma conserva un CTA viejo. Por eso la revisión pública debe incluir h1, inicio del cuerpo y CTA en cada idioma, no solo frontmatter lang.

Cómo llevar al lector a PDF, Gumroad y consulta

Si el lector aún necesita soltura con comandos, envíalo al cheatsheet gratuito. Si el bloqueo está en setup, permisos, CLAUDE.md, hooks, MCP o CI/CD, la mejor compra es la Setup Guide. Si repite prompts de revisión, debugging y refactor, encaja 50 Prompt Templates. Si el problema es despliegue de equipo, diseño de workflow o ruta de ingresos, usa la consulta. Para comparar opciones, abre products.

No fuerces a todo lector hacia el producto pagado de inmediato. El principiante suele necesitar primero un PDF de baja fricción. Quien repite prompts está más cerca de plantillas. Quien se bloquea en permisos, CLAUDE.md, hooks, MCP o CI/CD está más cerca de Setup Guide. Equipos y operadores con preguntas de proceso están más cerca de consulta.

Qué verificar antes y después de publicar

Verificar este artículo significa revisar h1, inicio del cuerpo, heroImage, enlaces internos, enlaces de Gumroad y ruta de consulta. Un HTTP 200 no basta si el CTA lleva al siguiente paso equivocado.

En publicación multilingüe, revisa japonés, inglés, chino, coreano, español, francés, alemán, portugués, hindi e indonesio por separado. El slug puede coincidir mientras el cuerpo sigue viejo. Las capturas móviles encuentran esto antes porque muestran párrafo inicial y CTA juntos.

Métricas que mirar después

Después mira inicios de PDF, clics Gumroad, visitas a products, visitas a training, origen de búsqueda, mezcla por país y tasa de clic de artículo a CTA. Si suben PV pero no Gumroad, falta mejor encaje de producto. Si suben consultas desde un artículo técnico, el lector probablemente necesita diseño de workflow.