gilles/mesh
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
Files
main
mesh/docs/agent_claude_codex_prompt.md
Gilles Soulier 1d177e96a6 first
2026-01-05 13:20:54 +01:00

7.9 KiB
Raw Permalink Blame History

Livrables — Agent Rust

Ce document contient :

  1. le fichier agent/CLAUDE.md
  2. un prompt Codex initial pour générer le squelette compilable de agent/

1) agent/CLAUDE.md

# CLAUDE.md — Mesh Agent (Rust)

## Portée
Ce fichier s’applique **uniquement** au code situé dans `agent/`.
Il complète le `CLAUDE.md` racine (vision/architecture). En cas de conflit, le `CLAUDE.md` racine prime.

---

## Objectifs de l’agent
- Multi-OS (Linux, Windows, macOS)
- Faible charge serveur : le serveur ne transporte pas de flux lourds
- Data-plane performant :
  - **QUIC (TLS 1.3)** pour fichiers/dossiers/terminal
  - fallback HTTP temporaire (exceptionnel)
- Terminal share robuste via PTY (preview par défaut)
- Notifications directes Gotify

---

## Rappels d’architecture
- Control plane : Mesh Server (REST + WS)
  - auth, rooms, ACL
  - capability tokens TTL court
  - orchestration des sessions P2P
- Data plane : agent ↔ agent
  - QUIC via `quinn`
  - handshake applicatif obligatoire `P2P_HELLO`

---

## Règles de sécurité (non négociables)
- Aucun contournement des capability tokens.
- Terminal : **preview-only** par défaut.
- Input distant uniquement si :
  1) serveur a accordé `terminal:control`
  2) l’agent propriétaire confirme/maintient le contrôleur actif
- Ne jamais exfiltrer : clés SSH, mots de passe, variables secrètes.
- Logs sans contenu sensible (pas de contenu de terminal en clair dans les logs).

---

## Contraintes de code Rust
- Rust stable
- Async : `tokio`
- HTTP : `reqwest`
- WebSocket : `tokio-tungstenite`
- QUIC : `quinn`
- Config : `serde` + `toml` (ou yaml)
- Logs : `tracing`

Qualité :
- Interdiction de `unwrap()` / `expect()` en code final
- Erreurs explicites (`Result`) + `thiserror` recommandé
- Tests stubs acceptés, mais structure prête

---

## Structure obligatoire du dossier
Ne pas renommer arbitrairement.

agent/ Cargo.toml src/ main.rs config/ mesh/ p2p/ quic/ share/ terminal/ notifications/ os/ tests/


---

## Développement : ordre recommandé
1) **Squelette compilable** + config + logs
2) Client Mesh (REST + WS)
3) Notifications Gotify (agent → gotify)
4) Terminal preview via PTY (local) + stream (transport abstrait)
5) QUIC : endpoint + handshake `P2P_HELLO`
6) Terminal preview sur QUIC
7) File transfer sur QUIC
8) Folder zip sur QUIC
9) Terminal take-control (arbitrage via serveur)

---

## Consigne de suivi d’avancement
À chaque jalon significatif **ou** vers ~80 % d’une session de travail, produire :

ÉTAT D’AVANCEMENT – Mesh Agent ✔ Terminé :

  • ... ◻ En cours :
  • ... ✖ À faire :
  • ... Risques / points bloquants :
  • ... Prochaine action recommandée :
  • ...

---

## Gestion du contexte (pour Claude)
- Utiliser `/clear` entre tâches distinctes.
- Pour revue sécurité/perf : utiliser un sous-agent.

Le contexte durable doit rester dans :
- `CLAUDE.md` (racine)
- ce `agent/CLAUDE.md`
- `docs/`.

2) Prompt Codex initial — squelette compilable agent/

# Codex Prompt — Mesh Agent (Rust) : Skeleton compilable (étape 1)

Contexte
- Projet Mesh : server Python (control plane), client web, agent Rust (data plane QUIC).
- Références : `CLAUDE.md` racine + `agent.md` + `agent/CLAUDE.md`.

Objectif
- Générer un squelette **compilable** du dossier `agent/` (Rust stable) avec la structure imposée.
- Aucun code “tout-en-un”. Travail en modules minimalistes.

Règles
- Rust stable, tokio, tracing.
- Pas de unwrap/expect dans le code final.
- Erreurs via Result + thiserror.
- Config via serde + toml.

Livrables attendus
1) `agent/Cargo.toml` avec dépendances minimales : tokio, tracing, tracing-subscriber, serde, toml, reqwest, tokio-tungstenite, thiserror.
2) Arborescence `src/` avec modules vides mais raccordés :
   - config/
   - mesh/ (rest.rs, ws.rs, types.rs)
   - notifications/ (gotify.rs, router.rs)
   - terminal/ (mod.rs, stream.rs)
   - p2p/quic/ (endpoint.rs, protocol.rs)
   - share/ (file_send.rs, folder_zip.rs)
   - os/ (autostart.rs, tray.rs)
3) `src/main.rs` :
   - charge config
   - init tracing
   - démarre runtime tokio
   - affiche un log “agent started”
4) `agent/README.md` : commandes build/run
5) `agent/.env.example` (si utile) + `config.example.toml`

Ne pas implémenter la logique QUIC/WS complète maintenant : uniquement les stubs d’API et la compilation.

Stop
- Quand tout compile (`cargo build`), terminer et fournir un court résumé des fichiers créés.
- Si tu estimes être à ~80 % de l’objectif, produire un état d’avancement au format imposé avant d’aller plus loin.

Traçabilité des modifications de code (obligatoire)

Chaque agent (Claude principal, sous-agent, Codex, ou autre) qui crée ou modifie du code doit explicitement l’indiquer dans les fichiers concernés.

Règles de traçabilité

  • Tout fichier créé doit contenir un commentaire en début de fichier indiquant :

    • l’agent auteur,
    • la date,
    • l’objectif de la création.

  • Toute modification d’un fichier existant doit être signalée :

    • soit par un commentaire en début de fichier (si modification importante),
    • soit par un commentaire en fin de ligne ou à proximité immédiate du changement (si modification ponctuelle).

Format imposé des commentaires

Création de fichier

// Created by: <agent_name>
// Date: YYYY-MM-DD
// Purpose: <short description>

Modification de fichier

// Modified by: <agent_name> — YYYY-MM-DD — <reason>

Le format exact peut être adapté au langage (Rust, Python, TypeScript…), mais les informations doivent toujours être présentes.

Agents concernés

Cette règle s’applique à :

  • Claude (agent principal),
  • tous les sous-agents,
  • Codex ou tout autre générateur de code,
  • toute automatisation produisant ou modifiant des fichiers.

Objectif

  • garantir une traçabilité claire des décisions et des changements,
  • faciliter les revues (sécurité, performance, architecture),
  • permettre de comprendre rapidement qui a fait quoi et pourquoi.

Cette consigne est obligatoire et non optionnelle pour le projet Mesh.

Traçabilité des modifications de code (obligatoire)

Toute création ou modification de code réalisée pour l’agent Mesh doit indiquer explicitement l’agent auteur.

Règles

  • Création de fichier : commentaire en début de fichier.
  • Modification importante : commentaire en début de fichier.
  • Modification ponctuelle : commentaire en fin de ligne ou à proximité immédiate.

Formats imposés (à adapter au langage)

Création

// Created by: <agent_name>
// Date: YYYY-MM-DD
// Purpose: <short description>

Modification

// Modified by: <agent_name> — YYYY-MM-DD — <reason>

Agents concernés

  • Claude (principal)
  • Sous-agents
  • Codex / générateurs de code

Objectif

Garantir une traçabilité claire (qui / quand / pourquoi) pour les revues sécurité, performance et maintenance.

Cette règle est non optionnelle pour l’agent Mesh.

Traçabilité des modifications de code (obligatoire — Agent)

Cette règle s’applique **spécifiquement au dossier **`` et est prioritaire pour Codex.

Exigences

  • Chaque agent (Claude, sous-agent, Codex) doit signer ses créations et modifications.
  • Aucune PR ou génération de code n’est valide sans cette signature.

Formats

Création de fichier

// Created by: <agent_name>
// Date: YYYY-MM-DD
// Purpose: <short description>

Modification

// Modified by: <agent_name> — YYYY-MM-DD — <reason>

Placement

  • Début de fichier : création ou refactor majeur.
  • Fin de ligne / bloc : correction ponctuelle.

Objectif

  • Auditabilité
  • Revue facilitée
  • Historique lisible sans dépendre des commits

Cette consigne est obligatoire pour toute génération de code dans agent/.

Reference in New Issue View Git Blame Copy Permalink