Back to Details

jan-project-standard

Compare original and translation side by side

🇺🇸

Original

English
🇨🇳

Translation

Chinese

Estándar de proyectos — Jan Polanco Velasco

项目标准 — 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.
此 skill 封装了 Jan 构建和治理项目的方式：一种可重复、可复现且可审计的工作流程，目前已经应用于数十个个人和学术仓库。
核心理念： 项目目录内的所有内容都有书面说明。承载这些说明的文档是 
CONSTITUTION.md
，即唯一事实来源。健康的项目应当让 Agent（或人）阅读章程后，无需猜测即可开展操作。

Cómo invocarlo (plantilla de prompt)

如何调用（Prompt 模板）

No hace falta memorizar comandos: describe tu caso en lenguaje natural. Estas son las piezas que conviene incluir:
text
@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.
无需记忆命令：用自然语言描述你的场景。建议包含以下内容：
text
@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.
协作规则（强制）：
  • 对于现有项目：先阅读，再提出方案，然后应用。未经审阅，绝不替换用户的文件（README、
    CONSTITUTION.md
    、代码）。
  • 如果你不是 Jan：不要使用固定路径或固定仓库；请提供你的信息（参见“Git 身份”）。
  • 如有疑问，先进行审计（
    --audit
    ）并展示报告，然后再进行任何修改。

Cuándo usar este skill

何时使用此 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.
  • 从零创建新的项目或仓库。
  • 标准化未遵循该标准的现有项目。
  • 编写、填充或更新 
    CONSTITUTION.md
    。
  • 配置 
    uv
    + Ruff + pre-commit + Makefile + CI。
  • 将本地项目接入 GitHub 仓库。
  • 准备包含徽章、许可证和目录结构的专业 README。

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

10 条不可协商的规则

  1. 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.
  2. uv
    manda.     Gestión de entornos y dependencias solo con 
    uv
    . Prohibido 
    pip
    y 
    requirements.txt
    . Dependencias en 
    pyproject.toml
    ; 
    uv.lock
    sí se versiona.
  3. Python 3.13+ fijado en 
    .python-version
    y en 
    requires-python
    .
  4. src-layout (
    src/<paquete>/
    ) con build backend 
    uv_build
    , salvo apps simples (modo 
    --app
    ).
  5. Calidad automatizada: Ruff (lint + formato), pre-commit y pytest. Nada se sube con 
    make check
    en rojo. 
    --no-verify
    está prohibido salvo causa documentada.
  6. 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.
  7. Conventional Commits (
    feat:
    , 
    fix:
    , 
    docs:
    , 
    refactor:
    , 
    style:
    , 
    test:
    , 
    chore:
    ) en un solo idioma claro; descripciones en imperativo.
  8. GitHub gobernado: plantilla de Pull Request, plantillas de issue, CI, Dependabot, labels declarativas y rama 
    main
    protegida por PRs.
  9. README profesional: badges, tabla de contenidos, stack, primeros pasos, estructura, arquitectura (opcional, con Archify), contribución y licencia.
  10. 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
    ).
  1. 优先创建 
    CONSTITUTION.md
    。     章程应在项目开始时创建，并在任何架构、技术或流程变更时通过同一次 commit 同步更新。
  2. 以 
    uv
    为准。     环境和依赖管理只能使用 
    uv
    。禁止使用 
    pip
    和 
    requirements.txt
    。依赖写在 
    pyproject.toml
    中；
    uv.lock
    必须纳入版本控制。
  3. 在 
    .python-version
    和 
    requires-python
    中固定使用 Python 3.13+。
  4. 使用 src-layout（
    src/<paquete>/
    ）和构建后端 
    uv_build
    ，简单应用除外（
    --app
    模式）。
  5. 自动化质量保障： Ruff（lint + 格式化）、pre-commit 和 pytest。不得在 
    make check
    未通过时推送内容。除非有书面记录的原因，否则禁止使用 
    --no-verify
    。
  6. 使用 Makefile 作为接口。 项目的所有命令都应通过 targets 暴露（
    make help
    会列出这些命令）。本地与 CI 必须保持一致：CI 执行相同的命令。
  7. 使用 Conventional Commits（
    feat:
    、
    fix:
    、
    docs:
    、
    refactor:
    、
    style:
    、
    test:
    、
    chore:
    ），并统一使用一种清晰的语言；描述采用祈使语气。
  8. 治理 GitHub： 提供 Pull Request 模板、issue 模板、CI、Dependabot、声明式 labels，并通过 PR 保护 
    main
    分支。
  9. 提供专业 README： 包含徽章、目录、技术栈、初始步骤、目录结构、架构（可选，使用 Archify）、贡献指南和许可证。
  10. 自动配置 Git 身份： 项目文件夹通过 
    ~/.gitconfig
    中的 
    includeIf
    自动继承姓名、邮箱和 SSH 密钥。配置 A 供 Jan 使用（
    ~/Desktop/Repositorios/personal/
    ）；配置 B 供其他任何用户使用（macOS 或 Windows），并且仅在用户明确要求时启用（参见 
    references/git-identity.md
    ）。

Modo A — Crear un proyecto nuevo

模式 A — 创建新项目

Paso 1 · Ejecutar el scaffolder

第 1 步 · 运行脚手架工具

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):
bash
python3 <SKILL_DIR>/scripts/new_project.py \
  --name "Nombre del Proyecto" \
  --path ./nombre-del-proyecto \
  --description "Descripción breve del proyecto." \
  --git
La autoría y el owner se deducen solos: 
--author
/
--email
salen de 
git config user.name
/ 
user.email
, y 
--owner
de 
git config github.user
. Puedes sobreescribirlos con flags si quieres.
Opciones más usadas:
OpciónEfecto
--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 un 
CONSTITUTION.md
o 
README.md
propios), no uses 
--force
a ciegas. Investiga, lee lo existente y fusiona en lugar de reemplazar.
脚手架工具会复制模板、替换变量，并使项目进入可用状态。它仅使用 Python 标准库（执行时不需要 
uv
）：
bash
python3 <SKILL_DIR>/scripts/new_project.py \
  --name "Nombre del Proyecto" \
  --path ./nombre-del-proyecto \
  --description "Descripción breve del proyecto." \
  --git
作者和 owner 会自动推导：
--author
/
--email
来自 
git config user.name
/ 
user.email
，
--owner
来自 
git config github.user
。你也可以通过参数手动覆盖。
常用选项：
选项效果
--name
项目的易读名称（必填）。
--path
目标文件夹（默认为 
.
）。
--repo
GitHub 仓库名称（默认为项目名称转换后的 slug）。
--owner
GitHub 账户或组织（默认为 
git config github.user
或 
<usuario>
）。
--description
单行描述（写入 README、pyproject 和章程）。
--author
/ 
--email
作者信息（默认为 
git config user.name
/ 
user.email
）。
--python-version
Python 版本（默认为 
3.13
）。
--app
应用项目（无 package 和 build-system），而不是 src-layout。
--minimal
仅保留必要内容：不包含 
.github
、
AGENTS.md
/
.opencode
和其他扩展项。
--archify
在 README 中包含项目架构（Archify）章节，并在章程中加入对应条目。
--no-types
从依赖、Makefile 和文档中移除 
ty
（静态类型检查）。
--no-github
不生成 
.github/
。
--no-agents
不生成 
AGENTS.md
或 
.opencode/
。
--git
/ 
--no-git
初始化 git 仓库（
main
分支）。默认启用。
--sync
完成后执行 
uv sync
和 
uv run pre-commit install
。
--force
覆盖现有文件。
--dry-run
展示将要执行的操作，但不写入任何内容。
--audit
仅审计现有项目（FALTA/DIFIERE/OK），不写入任何内容；同时推断仓库上下文。
⚠️ 覆盖之前： 如果目标文件夹已经包含文件（尤其是你自己的 
CONSTITUTION.md
或 
README.md
），不要盲目使用 
--force
。应先调查并阅读现有内容，然后合并，而不是替换。

Paso 2 · Poblar la constitución

第 2 步 · 填充章程

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).
打开 
CONSTITUTION.md
，至少填写所有以 
<!-- ... -->
标记的部分：
  • 目的和非目标（各一至两句话）。
  • 范围（包含什么，不包含什么）。
  • 技术栈（确认或修正表格）。
  • 历史记录中的初始决策（日期 + 决策 + 原因）。
  • 备注和待办事项（采用 checklist 格式的 roadmap）。

Paso 3 · Verificar el entorno

第 3 步 · 验证环境

bash
cd nombre-del-proyecto
uv sync
uv run pre-commit install
make check     # lint + formato + pruebas
bash
cd nombre-del-proyecto
uv sync
uv run pre-commit install
make check     # lint + formato + pruebas

Paso 4 · Conectar a GitHub

第 4 步 · 接入 GitHub

Crea el repositorio (si no existe) y publica:
bash
gh repo create <tu-usuario>/<repo> --private --source=. --remote=origin --push
创建仓库（如果尚不存在）并发布：
bash
gh repo create <tu-usuario>/<repo> --private --source=. --remote=origin --push

o, si el repo ya existe:

o, si el repo ya existe:

git remote add origin git@github.com:<tu-usuario>/<repo>.git git push -u origin main

Luego protege `main` y verifica que la CI esté en verde. Detalle en
[`references/github.md`](references/github.md).
git remote add origin git@github.com:<tu-usuario>/<repo>.git git push -u origin main

随后保护 `main` 分支，并确认 CI 全部通过。详细信息参见 [`references/github.md`](references/github.md)。

Paso 5 · Diagrama de arquitectura (opcional, Archify)

第 5 步 · 架构图（可选，使用 Archify）

Si el proyecto necesita un mapa de arquitectura en el README (documentación viva), instala la skill Archify y genera el diagrama:
bash
npx skills add tt-a1i/archify -g
如果项目需要在 README 中提供架构图（作为持续维护的活文档），请安装 Archify skill 并生成图表：
bash
npx skills add tt-a1i/archify -g

Luego, en el chat:

Luego, en el chat:

"Analiza este repositorio y usa Archify para crear un diagrama de arquitectura de

"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."

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`](references/archify.md).

---

结果会保存在 `docs/arquitectura.json`（纳入版本控制的源文件）和 `docs/arquitectura.html`（交互式产物）中，并从 README 链接。**不要**手动编辑 HTML；应使用 `deliver` 重新生成。完整说明参见 [`references/archify.md`](references/archify.md)。

---

Modo B — Mejorar un proyecto existente (no destructivo)

模式 B — 改进现有项目（非破坏性）

Contrato de no destrucción. El objetivo no es reemplazar, es completar y elevar. Un repo con historia, 
README.md
o 
CONSTITUTION.md
propios es trabajo del usuario: se lee, respeta y mejora; nunca se borra ni se sobrescribe con 
--force
a ciegas.
  1. Audita sin tocar nada (captura el contexto del propio repo):
    bash
    python3 <SKILL_DIR>/scripts/new_project.py --path . --audit
    Lee 
    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.
  2. Lee 
    README.md
    , 
    CONSTITUTION.md
    y la estructura real antes de cambiar nada.
  3. Propón un plan (qué se añade, qué se completa) y aplícalo de forma aditiva:
    bash
    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).
  4. Fusiona los 
    DIFIERE
    a mano:     conserva el contenido del usuario y añade lo que falte (no reemplaces secciones; no borres lo propio).
  5. Migra solo si el usuario lo pide: 
    requirements.txt
    → 
    pyproject.toml
    con 
    uv add
    ; scripts sueltos → 
    src/<paquete>/
    ; 
    .ipynb
    → 
    .py
    .
  6. 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.
不破坏性契约。 目标不是替换，而是补全和提升。拥有历史记录、自有 
README.md
或 
CONSTITUTION.md
的仓库属于用户：应当阅读、尊重并改进；绝不能删除文件，也不能盲目使用 
--force
覆盖。
  1. 不进行任何修改地审计（捕获仓库自身的上下文）：
    bash
    python3 <SKILL_DIR>/scripts/new_project.py --path . --audit
    读取 
    pyproject.toml
    、
    .python-version
    、
    CONSTITUTION.md
    和 git remote，并报告 FALTA / DIFIERE / OK。
    DIFIERE
    也可能是合理的个性化设置：请审查确认。
  2. 在修改任何内容之前，阅读 
    README.md
    、
    CONSTITUTION.md
    和真实目录结构。
  3. 提出计划（需要添加和补全哪些内容），然后以增量方式应用：
    bash
    python3 <SKILL_DIR>/scripts/new_project.py --path . --name "..." --description "..."
    不使用 
    --force
    时，脚手架工具会省略所有已经存在的文件，仅创建缺失内容。
  4. 手动合并 
    DIFIERE
    ：     保留用户内容并补充缺失部分（不要替换章节，也不要删除用户自己的内容）。
  5. 仅在用户明确要求时进行迁移：使用 
    uv add
    将 
    requirements.txt
    迁移到 
    pyproject.toml
    ；将零散脚本迁移到 
    src/<paquete>/
    ；将 
    .ipynb
    迁移为 
    .py
    。
  6. 在章程历史记录中登记此次变更，并使用 
    make check
    进行验证。
--audit
是用于“获取更多上下文”的工具：可以运行任意多次且不会产生副作用，即使面对大型仓库也是如此。应在提出变更方案前展示审计报告。

Manifiesto de archivos del estándar

标准文件清单

ArchivoPropó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
.
文件用途
CONSTITUTION.md
唯一事实来源：目的、技术栈、结构、约定、流程和决策。
README.md
面向公众的入口：徽章、目录、描述、技术栈、初始步骤、目录结构、贡献指南和许可证。
pyproject.toml
元数据、依赖（
uv
）、Ruff 和 pytest 配置。
uv.lock
确定性的 lockfile（纳入版本控制）。
.python-version
固定的 Python 版本（
3.13
）。
.gitignore
忽略 venv、缓存、机密信息、大型产物和数据集。
.editorconfig
跨编辑器统一代码风格。
Makefile
命令接口（
help
、
install
、
dev
、
lint
、
format
、
test
、
check
、
clean
）。
.pre-commit-config.yaml
每次 commit 前执行文件检查、Ruff 和 
uv-lock
。
LICENSE
默认采用 MIT。
CONTRIBUTING.md
环境、分支、标准、commit 和 PR 流程。
CODE_OF_CONDUCT.md
Contributor Covenant 2.1（适用于协作项目）。
AGENTS.md
为 LLM Agent 提供上下文（技术栈、流程、规则、tgrep）。
.opencode/rules/tgrep.md
OpenCode Agent 使用 tgrep 进行搜索的规则。
.github/pull_request_template.md
PR 模板（Conventional Commits + checklist）。
.github/ISSUE_TEMPLATE/
bug、功能和调查（spike）表单。
.github/workflows/ci.yml
CI：pre-commit + 测试。
.github/workflows/labels.yml
根据 
.github/labels.yml
同步 labels。
.github/labels.yml
仓库 labels 的唯一事实来源。
.github/dependabot.yml
自动更新依赖（
uv
和 Actions）。
src/<paquete>/
package 代码（src-layout）。
tests/
pytest 测试（AAA 模式）。
docs/
文档、ADR、spike 和研究记录。
docs/arquitectura.{json,html}
交互式架构图（Archify）；JSON 是源文件。参见 
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:
MarcadorSignificado
{{PROJECT_NAME}}
Nombre legible (
Mi Proyecto
).
{{PROJECT_SLUG}}
Identificador kebab-case (
mi-proyecto
), usado como carpeta y repo.
{{PACKAGE_NAME}}
Identificador snake_case (
mi_proyecto
), 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}}
.
assets/templates/
下的模板使用标记占位符，脚手架工具会替换这些标记。如果手动编辑，请全部替换：
标记含义
{{PROJECT_NAME}}
易读名称（
Mi Proyecto
）。
{{PROJECT_SLUG}}
kebab-case 标识符（
mi-proyecto
），用作文件夹和仓库名称。
{{PACKAGE_NAME}}
snake_case 标识符（
mi_proyecto
），用作 Python package 名称。
{{DESCRIPTION}}
单行描述。
{{OWNER}}
/ 
{{REPO}}
仓库所属账户和仓库名称。
{{REPO_URL}}
/ 
{{SSH_URL}}
仓库的 HTTPS 和 SSH URL。
{{AUTHOR}}
/ 
{{AUTHOR_EMAIL}}
作者姓名和邮箱。
{{PYTHON_VERSION}}
Python 版本（
3.13
）。
{{YEAR}}
/ 
{{DATE}}
年份和 ISO 日期。
条件块（当对应参数为 false 时会被删除）： 
{{#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):
ReferenciaContenido
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.
仅在需要时加载以下文件（渐进式披露）：
参考文档内容
references/constitution.md
逐节介绍 
CONSTITUTION.md
的完整结构，并提供示例。
references/python-stack.md
uv
、
pyproject.toml
、Ruff、Makefile、pre-commit、
.editorconfig
、
.gitignore
。
references/github.md
创建仓库、SSH remote、徽章、模板、CI、Dependabot、labels 和分支。
references/agent-context.md
AGENTS.md
、
.opencode/rules/
和 tgrep。
references/git-identity.md
自动 Git 身份（
includeIf
）：Jan 配置及其他用户在 macOS/Windows 上的个人配置。
references/archify.md
使用 Archify 创建交互式架构图（安装、类型、validate/deliver、README）。
references/slidev.md
使用 Slidev 制作演示文稿（课程项目）：monolith、hub、语法规则和导出。

Identidad Git automática (
includeIf
)

自动 Git 身份（
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
).
配置 Git，使指定文件夹下的所有仓库自动使用同一个姓名、邮箱和 SSH 密钥。这是该标准中最实用的组成部分之一：无需再为每个项目设置参数和执行 
gh auth
。该机制包含两种配置，Agent 必须判断适用哪一种（详情参见 
references/git-identity.md
）。

Perfil A — Ejemplo (configuración del autor de la skill)

配置 A — 示例（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/
:
ini
undefined
这只是一个真实可运行的配置示例。其他用户应使用配置 B 并填写自己的数据。
示例规范文件夹 
~/Desktop/Repositorios/personal/
：
ini
undefined

~/.gitconfig

~/.gitconfig

[includeIf "gitdir:~/Desktop/Repositorios/personal/"] path = ~/.gitconfig-personal

```ini
[includeIf "gitdir:~/Desktop/Repositorios/personal/"] path = ~/.gitconfig-personal

```ini

~/.gitconfig-personal

~/.gitconfig-personal

[user] name = Jan Polanco V. email = hamsomp3@gmail.com [core] sshCommand = ssh -i ~/.ssh/id_ed25519 -o IdentitiesOnly=yes

**Efecto:** 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.
[user] name = Jan Polanco V. email = hamsomp3@gmail.com [core] sshCommand = ssh -i ~/.ssh/id_ed25519 -o IdentitiesOnly=yes

**效果：** 该文件夹下的所有仓库都会使用示例中的姓名、邮箱和密钥。优先使用 **SSH** remote（`git@github.com:<tu-usuario>/<repo>.git`）；HTTPS 可以使用其他账户的 token 进行身份验证。

Perfil B — Cualquier otro usuario (alumno, compañero)

配置 B — 其他所有用户（学生、同事等）

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:
bash
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
如果用户要求自动身份配置，并且不使用示例中的配置，应先询问其姓名、邮箱、SSH 密钥和项目文件夹，然后针对其文件夹和其操作系统（macOS 或 Windows）配置 
includeIf
。可以使用现成脚本：
bash
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 windows

Windows: --key C:/Users/pedro/.ssh/id_ed25519 --dir C:/Users/pedro/Repos --platform windows


El 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`](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**.

---

该脚本会备份 `~/.gitconfig`，具备幂等性，并提供 `--print` 模式，仅展示配置块而不写入任何内容。手动配置步骤和注意事项（`includeIf` 顺序、`gitdir/i:`、Windows 中带 `/` 的路径、`IdentitiesOnly`）参见 [`references/git-identity.md`](references/git-identity.md)。

> ⚙️ **绝不提交：** 这是**机器本地配置**。在章程中仅可将其记录为**备注**（而不是仓库文件），并且**仅在用户要求时**应用。

---

Flujo diario (commit + push)

日常流程（commit + push）

bash
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. subir
bash
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. subir

Checklist de verificación

验证 Checklist

Antes de dar por terminado un proyecto o un cambio:
  • CONSTITUTION.md
    existe y está poblado (propósito, stack, estructura, flujo, decisiones).
  • uv sync
    funciona y 
    uv.lock
    está versionado.
  • make check
    pasa en verde (lint + formato + pruebas).
  • uv run pre-commit run --all-files
    pasa (hooks instalados).
  • README.md
    tiene badges, TOC, descripción, stack, primeros pasos y licencia.
  • LICENSE
    presente (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.
在将项目或变更标记为完成之前：
  • CONSTITUTION.md
    已存在并完成填充（目的、技术栈、结构、流程、决策）。
  • uv sync
    可以正常运行，且 
    uv.lock
    已纳入版本控制。
  • make check
    全部通过（lint + 格式化 + 测试）。
  • uv run pre-commit run --all-files
    通过（hooks 已安装）。
  • README.md
    包含徽章、目录、描述、技术栈、初始步骤和许可证。
  • 已提供 
    LICENSE
    （默认采用 MIT）。
  • .github/
    包含 PR 模板、issue 模板、CI、Dependabot 和 labels（如适用）。
  • AGENTS.md
    （以及 
    .opencode/rules/tgrep.md
    ）已向 Agent 描述项目（如适用）。
  • 已配置自动 Git 身份**（仅当用户要求时）**（Jan 使用配置 A，其他用户使用配置 B）。
  • 架构图已通过 Archify 生成并保存在 
    docs/
    中，同时已从 README 链接（如适用）。
  • 未将机密信息、个人数据或大型产物纳入版本控制。
  • 章程中的决策历史记录了所有重要变更。

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.
每当进行重要变更（新增功能、架构调整、添加 class/module 或调整技术选型）时，必须在同一次 commit 中更新 
CONSTITUTION.md
，以维护项目的唯一事实来源。Pull Request 模板中的 checklist 会明确检查此项。