# CLAUDE.md — Set-OPS

## Instruction principale

Claude Code doit lire et respecter `AGENTS.md` avant toute modification.

`AGENTS.md` est la source d’autorité principale du dépôt.

En cas de contradiction entre `CLAUDE.md` et `AGENTS.md`, suivre `AGENTS.md`.

---

## Rôle du dépôt

`Set-OPS` est le moteur Ansible global d’exploitation d’écosystèmes numériques souverains.

Le template Debian 13 Proxmox est seulement un sous-ensemble du dépôt. Ne pas restructurer tout le dépôt autour de ce seul chantier.

---

## Règle d’or IA

Un seul agent IA travaille dans ce dépôt à la fois.

- Soit Codex.
- Soit Claude Code.
- Jamais les deux simultanément.

---

## Avant toute modification

Exécuter ou demander l’équivalent de :

```bash
git status --short
find . -maxdepth 3 -type f | sort
```

Lire au minimum :

```text
AGENTS.md
README.md
CHANGELOG.md
ansible.cfg
```

Lire aussi les fichiers directement concernés avant de les modifier.

Ne pas remplacer massivement l’arborescence sans demande explicite.

Préférer un correctif minimal ciblé.

---

## Validation Ansible obligatoire

Avant de dire qu’un changement est prêt, exécuter au minimum le `--syntax-check` du playbook touché.

Pour le template Debian 13 Proxmox :

```bash
ansible-playbook -i instance/inventories/lab/hosts.yml playbooks/modeles_vm/debian13_proxmox_preparer.yml --syntax-check
```

Si `ansible-lint` est disponible :

```bash
ansible-lint
```

Si `ansible-lint` n’est pas disponible, le signaler clairement.

Ne jamais déclarer un playbook prêt si la validation échoue.

---

## Handlers Ansible

Chaque rôle qui utilise `notify` doit contenir son handler dans le rôle lui-même.

Exemple :

```text
roles/ssh_baseline/tasks/main.yml
roles/ssh_baseline/handlers/main.yml
```

Commandes utiles :

```bash
find roles -path '*/tasks/*.yml' -exec grep -H "notify:" {} \;
find roles -path '*/handlers/main.yml' -print
```

Avant de livrer un rôle, vérifier que chaque handler référencé existe réellement.

---

## Actions destructives

Toute action destructrice ou risquée doit exiger une confirmation explicite.

Exemple :

```yaml
confirm_destructive_action: true
```

Sont considérées risquées :

- modification bloquante de SSH ;
- activation ou modification d’un pare-feu ;
- suppression d’utilisateurs ;
- suppression de paquets critiques ;
- formatage disque ;
- modification de partitions ;
- redémarrage massif ;
- purge de données ;
- changement réseau pouvant couper l’accès ;
- modification d’un hyperviseur Proxmox ;
- opération sur stockage, iSCSI, ZFS ou Ceph.

Sans confirmation explicite, refuser l’exécution.

---

## Template Debian 13 Proxmox

Le template doit rester un socle commun.

Il peut contenir :

- Debian minimal ;
- SSH ;
- sudo ;
- compte technique `ansible` ;
- sudo NOPASSWD pour `ansible` lorsque requis ;
- `qemu-guest-agent` ;
- `cloud-init` ;
- `cloud-guest-utils` ;
- chrony ;
- outils de diagnostic ;
- hardening raisonnable ;
- AppArmor ;
- auditd ;
- fail2ban SSH ;
- unattended-upgrades ;
- journald ;
- sysctl de sécurité ;
- nftables installé et préparé, mais non activé par défaut.

Il ne doit pas contenir par défaut :

- NGINX ;
- PostgreSQL ;
- MariaDB ;
- Docker ;
- Podman ;
- Redis ;
- GitLab ;
- Nextcloud ;
- monitoring complet ;
- données propres à un clone ;
- secrets ;
- clés privées.

---

## SSH

Pendant la construction du template :

```text
PasswordAuthentication yes
PermitRootLogin no
PubkeyAuthentication yes
```

État cible après validation des clés SSH :

```text
PasswordAuthentication no
PermitRootLogin no
PubkeyAuthentication yes
```

Ne jamais désactiver l’authentification par mot de passe avant d’avoir confirmé que l’accès par clé fonctionne.

Toute modification SSH doit valider la configuration avant rechargement :

```bash
sshd -t
```

---

## Pare-feu

Ne pas activer un pare-feu générique dans le template sans confirmation explicite.

`nftables` peut être installé et préparé, mais rester désactivé dans le template.

L’activation doit être faite sur un clone ou un serveur final, avec des règles adaptées au rôle du serveur.

---

## Cloud-init

Cloud-init donne l’identité initiale d’un clone :

- hostname ;
- utilisateur initial ;
- clé SSH ;
- IP ;
- passerelle ;
- DNS ;
- agrandissement de la partition racine.

Cloud-init ne remplace pas Ansible.

Séparation attendue :

```text
Proxmox + cloud-init : identité initiale de la VM
Set-OPS + Ansible    : configuration réelle du serveur
```

---

## Après modification

Répondre avec :

1. fichiers créés ;
2. fichiers modifiés ;
3. commandes de validation exécutées ;
4. résultat des validations ;
5. tests non exécutés ;
6. limites connues ;
7. entrée `CHANGELOG.md` ajoutée ou raison de l’absence d’entrée.

Ne pas dire que c’est prêt si ce n’est pas validé.