사용 방법
- 설치 명령을 복사하고 자신의 에이전트 환경에 설치하기 전에 소스 패키지를 확인하세요.
- 필요한 도구, 인증 정보, 지원 환경은 원본 문서에서 확인하세요.
- 입력과 원하는 산출물을 설명하고 출처와 결과를 대조하세요.
npx skills add https://github.com/hamsomp3/jan_skills_repository --skill jan-project-standard시작 전 확인
- 설치에는 모델 구독, API 한도, 파일 접근 권한이 포함되지 않습니다.
- 별점 수와 설치 수는 활동 지표이며 독립적인 품질·보안 검증이 아닙니다.
원본 저장소의 제목, 예시, 코드, 표, 링크, 이미지를 유지해 표시합니다.
Estándar de proyectos — Jan Polanco Velasco
Este skill encapsula cómo se construyen y gobiernan los proyectos de Jan: una forma de trabajar repetible, reproducible y auditable que ya está aplicada en decenas de repositorios personales y académicos.
Filosofía central: todo lo que vive dentro de la carpeta del proyecto tiene una instrucción escrita. El documento que la contiene es `CONSTITUTION.md`, la fuente única de verdad. Un proyecto sano es un proyecto donde un agente (o una persona) puede leer la constitución y operar sin adivinar.
Cómo invocarlo (plantilla de prompt)
No hace falta memorizar comandos: describe tu caso en lenguaje natural. Estas son las piezas que conviene incluir:
@jan-project-standard
Soy: Jan | NO soy Jan → aquí mi nombre y correo
Estado: proyecto nuevo | proyecto existente (ya tiene README y/o CONSTITUTION.md)
Repo: git@github.com:<usuario>/<repo>.git
Stack: Python (uv) · ¿paquete o app? · ¿ty? · ¿Archify?
Objetivo: crear desde cero | estandarizar SIN borrar | solo auditar | añadir X
Restricción: no elimines nada existente; mejora y completa.Reglas de convivencia (obligatorias):
- En un proyecto existente: primero leer, luego proponer, luego aplicar. Nunca reemplaces
archivos del usuario (README, CONSTITUTION.md, código) sin revisarlos.
- Si no eres Jan: no uses rutas ni repos fijos; aporta tus datos (ver "Identidad Git").
- Ante la duda, audita (
--audit) y muestra el informe antes de tocar nada.
Cuándo usar este skill
- Crear un proyecto o repositorio nuevo desde cero.
- Estandarizar un proyecto existente que no sigue el estándar.
- Redactar, poblar o actualizar un
CONSTITUTION.md. - Configurar
uv+ Ruff + pre-commit + Makefile + CI. - Conectar un proyecto local a un repositorio de GitHub.
- Preparar un README profesional con badges, licencia y estructura.
Cuándo NO usarlo
- Proyectos que ya tienen su propio estándar y el usuario no quiere adoptar este.
- Cambios triviales de una línea en un repo ya estandarizado (no re-scaffold).
Las 10 reglas no negociables
- CONSTITUTION.md primero. La constitución se crea al inicio y se **actualiza en el
mismo commit** ante cualquier cambio arquitectónico, tecnológico o de proceso.
- `uv` manda. Gestión de entornos y dependencias solo con
uv. Prohibidopip
y requirements.txt. Dependencias en pyproject.toml; uv.lock sí se versiona.
- Python 3.13+ fijado en
.python-versiony enrequires-python. - src-layout (
src/<paquete>/) con build backenduv_build, salvo apps simples
(modo --app).
- Calidad automatizada: Ruff (lint + formato), pre-commit y pytest. Nada se sube
con make check en rojo. --no-verify está prohibido salvo causa documentada.
- Makefile como interfaz. Todos los comandos del proyecto se exponen en targets
(make help los lista). La paridad local ↔ CI es obligatoria: el CI corre lo mismo.
- Conventional Commits (
feat:,fix:,docs:,refactor:,style:,test:,
chore:) en un solo idioma claro; descripciones en imperativo.
- GitHub gobernado: plantilla de Pull Request, plantillas de issue, CI, Dependabot,
labels declarativas y rama main protegida por PRs.
- README profesional: badges, tabla de contenidos, stack, primeros pasos, estructura,
arquitectura (opcional, con Archify), contribución y licencia.
- Identidad Git automática: la carpeta de proyectos hereda nombre, correo y llave SSH
vía includeIf en ~/.gitconfig. Perfil A para Jan (~/Desktop/Repositorios/personal/); Perfil B para cualquier otro usuario (macOS o Windows), y solo si lo pide (ver `references/git-identity.md`).
Modo A — Crear un proyecto nuevo
Paso 1 · Ejecutar el scaffolder
El scaffolder copia las plantillas, sustituye variables y deja el proyecto listo. Usa solo la biblioteca estándar de Python (no requiere uv para ejecutarse):
python3 <SKILL_DIR>/scripts/new_project.py \
--name "Nombre del Proyecto" \
--path ./nombre-del-proyecto \
--description "Descripción breve del proyecto." \
--gitLa autoría y el owner se deducen solos:--author/git config user.name/user.email, y--ownerdegit config github.user. Puedes sobreescribirlos con flags si quieres.
Opciones más usadas:
| Opción | Efecto |
|---|---|
--name | Nombre legible del proyecto (obligatorio). |
--path | Carpeta destino (por defecto .). |
--repo | Nombre del repo en GitHub (por defecto, slug del nombre). |
--owner | Cuenta/organización de GitHub (por defecto: git config github.user o <usuario>). |
--description | Descripción de una línea (va al README, pyproject y constitución). |
--author / --email | Autoría (por defecto: git config user.name / user.email). |
--python-version | Versión de Python (por defecto 3.13). |
--app | Proyecto de aplicación (sin paquete ni build-system), en vez de src-layout. |
--minimal | Solo lo esencial: sin .github, sin AGENTS.md/.opencode, sin extras. |
--archify | Incluye la sección Arquitectura del proyecto (Archify) en el README y la fila en la constitución. |
--no-types | Omite ty (tipado estático) de dependencias, Makefile y docs. |
--no-github | No genera .github/. |
--no-agents | No genera AGENTS.md ni .opencode/. |
--git / --no-git | Inicializa el repositorio git (rama main). Por defecto: sí. |
--sync | Ejecuta uv sync y uv run pre-commit install al terminar. |
--force | Sobrescribe archivos existentes. |
--dry-run | Muestra qué haría sin escribir nada. |
--audit | Solo audita un proyecto existente (FALTA/DIFIERE/OK) sin escribir nada; infiere el contexto del repo. |
⚠️ Antes de sobrescribir: si la carpeta destino ya tiene archivos (sobre todo unCONSTITUTION.mdoREADME.mdpropios), no uses `--force` a ciegas. Investiga, lee lo existente y fusiona en lugar de reemplazar.
Paso 2 · Poblar la constitución
Abre CONSTITUTION.md y completa, como mínimo, las secciones marcadas con <!-- ... -->:
- Propósito y no-propósito (una o dos frases cada uno).
- Alcance (qué entra y qué no).
- Stack técnico (confirma o corrige la tabla).
- Decisiones iniciales en el historial (fecha + decisión + motivo).
- Notas y tareas pendientes (roadmap en formato checklist).
Paso 3 · Verificar el entorno
cd nombre-del-proyecto
uv sync
uv run pre-commit install
make check # lint + formato + pruebasPaso 4 · Conectar a GitHub
Crea el repositorio (si no existe) y publica:
gh repo create <tu-usuario>/<repo> --private --source=. --remote=origin --push
# o, si el repo ya existe:
git remote add origin git@github.com:<tu-usuario>/<repo>.git
git push -u origin mainLuego protege main y verifica que la CI esté en verde. Detalle en `references/github.md`.
Paso 5 · Diagrama de arquitectura (opcional, Archify)
Si el proyecto necesita un mapa de arquitectura en el README (documentación viva), instala la skill Archify y genera el diagrama:
npx skills add tt-a1i/archify -g
# Luego, en el chat:
# "Analiza este repositorio y usa Archify para crear un diagrama de arquitectura de
# runtime. 8–12 componentes, un camino principal, dependencias externas y límites."El resultado queda en docs/arquitectura.json (fuente versionada) y docs/arquitectura.html (artefacto interactivo), y se enlaza desde el README. No se edita el HTML a mano: se regenera con deliver. Detalle completo en `references/archify.md`.
Modo B — Mejorar un proyecto existente (no destructivo)
Contrato de no destrucción. El objetivo no es reemplazar, es completar y elevar. Un repo con historia,README.mdoCONSTITUTION.mdpropios es trabajo del usuario: se lee, respeta y mejora; nunca se borra ni se sobrescribe con--forcea ciegas.
- Audita sin tocar nada (captura el contexto del propio repo):
python3 <SKILL_DIR>/scripts/new_project.py --path . --auditLee pyproject.toml, .python-version, CONSTITUTION.md y el remoto de git, y reporta FALTA / DIFIERE / OK. DIFIERE puede ser personalización legítima: revísala.
- Lee
README.md,CONSTITUTION.mdy la estructura real antes de cambiar nada. - Propón un plan (qué se añade, qué se completa) y aplícalo de forma aditiva:
python3 <SKILL_DIR>/scripts/new_project.py --path . --name "..." --description "..."Sin --force, el scaffolder omite todo archivo que ya existe (solo crea lo que falta).
- Fusiona los `DIFIERE` a mano: conserva el contenido del usuario y añade lo que
falte (no reemplaces secciones; no borres lo propio).
- Migra solo si el usuario lo pide:
requirements.txt→pyproject.tomlconuv add;
scripts sueltos → src/<paquete>/; .ipynb → .py.
- Registra el cambio en el historial de la constitución y verifica con
make check.
El --audit es la herramienta para "capturar más contexto": puedes correrlo las veces que quieras sin efectos secundarios, incluso en repos grandes, y mostrar el informe antes de proponer cambios.Manifiesto de archivos del estándar
| Archivo | Propósito |
|---|---|
CONSTITUTION.md | Fuente única de verdad: propósito, stack, estructura, convenciones, flujo y decisiones. |
README.md | Puerta de entrada pública: badges, TOC, descripción, stack, primeros pasos, estructura, contribución, licencia. |
pyproject.toml | Metadatos, dependencias (uv), configuración de Ruff y pytest. |
uv.lock | Lockfile determinista (versionado). |
.python-version | Versión de Python fijada (3.13). |
.gitignore | Ignora venvs, cachés, secretos, artefactos pesados y datos. |
.editorconfig | Convenciones de estilo entre editores. |
Makefile | Interfaz de comandos (help, install, dev, lint, format, test, check, clean). |
.pre-commit-config.yaml | Higiene de archivos + Ruff + uv-lock antes de cada commit. |
LICENSE | MIT por defecto. |
CONTRIBUTING.md | Entorno, ramas, estándares, commits y proceso de PR. |
CODE_OF_CONDUCT.md | Contributor Covenant 2.1 (proyectos con colaboración). |
AGENTS.md | Contexto para agentes LLM (stack, flujo, reglas, tgrep). |
.opencode/rules/tgrep.md | Regla de búsqueda con tgrep para agentes en OpenCode. |
.github/pull_request_template.md | Plantilla de PR (Conventional Commits + checklist). |
.github/ISSUE_TEMPLATE/ | Formularios de bug, funcionalidad e investigación (spike). |
.github/workflows/ci.yml | CI: pre-commit + pruebas. |
.github/workflows/labels.yml | Sincroniza labels desde .github/labels.yml. |
.github/labels.yml | Fuente única de las etiquetas del repositorio. |
.github/dependabot.yml | Actualización automática de dependencias (uv y Actions). |
src/<paquete>/ | Código del paquete (src-layout). |
tests/ | Pruebas con pytest (patrón AAA). |
docs/ | Documentación, ADRs, spikes e investigación. |
docs/arquitectura.{json,html} | Diagrama interactivo de arquitectura (Archify); el JSON es la fuente. Ver `references/archify.md`. |
Variables de las plantillas
Las plantillas bajo assets/templates/ usan marcadores que el scaffolder sustituye. Si editas a mano, reemplázalos todos:
| Marcador | Significado |
|---|---|
{{PROJECT_NAME}} | Nombre legible (Mi Proyecto). |
{{PROJECT_SLUG}} | Identificador kebab-case (mi-proyecto), usado como carpeta y repo. |
{{PACKAGE_NAME}} | Identificador snakecase (`miproyecto`), usado como paquete Python. |
{{DESCRIPTION}} | Descripción de una línea. |
{{OWNER}} / {{REPO}} | Cuenta y nombre del repositorio. |
{{REPO_URL}} / {{SSH_URL}} | URLs HTTPS y SSH del repositorio. |
{{AUTHOR}} / {{AUTHOR_EMAIL}} | Autoría. |
{{PYTHON_VERSION}} | Versión de Python (3.13). |
{{YEAR}} / {{DATE}} | Año y fecha ISO. |
Bloques condicionales (se eliminan si la bandera es falsa): {{#if PACKAGE}}…{{/if}} (src-layout), {{#if TYPES}}…{{/if}} (ty), {{#if GITHUB}}…{{/if}}, {{#if AGENTS}}…{{/if}}.
Documentación de apoyo
Carga estos archivos solo cuando los necesites (divulgación progresiva):
| Referencia | Contenido |
|---|---|
| `references/constitution.md` | Anatomía completa del CONSTITUTION.md sección por sección, con ejemplos. |
| `references/python-stack.md` | uv, pyproject.toml, Ruff, Makefile, pre-commit, .editorconfig, .gitignore. |
| `references/github.md` | Creación del repo, remotos SSH, badges, plantillas, CI, Dependabot, labels, ramas. |
| `references/agent-context.md` | AGENTS.md, .opencode/rules/ y tgrep. |
| `references/git-identity.md` | Identidad Git automática (includeIf): perfil Jan y perfil propio para macOS/Windows. |
| `references/archify.md` | Diagramas de arquitectura interactivos con Archify (instalación, tipos, validate/deliver, README). |
| `references/slidev.md` | Presentaciones con Slidev (proyectos de curso): monolito, hub, reglas de sintaxis, export. |
Identidad Git automática (includeIf)
Configura Git para que todo repositorio bajo una carpeta use automáticamente un nombre, un correo y una llave SSH. Es una de las piezas más útiles del estándar: elimina flags y gh auth por proyecto. Hay dos perfiles y el agente debe decidir cuál aplica (detalle en `references/git-identity.md`).
Perfil A — Ejemplo (configuración del autor de la skill)
Es solo un ejemplo real de un perfil funcionando. Cualquier otro usuario sigue el Perfil B con sus propios datos.
Carpeta canónica de ejemplo ~/Desktop/Repositorios/personal/:
# ~/.gitconfig
[includeIf "gitdir:~/Desktop/Repositorios/personal/"]
path = ~/.gitconfig-personal# ~/.gitconfig-personal
[user]
name = Jan Polanco V.
email = hamsomp3@gmail.com
[core]
sshCommand = ssh -i ~/.ssh/id_ed25519 -o IdentitiesOnly=yesEfecto: todo repo bajo esa carpeta usa el nombre, correo y llave del ejemplo. Preferir remotos SSH (git@github.com:<tu-usuario>/<repo>.git); HTTPS puede resolver con un token de otra cuenta.
Perfil B — Cualquier otro usuario (alumno, compañero)
Si el usuario pide identidad automática y no comparte el perfil de ejemplo, pregúntale primero su nombre, correo, llave SSH y carpeta de proyectos, y luego configura includeIf en su carpeta y su sistema operativo (macOS o Windows). Script listo:
python3 <SKILL_DIR>/scripts/setup_git_identity.py \
--name "Pedro Pérez" --email pedro@example.com \
--key ~/.ssh/id_ed25519 --dir ~/Repos/personal --platform mac
# Windows: --key C:/Users/pedro/.ssh/id_ed25519 --dir C:/Users/pedro/Repos --platform windowsEl script respalda ~/.gitconfig, es idempotente y tiene un modo --print que solo muestra los bloques sin escribir nada. Pasos manuales y gotchas (orden de includeIf, gitdir/i:, rutas con / en Windows, IdentitiesOnly) en `references/git-identity.md`.
⚙️ Nunca se commitea: es configuración local de la máquina. Vive en la constitución solo como nota (no como archivo del repo), y solo se aplica si el usuario lo pide.
Flujo diario (commit + push)
git status # 1. ver cambios
make check # 2. lint + formato + (tipos) + pruebas
git add -A # 3. agregar
git commit -m "tipo: mensaje" # 4. commitear (los hooks se ejecutan solos)
git push # 5. subirChecklist de verificación
Antes de dar por terminado un proyecto o un cambio:
- [ ]
CONSTITUTION.mdexiste y está poblado (propósito, stack, estructura, flujo, decisiones). - [ ]
uv syncfunciona yuv.lockestá versionado. - [ ]
make checkpasa en verde (lint + formato + pruebas). - [ ]
uv run pre-commit run --all-filespasa (hooks instalados). - [ ]
README.mdtiene badges, TOC, descripción, stack, primeros pasos y licencia. - [ ]
LICENSEpresente (MIT por defecto). - [ ]
.github/con PR template, issue templates, CI, Dependabot y labels (si aplica). - [ ]
AGENTS.md(y.opencode/rules/tgrep.md) describen el proyecto para agentes (si aplica). - [ ] Identidad Git automática configurada si el usuario lo pidió (perfil A para Jan / perfil B para otros).
- [ ] Diagrama de arquitectura con Archify en
docs/y enlazado desde el README (si aplica). - [ ] Sin secretos, datos personales ni artefactos pesados versionados.
- [ ] El historial de decisiones de la constitución registra los cambios significativos.
Directiva de mantenimiento
Cada vez que se realicen cambios significativos (nuevas funcionalidades, cambios arquitectónicos, adición de clases/módulos o ajustes de tecnologías), se debe actualizar `CONSTITUTION.md` en el mismo commit para mantener la verdad central del proyecto. El checklist de la plantilla de Pull Request lo verifica explícitamente.