Ce portfolio

Le besoin

Ce portfolio est écrit en HTML, CSS et JavaScript, sans framework ni étape de build. Simple en apparence, il cache pourtant des règles qu'on ne voit pas en lisant une seule page :

• les URLs sans .html en production sont gérées à trois endroits (le .htaccess et deux scripts) ;
• le script des pages projet est dupliqué : une correction doit être faite partout ;
• ajouter un projet oblige à modifier quatre fichiers ;
• les données structurées (JSON-LD) pour le référencement doivent rester du JSON valide.

Un agent IA qui découvre le projet voit le code, mais pas ces règles. Sans cadre, il peut produire un changement qui fonctionne en apparence et casse la production.

La solution

Cadrer l'agent plutôt que répéter les mêmes consignes à chaque demande. J'utilise Claude Code, un agent qui travaille directement dans le projet (fichiers, terminal, Git), avec deux outils.

Un fichier CLAUDE.md, lu automatiquement au début de chaque session : architecture, conventions, pièges connus. Quand une nouvelle règle est découverte, elle y est écrite une fois pour toutes.

CLAUDE.md — extraits### Extensionless URLs (spans 3 places)

Production URLs have no `.html` extension:
1. `.htaccess` rewrites `/foo` → `/foo.html` when the file exists.
2. `js/navigation-projets.js` and the inline script in `index.html`
   both detect production (hostname not `127.0.0.1`/`localhost`)
   and strip `.html` from every internal `<a href>` at runtime.
3. Locally, `.html` is kept so Live Server works.

Always write internal links **with** `.html` in source;
the stripping happens at runtime.

[…]

Content rule: only write what Riyad can explain in an interview.
Never invent a motivation, a technical choice or a difficulty —
ask him, or check the project's code/commits.

Un skill, c'est-à-dire une procédure réutilisable. Avec /pushage-portfolio, l'agent met à jour le CLAUDE.md si besoin, fait un commit d'une ligne et pousse : la documentation suit le code à chaque fois. Il me demande ensuite s'il doit mettre le site en ligne, et ne le fait qu'avec mon accord.

.claude/skills/pushage-portfolio/SKILL.md (adresse du serveur masquée)update claude MD si pas déjà fait. ensuite, tu feras un commit d'une seule ligne (sans description) et tu pusheras.
après le push, demande-moi si tu dois mettre à jour le site en ligne.
si je réponds oui, lance `ssh <serveur> 'cd /var/www/portfolio && git pull --ff-only'`,
puis vérifie que https://riyadayoub.fr répond en 200
et que https://riyadayoub.fr/.git/HEAD renvoie 404.

Mon workflow

1. Le cadre est posé : le CLAUDE.md décrit l'architecture et les pièges du projet.
2. Je décris le besoin, pas la solution : ce que je veux obtenir, et pourquoi.
3. L'agent analyse et propose un plan : rien n'est modifié tant que je ne l'ai pas validé.
4. Je relis le diff, fichier par fichier, et je fais corriger ce qui ne va pas.
5. Commit avec /pushage-portfolio, qui met aussi le CLAUDE.md à jour, puis mise en ligne si je la valide.

Mes choix

Un exemple concret : cette refonte

Un director engineering spécialisé en IA m'a fait un retour : mon site présentait des projets et des technologies, mais pas ma réflexion (le besoin, les choix, les limites). Voici comment j'ai travaillé avec l'agent pour corriger ça :

1. Je lui ai donné ce retour. Il a analysé les pages projet et proposé de les transformer en études de cas.
2. Avant d'écrire, il m'a posé des questions sur ma démarche plutôt que de l'inventer : mon rôle, mes choix, mes difficultés.
3. Pour ce que je ne pouvais pas détailler de mémoire, il est allé vérifier dans le code et l'historique Git des projets.
4. J'ai validé le plan, puis relu chaque modification avant de la publier.

Ces vérifications ont fait remonter des problèmes que je n'avais pas vus :

• un lien « Voir le code » qui menait à une page GitHub introuvable (404) ;
• une page qui annonçait une conception « mobile-first » alors que ce n'était pas le cas ;
• une démo présentée comme utilisant sa base de données en ligne, alors que son code était passé à un stockage en session ;
• un projet que je ne pouvais plus expliquer en détail : je l'ai retiré plutôt que de l'enjoliver.

La règle que j'en tire, désormais écrite dans le CLAUDE.md : je ne montre que ce que je sais expliquer.

Ce que je ne délègue pas

• Ce qui est vrai sur mes projets : l'agent rédige, mais les faits viennent de moi ou du code.
• La relecture : chaque diff est relu avant d'être commité.
• La décision de mettre en ligne : c'est moi qui décide quand lancer /pushage-portfolio.

Ce que j'améliorerais ensuite

• Une vérification automatique avant chaque push : valider le JSON-LD et tester les liens internes, pour ne plus dépendre uniquement d'une relecture humaine sur ces points.
• Sortir le script dupliqué des pages projet dans un fichier partagé : une règle de moins à retenir, pour moi comme pour l'agent.

Ce que j'ai appris

Outils