CommunityRédaction et éditiongithub.com

Shaelz/codebase-orient-skill

Une compétence réutilisable d'orientation dans le code source pour Claude Code et Codex.

Qu'est-ce que codebase-orient-skill ?

Cette compétence, `codebase-orient`, est conçue pour aider les agents IA comme Claude Code et Codex à comprendre rapidement l'état actuel d'un dépôt de code avant d'entreprendre un travail non trivial. Elle crée ou met à jour un ensemble standardisé de quatre artefacts dans le dossier `docs/ai/`, servant de cache d'orientation pour réduire les coûts de découverte répétée du dépôt entre les sessions et les passations d'agents. La compétence définit des règles strictes : ne pas modifier le code source, ne pas refactoriser, ne pas commiter, et vérifier toute affirmation par rapport au code source avant de l'écrire. Elle fournit également des directives pour le mode normal (exécution complète) et le mode simulation (rapport seul), des étiquettes de confiance détaillées, un ordre de découverte générique, des sondes spécifiques pour SvelteKit, et des règles de précision pour l'intégration continue et le déploiement, garantissant ainsi une orientation fiable et efficace pour tout projet.

Compatible avec✓Claude Code✓Codex CLI~Cursor
npx skills add Shaelz/codebase-orient-skill

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

Compétence : codebase-orient

Objectif

Orienter Claude sur l'état actuel de ce dépôt avant un travail non trivial. Cela crée ou réconcilie un ensemble fixe de quatre artefacts, basés sur une provenance, dans docs/ai/. Le code source et la configuration du projet restent l'autorité.

Quand utiliser cette compétence

Utilisez cette compétence lorsque

  • Vous entrez dans un dépôt nouveau ou inconnu
  • Vous commencez une nouvelle session après un temps significatif passé loin du dépôt
  • Avant un travail d'implémentation large ou multi-fichier
  • Avant des refontes, nettoyages, planification d'architecture ou passation d'agent
  • Après des changements structurels : routes, schéma, authentification, déploiement, configuration ou surfaces d'administration
  • Lorsque docs/ai/ est manquant, obsolète, incomplet ou incohérent en interne
  • Lorsque la structure du dépôt, les surfaces de changement, les cibles de déploiement, le comportement d'authentification, les routes d'administration, les commandes ou la forme des tests ne sont pas clairs
  • Lorsque l'agent passerait autrement un contexte significatif à redécouvrir ce qui est déjà dans ou près de docs/ai/
  • Chaque fois que l'utilisateur dit "scanner", "orienter", "comprendre", "cartographier", "réviser", "auditer", "enquêter", "familiariser" ou "avant de commencer"

Ignorez cette compétence lorsque

  • Vous effectuez une petite modification locale et connue sur un seul fichier
  • Vous corrigez un bug dans un fichier unique où le fichier concerné et la modification sont déjà clairs
  • Vous effectuez des changements uniquement de copie ou de chaîne de caractères
  • La tâche est limitée à des fichiers déjà vérifiés dans le contexte actuel
  • docs/ai/ vient d'être rafraîchi et la tâche est suffisamment étroite pour ne pas nécessiter un passage d'orientation complet

Conseils d'utilisation tenant compte des tokens

docs/ai/ est un cache d'orientation. Un cache frais réduit le coût en tokens de la redécouverte répétée du dépôt entre les sessions et les passations d'agent.

  • Si docs/ai/ est frais et complet : lisez-le comme contexte et procédez. Ignorez la réexécution de l'orientation.
  • Si docs/ai/ peut être obsolète ou est manquant : exécutez la compétence pour rafraîchir le cache. Le coût initial en tokens est amorti sur le travail à venir.
  • Si la tâche est minuscule et que le fichier cible est déjà connu : ignorez l'orientation. Utilisez plutôt des lectures ciblées.
  • Si l'agent passerait de nombreux tokens à redécouvrir ce que docs/ai/ capture déjà : rafraîchissez-le.

N'économisez pas les tokens en ignorant l'orientation et en devinant la structure. Si une découverte large du dépôt serait autrement répétée ou coûteuse, rafraîchissez le cache à la place.

Règles strictes pendant l'orientation

  • Ne modifiez pas le code applicatif ou source.
  • Ne refactorisez pas.
  • Ne commitez pas.
  • Vérifiez les affirmations par rapport au code source avant de les écrire.
  • Marquez chaque affirmation significative avec une étiquette de confiance.

Mode normal vs mode simulation

Mode normal (par défaut - à utiliser lorsque l'utilisateur ne précise pas) :

  • Résolvez automatiquement les petites incertitudes pertinentes à la tâche en lisant les fichiers sources
  • Créez un package complet lors de la première utilisation dans un dépôt propre
  • Réutilisez un package propre exactement actuel sans le réécrire
  • Traitez une demande non spécifique de rafraîchissement ou de réconciliation comme une réconciliation complète
  • Signalez ce qui a changé à la fin

Mode simulation / rapport seul (à utiliser lorsque l'utilisateur dit "simulation", "rapport seulement", "n'écris pas", "propose d'abord des changements", "audit seulement", "pas d'écriture", ou similaire) :

  • Inspectez et collectez les changements proposés
  • Rapportez les modifications proposées à docs/ai/ sans les écrire
  • Attendez une approbation explicite avant d'écrire

Si le mode n'est pas spécifié, utilisez par défaut le mode Normal.

Cycle de vie et sécurité d'écriture

  • Rafraîchissement explicite : Rafraîchissez ou réconciliez uniquement lorsque l'utilisateur le demande explicitement après qu'un package exactement actuel a été trouvé.
  • Rafraîchissement ciblé : Suivez un périmètre explicite de l'utilisateur et ses dépendances directes. Enregistrez la couverture ciblée sans avancer ni revendiquer une capture complète du package entier. Ne créez pas de package partiel pris en charge avant qu'un package complet n'existe.
  • Adoption héritée : Les artefacts Markdown sans ORIENTATION_STATE.json sont du matériel hérité. Inspectez-les, mais obtenez une approbation explicite avant d'écrire un manifeste ou de les modifier. Reconciliez à partir de la source après approbation.
  • Arbre sale : Avant d'écrire un état représentant un travail non commité, demandez s'il faut écrire une capture sale ou seulement un rapport. Enregistrez la condition de l'arbre ; maintenez-le marqué comme sale jusqu'à ce qu'un rafraîchissement propre le remplace.
  • Pas d'historique Git utilisable : Effectuez une réconciliation complète et enregistrez que la comparaison de révisions est indisponible.
  • Modifications manuelles : Orient possède le package. Ne promettez pas de comportement de fusion ou de conservation pour l'état Orient modifié manuellement.

Étiquettes de confiance

  • Fait : vérifié directement dans le code ou la documentation
  • Inférence forte : soutenue par plusieurs fichiers
  • Inférence faible : plausible mais non confirmé
  • Inconnu : nécessite plus d'inspection avant modification

Distinguez comment une affirmation a été établie :

  • vérifié indépendamment à partir de la source/configuration : affirmation vérifiée par rapport au fichier source ou de configuration réel, non tirée de la documentation
  • hérité de la documentation existante : affirmation tirée de CLAUDE.md, README ou autre documentation sans vérification indépendante
  • hérité puis vérifié : affirmation provenant de la documentation et ensuite confirmée par rapport à la source
  • existence du chemin confirmée : fichier trouvé mais pas lu
  • lecture partielle : une partie du fichier inspectée ; peut ne pas capturer le contexte complet
  • lecture source complète : contenu complet du fichier inspecté
  • inféré à partir de l'implémentation : déduit du comportement du code, pas explicitement indiqué
  • inféré à partir de commentaires/tests/fixtures : provenant d'un contexte non autoritaire ; traiter comme Inférence forte au mieux
  • comportement vérifié par test : confirmé par l'exécution réussie d'un test
  • inconnu : base non établie ; ne pas présenter comme Fait

Dans les rapports finaux et la documentation d'orientation, étiquetez chaque affirmation non triviale avec l'une des origines ci-dessus afin que les lecteurs puissent juger quelles affirmations nécessitent une re-vérification avant d'agir sur elles.

Ordre de découverte

Note de personnalisation : L'ordre de découverte ci-dessous est intentionnellement large et fonctionne sur la plupart des formes de projet sans modification. Vous pouvez ajuster les chemins de fichiers et l'ordre pour un projet spécifique, mais cela est optionnel – pas requis avant la première utilisation.

Exécutez dans cet ordre :

  1. Fichiers d'instructions du projet tels que CLAUDE.md, AGENTS.md et README.md, s'ils sont présents – objectif du produit, règles de l'agent, conventions du projet. Règle des documents comme hypothèses
    • Traitez ces documents comme des hypothèses utiles, pas comme une vérité absolue.
    • Extrayez les affirmations factuelles à fort impact sur l'architecture, les routes, le déploiement, les tests et les fichiers source de vérité.
    • Vérifiez ces affirmations par rapport au code source avant de vous y fier. Concentrez-vous sur les affirmations qui affecteraient les futures modifications ; n'auditez pas chaque phrase.
    • Ne copiez pas les affirmations de ces documents dans CODEBASE_MAP.md sans étiqueter si elles sont vérifiées indépendamment à partir de la source/configuration ou héritées de la documentation existante.
    • Si un document d'instruction est obsolète ou trompeur par rapport à ce que la source montre, enregistrez la dérive dans OPEN_QUESTIONS.md sous la règle de signalement des risques cachés et étiquetez-la comme dérive de documentation.
    • Cartographiez la topologie de la couche d'instructions : notez quels fichiers d'instructions sont présents (par exemple, CLAUDE.md, AGENTS.md, .claude/settings.json) et à quelle portée (locale au projet vs niveau utilisateur). Enregistrez cela dans CODEBASE_MAP.md ; cela aide les futurs agents à savoir quelles règles s'appliquent.
  2. Manifeste du projet (par exemple, package.json, pyproject.toml, Cargo.toml) – dépendances, scripts, commandes de construction/test
  3. Fichiers de construction et de configuration (par exemple, configuration du framework, configuration du bundler) – adaptateur, configuration de construction
  4. Répertoire scripts/, s'il est présent – peut contenir des outils exécutés manuellement non représentés dans les scripts du package ou CI
  5. Points d'entrée et couche de routage – toutes les pages, contrôleurs ou routes API
  6. Logique métier principale – types de domaine, modèles, notation, logique de rapport
  7. Services côté serveur – authentification, base de données/schéma, email, intégrations externes
  8. Couche UI/présentation – composants, vues, templates
  9. Fichiers d'internationalisation ou de copie – fichiers de locale
  10. Cycle de vie des requêtes / middleware – hooks, intercepteurs, middleware
  11. Couche de base de données – migrations, instantanés de schéma
  12. Tests – structure des tests et forme de couverture
  13. Documentation – documentation existante, matrices de vérification. Si un plan de publication, un document de suivi des jalons ou un journal des modifications de version est trouvé, ajoutez une section ## Statut de publication à CODEBASE_MAP.md résumant la version actuelle, le jalon actif et ce qui bloque la prochaine publication. Omettez cette section si aucun artefact de cycle de vie de publication n'est présent.
  14. Incertitude connue

Sondes spécifiques au framework

Appliquez ces sondes en plus de l'ordre de découverte générique lorsque le framework pertinent est détecté.

La compétence réutilisable inclut actuellement un ensemble de sondes ajustées explicite pour SvelteKit. Les autres frameworks utilisent actuellement l'ordre de découverte générique, sauf si des preuves ultérieures en conditions réelles ou d'évaluation justifient une section de sonde ajustée dédiée.

SvelteKit

Recherchez les motifs de fichiers suivants lorsqu'un projet SvelteKit est détecté :

  • src/routes/**/+page.svelte : pages de route UI ; chaque fichier est un candidat de route ; vérifiez les sous-répertoires, pas seulement le src/routes/+page.svelte de premier niveau
  • src/routes/**/+page.server.ts : chargement de données côté serveur, actions de formulaire et contrôle d'accès au niveau de la route
  • src/routes/**/+layout.svelte : coques de mise en page partagées
  • src/routes/**/+layout.server.ts : fonctions de chargement côté serveur pour l'authentification, la session ou les données au niveau de la mise en page
  • src/routes/**/+server.ts : endpoints API et gestionnaires de requêtes côté serveur uniquement

Les fichiers de route côté serveur (+page.server.ts, +layout.server.ts, +server.ts) sont critiques pour comprendre l'authentification, le chargement des données, les actions de formulaire, les endpoints API et le contrôle d'accès au niveau de la route. Ne les ignorez pas lors de la cartographie des routes ou des surfaces de changement.

  • Le template standard de coque d'application est src/app.html.
  • Le choix de l'adaptateur dans svelte.config.js détermine la cible de déploiement – confirmez avant de faire des affirmations liées au déploiement.

Règle de précision CI/déploiement

Lors de la lecture des fichiers de workflow CI ou de déploiement, conservez les détails opérationnellement pertinents. N'arrondissez pas les spécificités en résumés vagues.

Capturez et rapportez :

  • le nom du groupe de concurrence (quelles exécutions sont en compétition entre elles)
  • le comportement cancel-in-progress – si true, dites "les exécutions plus récentes annulent les exécutions en cours du même groupe", pas simplement "empêche les déploiements parallèles"
  • le comportement fail-fast
  • les chemins des artefacts de déploiement
  • le format de nommage des versions incluant tout composant d'horodatage ou de hachage
  • la politique de rétention et de nettoyage pour les anciennes versions ou artefacts
  • les conditions de déclenchement manuelles vs automatiques
  • les secrets et variables d'environnement requis
  • si le déploiement écrase sur place, prépare vers un chemin temporaire, utilise des liens symboliques ou utilise des répertoires de versions versionnés

Étiquetez les affirmations CI/déploiement avec vérifié indépendamment à partir de la source/configuration lorsqu'elles sont lues directement à partir du fichier de workflow. Ne résumez pas ces détails d'une manière qui perd la précision dont un opérateur aurait besoin lors d'un incident.

Heuristique de profondeur de lecture

Ne lisez pas par défaut chaque grand fichier CSS, de configuration ou généré.

  • Lecture complète : fichiers qui affectent directement la tâche demandée (points d'entrée, routage, authentification, schéma, configuration de construction, le fichier à modifier).
  • Lecture partielle ou confirmation de chemin uniquement : surfaces secondaires telles que les grandes feuilles de style, le code externalisé, la sortie générée ou les fichiers de configuration non pertinents pour la tâche. Si vous confirmez seulement le chemin d'un fichier ou lisez une partie, dites-le explicitement dans le rapport en utilisant les étiquettes existence du chemin confirmée ou lecture partielle définies dans les Étiquettes de confiance.
  • Ignorer : fichiers clairement hors de portée (par exemple, ressources binaires, fichiers de verrouillage, instantanés de test) sauf si une question spécifique les rend pertinents.

En cas de doute, préférez d'abord confirmer l'existence et ne lisez complètement que si une affirmation l'exige.

Existence du chemin vs lecture du contenu

L'existence du chemin seule est suffisante pour les affirmations d'inventaire à faible risque – confirmer une structure de répertoire, lister les nombres de fichiers ou noter qu'un fichier de configuration est présent.

Lisez le contenu réel du fichier lorsque l'affirmation affecte le comportement, l'architecture, le risque, les commandes, le déploiement, l'authentification, le routage ou les surfaces de changement. N'étiquetez pas une affirmation comme vérifié indépendamment à partir de la source/configuration basée uniquement sur l'existence du chemin lorsque le fichier est peu coûteux à inspecter et que son contenu affecterait matériellement la carte.

Règle de lecture des petits fichiers source de vérité

Si un petit fichier semble définir un vocabulaire ou des jetons source de vérité utilisés dans tout le projet, lisez-en suffisamment pour vérifier le vocabulaire plutôt que d'hériter du vocabulaire de la documentation.

Exemples où cela s'applique :

  • fichiers de jetons de propriétés personnalisées CSS
  • fichiers de configuration de route ou de menu
  • petits fichiers de schéma ou de constantes
  • registres de commandes ou de plugins

Utilisez une lecture partielle lorsque cela est suffisant. Étiquetez les affirmations résultantes avec l'origine de revendication appropriée (lecture partielle, lecture source complète). Ne les étiquetez pas comme vérifié indépendamment à partir de la source/configuration si vous n'avez pas réellement lu le fichier.

Règle de recherche globale peu coûteuse

Avant de laisser une question ouverte sur l'existence ou la portée des ressources statiques, scripts, sorties générées, documentation, tests, migrations ou fichiers de configuration, résolvez-la avec une recherche globale peu coûteuse.

Modèles de recherche courants à essayer :

  • static/**/*
  • public/**/*
  • scripts/**/*
  • tests/**/* ou test/**/* ou spec/**/*
  • .github/workflows/*
  • docs/**/*
  • migrations/**/*
  • dist/**/* ou build/**/*

Ne lisez pas en profondeur tous les fichiers correspondants par défaut. Utilisez la recherche globale pour résoudre les questions d'existence et de portée à moindre coût. Effectuez des lectures ciblées uniquement lorsque le contenu d'un fichier spécifique est nécessaire.

Skills associés