Le problème : le spaghetti de prompts

Quand j'ai commencé à construire mon setup Claude Code, tout vivait partout. Des commandes éparpillées dans des fichiers random. Des skills qui dupliquaient de la logique. Des agents qui ne trouvaient pas leurs dépendances. Ça te parle ?

Le déclic est venu quand j'ai arrêté de traiter les assets IA comme "juste des prompts" et que j'ai commencé à les traiter comme du code.

Le principe fondamental : la colocation

Les fichiers qui changent ensemble vivent ensemble.

Ce n'est pas nouveau. C'est le même principe qui guide :

L'insight : ça s'applique aux assets Claude Code aussi.

À quoi ça ressemble ?

Avant : structure éclatée

commands/
  jira.md
  git.md
  prep.md
scripts/
  jira-create.sh
  jira-status.sh
  git-worktree.sh
skills/
  random-skill-1.md
  another-skill.md

Problèmes :

Après : plugins colocalisés

marketplace/plugins/jira/
├── .claude-plugin/
│   └── manifest.json      # Métadonnées du plugin
├── SKILL.md               # Point d'entrée
├── scripts/               # Scripts shell (colocalisés !)
│   ├── jira_create.sh
│   └── jira_status.sh
└── skills/                # Sous-skills
    ├── reader/
    ├── creator/
    └── status/
        ├── SKILL.md
        └── reference/     # Connaissance pour ce skill uniquement

Maintenant :

Les trois niveaux de colocation

Niveau 1 : frontière du plugin

Un plugin est un bounded context. Il possède :

plugins/{domain}/
├── .claude-plugin/manifest.json
├── commands/       # Invocables par l'utilisateur
├── skills/         # Invocables par l'agent
├── scripts/        # Bash de support
└── knowledge/      # Matériel de référence

Niveau 2 : composition de skills

Les skills peuvent être hiérarchiques. Un skill de surface route vers des sous-skills spécialisés :

skills/code-writer/
├── SKILL.md           # Route vers les sous-skills
├── frontend/
│   ├── index.md       # Vue, Mozaic, i18n
│   └── vue/
│       ├── component.md
│       └── composable.md
├── backend/
│   └── index.md       # NestJS
└── testing/
    └── playwright/
        └── index.md   # Patterns E2E

Le skill de surface (code-writer) sait quand utiliser chaque sous-skill.

Les sous-skills savent comment faire des tâches spécifiques.

Niveau 3 : connaissance proche de l'usage

Le matériel de référence vit à côté du skill qui l'utilise :

skills/jira/status/
├── SKILL.md
└── reference/
    └── workflow-states.md  # Seul le skill status en a besoin

Pas dans un dossier docs/ global. Pas dans un fourre-tout references/ partagé.

Ici. Là où c'est utilisé.

Pourquoi c'est important pour l'IA

1. Le chargement de contexte coûte cher

Chaque fichier que Claude lit coûte des tokens. La colocation signifie :

2. Les agents partent de zéro

Quand tu spawnes un subagent, il n'a aucun contexte. Il ne connaît pas ta structure de dossiers. Il ne se souvient pas des conversations précédentes.

La colocation signifie : si un agent connaît le chemin de son skill, il sait tout ce dont il a besoin.

# L'agent charge : skills/code-writer/frontend/vue/
# Il a maintenant : component.md, composable.md, query.md
# Pas de devinette. Pas de recherche.

3. La maintenance devient évidente

Question : "Où j'ajoute les patterns de tests E2E ?"

Réponse : skills/code-writer/testing/playwright/

Question : "Comment je mets à jour les transitions de statut Jira ?"

Réponse : plugins/jira/skills/status/reference/

La structure encode la décision.

Patterns pratiques

Pattern : point d'entrée + table de routage

Chaque skill a un SKILL.md qui agit comme un routeur :

# code-writer

## Routing

| Tâche            | Référence                   |
| ---------------- | --------------------------- |
| Composants Vue   | `frontend/vue/component.md` |
| Services NestJS  | `backend/index.md`          |
| Tests Playwright | `testing/playwright/`       |

L'agent lit le point d'entrée, trouve le chemin pertinent, charge uniquement ce dont il a besoin.

Pattern : groupement par fréquence de changement

Demande-toi : "Quand est-ce que ce fichier change ?"

| Change quand... | Vit dans... |

| ------------------------- | ------------------ |

| La feature change | {feature}/ |

| Le domaine change | {domain}/ |

| Le framework/outil change | helpers/ partagé |

Pattern : supprimer = un seul dossier

Si supprimer une capacité nécessite de toucher plusieurs dossiers sans lien, ta structure est mauvaise.

Bien : rm -rf plugins/jira/

Mal : rm scripts/jira*.sh && rm commands/jira.md && rm skills/jira*.md

Le chemin de migration

Pas besoin de tout restructurer d'un coup.

Chaque étape est atomique. Chaque étape améliore les choses.

Conclusion

Les assets Claude Code sont du code. Traite-les comme tel.

Le résultat : un setup Claude Code qui scale, sur lequel tu peux raisonner, et qui ne te combat pas quand tu dois changer quelque chose.