Introduction

Shingan (心眼) est un framework léger et réutilisable pour orchestrer le développement assisté par IA. Inspiré de BMAD Method.

Pourquoi ce framework ?

Travailler avec un AI coding agent (Claude Code, Cursor, Copilot...) est puissant, mais sans structure :

• L'IA fait des choix architecturaux incohérents
• Les reviews de code sont superficielles
• Les bugs sont patchés sans comprendre la root cause
• Le contexte se perd entre les sessions

Ce framework résout ces problèmes en fournissant :

1. Des personas — rôles IA spécialisés avec contraintes claires
2. Des skills — workflows réutilisables invocables via /commande
3. Des agents — sous-agents ciblés pour des tâches spécifiques
4. Des profiles — contexte technologique par stack (Rust, Python, Java...)
5. Des modèles configurables — opus, sonnet ou haiku selon le rôle
6. Des workflows — pipelines orchestrant le tout avec des gates

Architecture

framework/
├── personas/            ← Rôles IA (analyst, architect, developer, reviewer)
├── skills/
│   ├── workflows/       ← Pipelines multi-steps (apex, bugfix, review-code, debug...)
│   ├── actions/         ← Commandes directes (commit, init, oneshot, profile...)
│   ├── creators/        ← Générateurs (create-skill, create-prompt...)
│   └── deprecated/      ← Skills obsolètes
├── agents/              ← Sous-agents spécialisés (8 agents)
├── profiles/            ← Contexte technologique (rust, tauri, vue...)
├── models.md            ← Configuration centralisée des modèles
├── scripts/             ← Hooks d'automatisation
├── workflows/           ← Pipelines visuels
└── templates/           ← Documents standardisés (PRD, ADR)

Concepts clés

Progressive Disclosure

Le framework charge le contexte progressivement pour ne pas saturer la fenêtre de l'IA :

Niveau	Contenu	Quand
1 — Découverte	Frontmatter YAML (nom, description)	L'IA sait quand utiliser le skill
2 — Activation	Corps du SKILL.md	Instructions étape par étape
3 — Détails	REFERENCE.md + resources/	Contexte approfondi si nécessaire

Steps avec Gates

Chaque skill a des étapes numérotées. On passe à la suivante en tapant next. Chaque step produit un output (fichier) que le step suivant consomme.

Step 01 → [Gate: output validé?] → Step 02 → [Gate] → Step 03 → ...

State Management via Fichiers

L'état est géré par les fichiers produits — pas de base de données :

docs/
├── specs/       ← Output analyst (PRD)
├── plans/       ← Output architect (ADR)
├── reviews/     ← Output reviewer
├── bugs/        ← Output bugfix
└── apex/        ← Output APEX

Pour qui ?

Ce framework est conçu pour le développeur qui utilise un AI coding agent au quotidien et veut :

• Structurer ses interactions avec l'IA
• Avoir des workflows reproductibles
• Garder une trace des décisions
• Maintenir la qualité du code

Profiles technologiques

Les profiles injectent des conventions spécifiques à votre stack dans tous les personas. Un architecte avec le profil rust propose des patterns Tauri et tokio. Sans profil, il propose des solutions génériques.

# Dans CLAUDE.md
profile: rust, tauri, vue-typescript

Modèles configurables

La configuration des modèles permet de choisir quel modèle (opus, sonnet, haiku) utilise chaque persona et agent. Trois presets sont disponibles : budget, standard, quality.

# Dans CLAUDE.md
models:
  preset: standard
  override:
    developer: opus

Prêt à commencer ?

La méthode la plus simple est l'installation via plugin — une seule commande et Shingan est disponible. Pour personnaliser le framework, voir l'installation manuelle.