[Content] Guide: Inject context into Claude Code (UserPromptSubmit & SessionStart)

[steve-magne]

[Content] Guide: Inject context into Claude Code (UserPromptSubmit & SessionStart)

Priorité : 2. context est la 2ᵉ plus grosse catégorie (17 hooks) et n'a aucun guide dédié. Les requêtes « UserPromptSubmit hook » et « SessionStart hook » sont des long-tail réelles sans page d'atterrissage chez nous.

Objectif

Écrire un guide long-form expliquant comment injecter du contexte dans Claude Code via hooks : conventions de projet et date à chaque prompt (UserPromptSubmit), état du repo git au démarrage (SessionStart), et ré-injection après compaction. Capter l'intention « comment faire que l'agent connaisse X automatiquement » et pousser vers les hooks context.

Spec du guide

• slug : inject-context-claude-code-hooks
• title : Inject Context into Claude Code with Hooks
• metaTitle (≤60) : Inject Context into Claude Code with Hooks
• description (150-160, contient « Claude Code ») : injecter conventions, date et état git automatiquement via les hooks UserPromptSubmit et SessionStart.
• Mot-clé principal : « inject context claude code ». Requêtes long-tail : « UserPromptSubmit hook », « SessionStart hook », « claude code inject context », « claude code remember conventions », « claude code current date hook ».

Sections à couvrir (titres en question)

1. Pourquoi injecter du contexte par hook plutôt que de tout mettre dans CLAUDE.md ? (le hook injecte déterministe à chaque tour, au bon moment ; coût en tokens uniquement de ce qui est imprimé).
2. Comment fonctionne un hook UserPromptSubmit ? (ce qui est imprimé sur stdout devient du contexte ajouté au tour). Bloc de code : un hook qui préfixe les conventions/la date.
3. Comment injecter l'état git au démarrage avec SessionStart ? (branche, derniers commits, working tree). Mentionner le champ source (startup/resume/clear/compact).
4. Comment faire survivre le contexte à une compaction ? (ré-injection SessionStart source=compact).
5. Quels autres contextes valent l'injection ? (date/heure pour éviter les réponses périmées, AGENTS.md, contexte GitHub PR/CI).
6. Combien ça coûte en tokens ? (seul le texte imprimé compte ; garder l'injection concise).
7. Comment installer ces hooks en une commande ? (npx hookstack-cli@latest install).

Références internes

• related : what-are-claude-code-hooks, claude-code-hooks-vs-slash-commands, claude-code-settings-json.
• relatedHookSlugs (slugs réels) :
  user-prompt-inject-conventions, user-prompt-inject-datetime, session-start-load-git-context, session-start-reinject-after-compact, session-start-github-context, session-start-agents-md, user-prompt-log-session
• Lien entrant à créer : ajouter 'inject-context-claude-code-hooks' au related de claude-code-hooks-vs-slash-commands (et idéalement de what-are-claude-code-hooks).

---

📂 Comment réaliser ce guide (playbook partagé — à lire en premier)

Tous les guides long-form vivent dans un seul fichier : src/lib/guides.ts. Pour ajouter un guide, on ajoute un objet au tableau exporté guides. Tout le reste (page /guides/[slug], index /guides, sitemap.xml, /llms.txt, cross-links depuis les pages hook) est généré automatiquement en mappant sur ce tableau.

Avant d'écrire, lire src/lib/guides.ts en entier. Les 8 guides existants sont le gold standard : structure, profondeur, voix dev, et surtout formatage des blocs de code. Calquer exactement.

Forme Guide (interface en haut du fichier)

interface Guide {
  slug; title; metaTitle; description;
  datePublished; dateModified; readingMinutes;
  intro: string[];           // 2 paragraphes d'accroche sous le H1
  sections: { heading; body: (string | {list:string[]} | {code:string})[] }[];
  faq: { q; a }[];           // exactement 4
  related?: string[];        // slugs d'AUTRES guides (doivent exister)
  relatedHookSlugs: string[];// slugs de registry/registry.json (doivent exister)
  sources: { label; url }[]; // utiliser la constante DOCS du fichier
}

Règles dures (une erreur de syntaxe casse le build)

• Apostrophes : les strings de prose sont en quotes simples → pour une apostrophe dans la prose, utiliser le caractère courbe ’ (U+2019), jamais une apostrophe droite ' (elle casserait la string).
• Blocs de code : toujours un template literal backtick { code: \...` }. **Doubler chaque backslash** (\s, \/, \.) pour qu'il s'affiche en simple. Ne jamais mettre ${` dans le code.
• metaTitle ≤ 60 caractères. description entre 150 et 160 caractères, contenant le mot-clé principal. datePublished et dateModified = date du jour (format YYYY-MM-DD).
• Le code doit être du vrai code de hook Claude Code correct : fonction pure export function run(input, deps) + garde d'entrée if (process.argv[1] === fileURLToPath(import.meta.url)) { ... } ; décisions → stdout, logs → stderr ; référencer les scripts via node $CLAUDE_PROJECT_DIR/.claude/hooks/<name>.mjs ; toujours un timeout sur execSync ; filtrer par tool_name / extension avant tout travail lourd.
• Titres de section formulés en question quand c'est naturel (AEO / People-Also-Ask).

Câblage (presque tout automatique)

• /guides, sitemap.xml, /llms.txt, cross-links hook→guide : rien à toucher, ils mappent sur guides.
• Obligatoire : ajouter le nouveau slug au tableau related d'au moins un guide existant (lien interne entrant — c'est ce qui fait ranker la nouvelle page).
• relatedHookSlugs doivent être des slugs réels — vérifier dans registry/registry.json. Ne jamais inventer un slug (lien cassé sinon).
• (Optionnel) maillage supplémentaire : la section « Learn more » des pages hook (src/app/hook/[slug]/page.tsx) route event→guide en dur ; on peut y ajouter un lien vers ce guide pour les hooks du cluster concerné.

✅ Definition of Done

• Objet ajouté au tableau guides dans src/lib/guides.ts, conforme à Guide.
• Nouveau slug ajouté au related d'au moins un guide existant.
• pnpm typecheck passe.
• Tous les related résolvent vers des slugs de guides et tous les relatedHookSlugs vers des slugs du registre (script ci-dessous → OK).
• pnpm build réussit.
• GET /guides/<slug> renvoie 200, avec un <h1> et les JSON-LD Article + FAQ + Breadcrumb présents.
• Le guide apparaît dans /guides, /sitemap.xml et /llms.txt.
• Voix, longueur (~7-8 min) et densité comparables aux 8 guides existants ; 6-8 sections, 4 FAQ, 2 paragraphes d'intro.

Script de validation des références

node - <<'EOF'
const fs=require('fs');
const reg=JSON.parse(fs.readFileSync('registry/registry.json','utf8'));
const hookSlugs=new Set((reg.hooks||reg).map(h=>h.slug));
const src=fs.readFileSync('src/lib/guides.ts','utf8');
const g=new Set([...src.matchAll(/^\s{4}slug:\s*'([^']+)'/gm)].map(m=>m[1]));
let bad=0;
for(const m of src.matchAll(/relatedHookSlugs:\s*\[([^\]]*)\]/g))
  for(const s of [...m[1].matchAll(/'([^']+)'/g)].map(x=>x[1]))
    if(!hookSlugs.has(s)){console.log('BAD hook slug:',s);bad++}
for(const m of src.matchAll(/(?<!relatedHook)related:\s*\[([^\]]*)\]/g))
  for(const s of [...m[1].matchAll(/'([^']+)'/g)].map(x=>x[1]))
    if(!g.has(s)){console.log('BAD guide slug:',s);bad++}
console.log(bad?bad+' broken refs':'OK — all refs resolve');
EOF

Contexte SEO (pourquoi ce guide existe)

Ce guide fait partie d'un backlog de gap de contenu : le catalogue Hookstack a des clusters de hooks à forte intention de recherche qui n'ont aujourd'hui aucune page informationnelle qui les capte. Chaque guide cible des requêtes long-tail précises et draine vers un cluster de hooks distinct (maillage interne → conversion vers npx hookstack-cli@latest install). Objectif global : ranker top sur « Claude Code hooks » et dériver le trafic vers le catalogue. Les 8 guides actuels couvrent : définition, PreToolUse vs PostToolUse, hooks vs slash commands, troubleshooting, premier hook, settings.json, exemples, sécurité.