ai-app-blueprint

AI App Blueprint

[ES] Escribir specs antes de codear está bien. Hacerlo a mano no escala.
[EN] Writing specs before code is fine. Doing it by hand doesn't scale.

De idea a app corriendo en una sesión — Claude Code + Context Engineering + AI App Blueprint

---

Español

Deja de re-explicarle tu proyecto a Claude en cada sesión.

Este blueprint hace que tu repo sea auto-documentado para la IA — arquitectura, decisiones, restricciones, qué está hecho y qué sigue. El agente lo lee al inicio de cada sesión y empieza a trabajar en 30 segundos.

Diseñado para Claude Code. Usa CLAUDE.md, comandos slash (/handoff-save, /handoff-open) y hooks nativos de Claude Code. Si buscas la versión agnóstica al modelo, ve a handoff-blueprint.

Inicio rápido

Opción A — Proyecto nuevo (recomendada)

Prerequisitos: Git · VS Code · extensión Claude Code instalada

1. Abre VS Code y crea una carpeta vacía para tu nuevo proyecto
2. En el chat de Claude Code escribe:

Clona el siguiente repo https://github.com/handoffcl/ai-app-blueprint y ejecuta bootstrap

3. Claude preguntará: "Cuéntame tu idea: ¿qué hace, para quién es y qué puede hacer un usuario en ella?"
4. Describe tu app. Claude genera todo solo: specs, arquitectura, docs, estructura y código.

Opción B — Proyecto existente

# En tu sesión de Claude Code:
# Lee este archivo y adáptalo a nuestro proyecto existente:
# /path/to/ai-app-blueprint/commands/bootstrap-app.md

Opción C — Comando global de Claude Code

cp commands/bootstrap-app.md ~/.claude/commands/
# Luego en cualquier sesión: /bootstrap-app

---

English

Stop re-explaining your project to Claude every session.

This blueprint makes your repo self-documenting for AI — architecture, decisions, constraints, what's done and what's next. Claude reads it at the start of every session and starts working in 30 seconds.

Built for Claude Code. Uses CLAUDE.md, slash commands (/handoff-save, /handoff-open) and native Claude Code hooks. For the model-agnostic version, see handoff-blueprint.

Quickstart

Option A — New project (recommended)

Prerequisites: Git · VS Code · Claude Code extension installed

1. Open VS Code and create an empty folder for your new project
2. In the Claude Code chat, write:

Clone the following repo https://github.com/handoffcl/ai-app-blueprint and run bootstrap

3. Claude will ask: "Tell me your idea: what does it do, who is it for, and what can a user do with it?"
4. Describe your app. Claude generates everything: specs, architecture, docs, project structure and code.

Option B — Existing project

# In your Claude Code session:
# Read this file and adapt it to our existing project:
# /path/to/ai-app-blueprint/commands/bootstrap-app.md

Option C — Claude Code global command

cp commands/bootstrap-app.md ~/.claude/commands/
# Then in any Claude Code session: /bootstrap-app

---

Migrating an existing project (bootstrapped before WORKING-AGREEMENT.md)

If you bootstrapped your project before the WORKING-AGREEMENT.md rule existed, you have two options:

Option 1 — Manual copy (recommended, takes 30 seconds):

# From your project root
curl -fsSL https://raw.githubusercontent.com/handoffcl/ai-app-blueprint/main/blueprint/WORKING-AGREEMENT.md.template -o WORKING-AGREEMENT.md

Then add this block at the top of your CLAUDE.md:

## 🔴 Rule #1 — Read first, code after

**Before any action**, read `WORKING-AGREEMENT.md` and respect it. Not optional.

Summary: analyze → summarize → propose → wait for OK → write spec → only then code.

Option 2 — Re-run /bootstrap-app: This will overwrite CLAUDE.md and other templates. Only do this on a clean branch where you can review the diff and pick the parts you want.

---

What's inside