Les Compétences comme connaissance institutionnelle · Le guide pratique du SDLC natif à l'IA

Les Compétences sont la manière dont une organisation rend sa connaissance institutionnelle opérationnelle. Les instructions sont explicites, versionnées, appliquées largement, et mises à jour de manière centralisée lorsque la politique change. La règle de base : écrivez une Compétence pour la connaissance institutionnelle qui doit être appliquée de manière cohérente ; n'écrivez pas de Compétence pour les composants qui appartiennent à CLAUDE.md ou à un prompt.

Pour commencer

Prérequis : Aucun requis. Avoir un CLAUDE.md aide, car cela conserve la connaissance de travail de l'agent dans le dépôt, mais une Compétence n'en dépend pas.
Infrastructure : Une politique avec un propriétaire nommé et une source de vérité écrite.

Comment l'exécuter

Choisissez un élément de connaissance qui est appliqué de manière incohérente aujourd'hui. Cela peut être une norme de sécurité, une convention de conception d'API, ou une règle de marque.
Écrivez-le sous forme de Compétence, un dossier contenant un SKILL.md dont le frontmatter indique quand elle se déclenche et dont le corps indique quoi faire. Un ingénieur l'écrit à partir de la source de vérité du propriétaire de la politique, en utilisant Claude pour l'aider.
Placez la Compétence dans le dépôt à .claude/skills/<name>/ afin qu'elle soit livrée avec le code, ou distribuez-la à l'échelle de l'organisation via un plugin.
Testez que la Compétence se déclenche. Demandez à Claude d'effectuer la tâche concernée de différentes manières et confirmez que la Compétence se charge chaque fois.
Lorsque la politique change, modifiez la Compétence et faites valider le changement par le propriétaire de la politique.
Les ingénieurs récupèrent automatiquement la nouvelle version lors de leur prochaine session.

À quoi cela ressemble

.claude/skills/secure-api-review/SKILL.md :

markdown

---
name: secure-api-review
description: Apply the API security standard. Use whenever creating or
  modifying an external-facing endpoint, reviewing API code, or
  generating an OpenAPI spec.
---
# Secure API review
When you create or change an API endpoint:
1. Authentication: every endpoint requires the gateway JWT;
   no anonymous routes outside /health.
2. Input validation: validate request bodies against the OpenAPI
   schema and reject unknown fields.
3. Audit: every state-changing endpoint emits an audit event with
   actor, action, entity and timestamp.
4. Data classification: fields tagged pii in the schema must never
   appear in logs or error messages.
Run scripts/check-endpoints.sh and include its output in your summary.

Considérations de gouvernance

Une Compétence est un contrôle, bien que de nature consultative. Elle rend Claude susceptible d'appliquer la politique pendant que le code est écrit, mais rien n'oblige une session à s'y conformer. Une politique qui doit toujours être respectée nécessite quelque chose de déterministe derrière la Compétence, comme un hook qui bloque l'action ou une passe de revue qui revérifie la politique au niveau de la PR. La Compétence rend les violations rares et le hook les rend presque impossibles. Le hook détecte une violation au moment de la modification, et la même vérification sur la pull request détecte tout ce qui a atteint la branche d'une autre manière. Les invocations de Compétences sont enregistrées dans les traces de session, et le propriétaire de la politique examine les modifications de Compétences comme du code.

Comment le mesurer

Indicateur avancé : Le temps écoulé entre l'approbation d'un changement de politique par le propriétaire de la politique et la fusion de la Compétence mise à jour, mesuré à partir de la PR sur le dossier de la Compétence.
Indicateur retardé : Les constats de revue de PR qui citent la politique, qui devraient tendre vers zéro une fois que la Compétence applique la politique pendant que le code est écrit. Lorsque les constats ne tendent pas vers zéro, soit la Compétence ne se déclenche pas, soit son texte s'est éloigné de la politique officielle.

Les hooks comme garde-fous au moment de la construction

Une Compétence est un contrôle consultatif, tandis qu'un hook est la couche déterministe qui se trouve derrière. La plupart des actions de Claude sont des modifications de fichiers et des commandes shell pendant l'implémentation, c'est pourquoi la phase de construction est celle où les hooks finissent par se déclencher le plus souvent.

Les hooks de phase de construction peuvent :

Bloquer les modifications sur des chemins protégés tels que des classes générées ou un package figé
Exécuter le formateur et le linter après les modifications de fichiers afin que la dérive ne s'accumule jamais
Empêcher les identifiants de se retrouver dans le diff
Soutenir toute Compétence dont la politique doit être respectée sans exception

Un hook s'exécute à chaque action qui lui correspond, donc les hooks de phase de construction doivent être rapides et limités au fichier qui a changé. Les vérifications plus lourdes, comme la suite de tests complète, ont leur place au niveau du commit ou de la PR.

Voici le hook derrière la règle 4 de la Compétence secure-api-review présentée plus haut sur cette page. Le dépôt est celui d'un assureur, et ses fichiers de points de terminaison se trouvent dans claims-api/routes/. Après chaque modification de l'un de ces fichiers, le hook exécute scripts/check-endpoints.sh, le script à la racine du dépôt que la Compétence nomme déjà. Ce script échoue lorsqu'un champ étiqueté pii dans le schéma OpenAPI atteint un appel de journalisation ou une erreur levée.

Le hook est enregistré dans .claude/settings.json. La liste args vide fait que Claude Code exécute le script directement plutôt que via un shell :

json

{
  "hooks": {
    "PostToolUse": [
      {
        "matcher": "Edit|Write",
        "hooks": [
          { "type": "command",
            "command": "${CLAUDE_PROJECT_DIR}/.claude/hooks/api-policy.sh",
            "args": [] }
        ]
      }
    ]
  }
}

Le script du hook, .claude/hooks/api-policy.sh :

bash

#!/bin/bash
# Étaye la règle 4 de la Compétence secure-api-review avec le même script que celui exécuté par la Compétence.
file=$(jq -r '.tool_input.file_path')
case "$file" in
  "$CLAUDE_PROJECT_DIR"/claims-api/routes/*.py) ;;
  *) exit 0 ;;                                   # not an endpoint
esac
cd "$CLAUDE_PROJECT_DIR" || exit 2
if ! found=$(scripts/check-endpoints.sh "${file#"$CLAUDE_PROJECT_DIR"/}"); then
  echo "secure-api-review rule 4: a pii field reaches a log or an error message." >&2
  echo "$found" >&2
  exit 2
fi

Un hook qui s'exécute après une modification ne peut pas l'annuler, donc le code de sortie 2 place le message du script devant Claude, qui peut alors corriger la ligne. Après une modification qui journalise le nom d'un client, voici le message que Claude voit de la part du script :

text

secure-api-review rule 4: a pii field reaches a log or an error message.
claims-api/routes/status.py:10: policy_holder_name

Un hook Edit|Write ne se déclenche pas lorsqu'une commande shell réécrit le fichier. Pour cette raison, le même script s'exécute également comme vérification obligatoire sur chaque pull request :

yaml

name: API policy
on: pull_request
jobs:
  check-endpoints:          # a required check in branch protection
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - run: scripts/check-endpoints.sh claims-api/routes/*.py

Un hook qui demande l'approbation d'un humain a sa place parmi les portes de validation de l'Étape 5 : Déploiement, car une invite d'approbation pendant la construction replace une personne sur le chemin critique de toutes les sessions s'exécutant en parallèle.

Pour commencer

Comment l'exécuter

À quoi cela ressemble

Considérations de gouvernance

Comment le mesurer