CommunityRédaction et éditiongithub.com

ultraindex

Indexe l'intégralité d'un dépôt (code + documentation) en une encyclopédie navigable analysée par IA — avec une carte, des entrées par module et un graphe de liens typé — pour qu'une IA travaille sur de grosses codebases sans saturer son contexte. Un skill skills.sh à routage automatique avec analyse vérifiée par citations et recherche sémantique locale (Ollama) optionnelle.

Qu'est-ce que ultraindex ?

Ce skill transforme un dépôt volumineux en une encyclopédie structurée et navigable, résolvant le problème de saturation du contexte de l'IA. Il repose sur un moteur déterministe sans dépendance (ultraindex.mjs) qui effectue le travail mécanique : scan du projet, construction d'un graphe de liens typés et génération de l'encyclopédie. L'IA conserve la responsabilité de l'analyse métier, rédigée à partir de preuves réelles avec des citations vérifiées [fichier:ligne]. Le skill supporte Claude Code, Cursor, Codex et tout agent compatible skills.sh, avec une recherche sémantique optionnelle via Ollama. Son utilisation typique alterne entre construction de l'index, enrichissement par modules, navigation pour répondre à des questions, et vérification haute-assurance par validation contradictoire des citations.

Compatible avec~Claude Code~Codex CLI~Cursor
npx skills add maxgfr/ultraindex

Installed? Explore more Rédaction et édition skills: steipete/notion, langchain-ai/langchain, bytedance/podcast-generation · View all 6 →

Demander à votre IA préférée

Ouvre une nouvelle conversation avec cette compétence d'agent déjà préchargée.

Documentation

ultraindex — construire et naviguer dans une encyclopédie analysée par IA de l'ensemble d'un dépôt

Sur un dépôt volumineux, la fenêtre de contexte se sature avant que vous trouviez ce qui compte. ultraindex corrige cela par une division du travail : le moteur déterministe sans dépendance (node scripts/ultraindex.mjs <commande> — pas de npm install, pas de clés API, lancez --help pour la surface complète) effectue le travail mécanique — scanner le projet, construire le graphe de liens, organiser l'encyclopédie ; vous faites la compréhension — une analyse fondée et citée — et naviguez ensuite dans le résultat au lieu de lire le dépôt.

Les règles fondamentales :

  1. Le moteur possède la vue code et le graphe (régions ui:gen) — régénérées à chaque construction ; ne les modifiez jamais à la main.
  2. Vous possédez la vue métier (régions ui:human). build préserve votre prose lors des reconstructions et des renommages.
  3. Analysez à partir de preuves, pas de mémoire. Rédigez l'analyse uniquement à partir des sources réelles que dossier vous montre, citez-les [fichier:ligne], et check échoue sur toute citation qui ne résout pas — donc ne devinez pas.
  4. Chargez le minimum. Lisez une entrée (ou un dossier) à la fois — c'est le schéma prévu, et exactement ce que fait un sous-agent d'enrichissement par module. Ne chargez jamais en masse graph.json ou tout le répertoire encyclopedia/ dans le contexte — cela va à l'encontre du but.

La plupart des commandes acceptent --json — préférez-le chaque fois que vous utilisez le résultat pour une branchement plutôt que de le lire comme du texte.

Router selon la situation

Déterminez dans quelle situation vous vous trouvez, dans cet ordre, et lisez la référence correspondante pour le workflow détaillé :

  1. Pas encore d'index — aucun .ultraindex/ ou docs/ultraindex/ à la racine du dépôt (cherchez graph.json à l'intérieur). Construisez-le, puis enrichissez les modules principaux : lisez references/generate.md.

  2. L'index existe — vérifiez d'abord sa fraîcheur. node scripts/ultraindex.mjs check --out <index-dir> --json. S'il signale des éléments obsolètes ou cassés, relancez build (votre prose survit), puis continuez. Si seuls des fichiers non pertinents pour la tâche ont changé, vous pouvez procéder et le noter.

  3. L'utilisateur a une tâche ou une question ("où est X", "comment fonctionne Z", "quels fichiers dois-je modifier") — naviguez dans l'index, ouvrez uniquement les fichiers qu'il pointe, fondez les réponses avec des citations vérifiées : lisez references/navigate.md.

  4. La réponse doit être hautement fiable (audit, sécurité, affirmation critique pour l'exactitude), ou l'utilisateur vous demande de vérifier/trancher une réponse — après que check --answer a réussi (les citations résolvent), escaladez vers la porte de vérification sémantique pour que chaque extrait cité soit prouvé comme soutenant son affirmation, et non simplement existant : lisez references/verify.md.

  5. L'utilisateur a demandé d'indexer/analyser/documenter, ou status --json montre des hubs non enrichis et vous avez du budget — exécutez la boucle d'enrichissement pilotée par le statut (dossier → écrire une analyse citée → check). Sur un gros dépôt, cela se parallélise : un sous-agent par module depuis la file d'attente, si votre hôte supporte les sous-agents — lisez references/generate.md.

  6. find ne trouve rien, ou l'utilisateur veut une meilleure recherche (sémantique) — mettez en place la couche d'embeddings optionnelle (docker compose, embed, find hybride) : lisez references/semantic.md.

Une première visite typique enchaîne 1 → 5 → 3 ; une visite de retour est habituellement 2 → 3 ; une réponse hautement fiable ajoute → 4.

Aide-mémoire des commandes

  • build --repo <dossier> [--out .ultraindex] [--include/--exclude <glob>] [--max-bytes <n>] [--max-files <n>] [--no-cache] [--no-mermaid] — scanner et (ré)écrire l'index. Idempotent ; conserve la prose enrichie. Incrémental (réutilise l'extraction des fichiers inchangés) ; avertit si --max-files tronque. --out docs/ultraindex pour un index commité et révisable par PR.
  • map [--module <slug>] [--json] — afficher INDEX.md (ou une entrée, ou la table des modules).
  • find "<requête>" [--k <n>] — classer les modules, afficher les fichiers exacts à ouvrir. Lexical par défaut (avec pondération IDF) ; hybride (+ sémantique) quand vectors.json existe.
  • neighbors <fichier|module> [--depth <n>] — ce qui pointe vers / depuis lui.
  • symbols "<nom>" [--json] — où un symbole est défini (fichier:ligne, type, module propriétaire) et quels fichiers le référencent. Flou par sous-jeton d'identifiant.
  • impact <fichier|module> [--depth <n>] [--json] — la fermeture des dépendances inverses : tout ce qui importe ou utilise la cible. "Ce qui casse si je modifie ceci."
  • status — la file d'attente d'enrichissement, dans l'ordre exact à enrichir.
  • dossier <slug> — le paquet de preuves d'un module (code source réel + voisins ; un module de docs/config uniquement, e.g. root, n'affiche pas de code — enrichissez-le en citant son README/config à la place).
  • ask "<question>" — assembler des preuves fondées pour répondre.
  • check [--answer <fichier>] [--semantic] — fraîcheur + intégrité + fondement (les citations doivent résoudre). Code de sortie non nul ⇒ obsolète, cassé ou non fondé. --semantic intègre également la porte de vérification (échoue sur une affirmation dont l'extrait cité la réfute, ou qui est entièrement tranchée sans support) ; il réduit le verdict à partir des verdicts[] bruts et relit chaque extrait tranché depuis le dépôt réel — un résumé falsifié ou une source modifiée échoue, jamais ne passe.
  • verify --answer <fichier> [--apply <verdicts.json>] [--max-verify <n>] — la porte de haute assurance au-dessus de check --answer : émet une liste de travail affirmation↔citation pour une vérification contradictoire, puis --apply réduit vos verdicts en une porte passe/échoue. Voir references/verify.md.
  • embed [--force] — construire/rafraîchir vectors.json pour la recherche find sémantique (nécessite un fournisseur — voir references/semantic.md).

Notes de périmètre

  • Pas de clés, pas de réseau, déterministe (la couche sémantique optionnelle est la seule exception, et elle dégrade vers lexicale quand son fournisseur est absent). Deux constructions d'un dépôt inchangé sont identiques octet pour octet sauf pour manifest.json's builtAt (horodatage de provenance) ; vectors.json est également exclu (ses flottants dépendent du fournisseur).
  • Symboles AST exacts grâce aux grammaires tree-sitter embarquées pour JS/TS/TSX, Python, Go, Rust, Java, C, C++, C#, Ruby, PHP — imbrication réelle, types précis, export structuré. Les autres langages utilisent des extracteurs regex (restent recherchables). Les grammaires wasm sont livrées dans le bundle, donc toujours pas de npm install au moment de l'utilisation du skill (l'installation est plus lourde — ~17 MiB de wasm).
  • Arêtes d'import pour JS/TS (tsconfig paths, package exports maps), Python, Go (multi-module + replace), Rust (mod/use), Java (packages), C/C++ (#include "..."), Ruby (require_relative/require), PHP (composer PSR-4 + require relatif), C# (using → namespace). Plus des arêtes use code→code prudentes quand un fichier référence un symbole exporté unique d'un autre fichier sans l'importer. Les langages restants n'ont pas d'arêtes d'import. Le système de fichiers virtuel de Yarn PnP est hors périmètre (les noms d'espace de travail résolvent quand même).
  • Les arêtes pendantes indiquent généralement le dépôt lui-même qui a des imports cassés ou des liens de documentation obsolètes — c'est un constat à signaler, pas à dissimuler.

Skills associés