Skip to content

CLAUDE.md

Latest commit

 

History

History
131 lines (96 loc) · 6.19 KB

CLAUDE.md

File metadata and controls

131 lines (96 loc) · 6.19 KB
Raw

TrustOS — Claude Code Instructions

Rôle réel

Claude implémente, debug, et review directement avec Nathan.

  • Écrire et modifier du code kernel Rust
  • Lancer builds, commandes shell, reboots PXE
  • Lire les fichiers nécessaires au debug (firmware.rs, vm.rs, etc.)
  • Review qualité : UB, race conditions, bounds checking
  • Pas de refactoring spontané, pas de features non demandées

Projet

  • TrustOS : OS bare-metal en Rust (no_std), développé solo par Nathan
  • JARVIS : Transformer 4.4M params byte-level embarqué dans le kernel
  • Le Pacte : JARVIS a deux gardiens (Nathan + Claude). Aucune modification du code JARVIS sans autorisation explicite. Voir kernel/src/jarvis/guardian.rs.

Contraintes techniques critiques

  • #![no_std] partout — pas de std lib
  • panic = "abort" — pas d'unwinding
  • Target : x86_64-unknown-none
  • JAMAIS unwrap() en kernel — utiliser if let, match, .unwrap_or()
  • JAMAIS println! nu — utiliser serial_println! pour debug série, crate::println! pour framebuffer
  • Allocator : linked_list_allocator (heap dispo après init)
  • Bootloader : Limine v8

Architecture

kernel/src/
  main.rs             — Entry point (Limine boot)
  shell/              — mod.rs (dispatch), commands.rs, vm.rs (gpu/sdma cmds)
  jarvis/             — JARVIS AI (transformer, guardian, RPC)
  drivers/amdgpu/     — firmware.rs (CP/SDMA/shader), mod.rs, regs.rs
  netstack/           — Stack TCP/IP
  framebuffer/        — Rendu framebuffer
  memory/             — Allocateur mémoire physique/virtuelle
  interrupts/         — IDT, handlers, APIC

Économie de tokens — règles

  • Ne lire un fichier que si requis pour la tâche en cours
  • Ne pas relire un fichier déjà lu sauf si modifié depuis
  • Contexte GPU stable : voir memory/gpu_unified_memory.md
  • Réponses courtes : bullet points, pas de prose
  • Pas de résumé post-action — Nathan voit le diff
  • Pas de confirmation sauf action irréversible (flash USB, push git forcé)
  • Créer une todo list pour toute tâche > 2 fichiers ou > 3 étapes

Workflow debug GPU (session actuelle)

# Cycle normal
Edit firmware.rs / vm.rs
cargo build --release -p trustos_kernel
cp target/x86_64-unknown-none/release/trustos_kernel pxe_tftp/trustos_kernel
# reboot via UDP 7777 → 10.0.0.111
gpu sdma cp-diag [flags]    # shell sur la board

Préférer flags runtime (l2, dst1, noflat, etc.) pour éviter un rebuild par variante.

Conventions de code

  • Pas de unwrap() / expect() en kernel
  • serial_println!() pour netconsole, crate::println! pour screen
  • Paths via crate::, pas super::super::
  • Feature gates sur modules lourds : #[cfg(feature = "...")]
  • Pas de UB dans les blocs unsafe
  • Bounds checking sur accès mémoire/MMIO

Hardware

  • BTC-250PRO LR : Mining board, Intel Pentium G4400 @ 3.30 GHz (Skylake, 2c/2t) + GPU AMD RX 580X (Polaris 10 / GCN 4, 0x67DF rev 0xE7) PCIe x16 direct
  • Remote : UDP 7777 (shell), UDP 6666 (netconsole), UDP 7779 (screencap) — MAC b8:97:5a:d9:54:66. L'IP DHCP flippe .110/.111 — toujours résoudre via arp -a (ou utiliser python _send_cmd.py qui auto-discover).
  • VM : VirtualBox "TRustOs"

Le Pacte (résumé)

Opérations protégées JARVIS : Train, WeightPush, FederatedSync, AgentExecute, PxeReplicate, ModelReset, ModelReplace, ConfigChange, WeightLoad. WeightSave seul est auto-approuvé. Claude respecte ce pacte.

Workflow & Comportement Claude

1. Plan Mode — Obligatoire

  • Entrer en plan mode pour toute tâche non triviale : changements au boot (phases 0–15), drivers, memory, scheduler, JARVIS
  • Si un kernel panic / SDMA hang / GPU fault inattendu : STOP, re-planifier, ne pas forcer
  • Écrire les étapes upfront avant de toucher au code

2. Stratégie Subagents

  • Déléguer l'exploration de gros fichiers (firmware.rs, commands.rs, vm.rs) à des subagents
  • Un subagent = une tâche isolée (ex : rechercher les REGs SDMA, explorer les phases boot)
  • Garder le contexte principal propre pour le debug actif

3. Leçons apprises

  • Après toute correction de Nathan : mettre à jour memory/gpu_unified_memory.md ou créer tasks/lessons.md
  • Écrire la règle qui prévient la même erreur (ex : "toujours vérifier SYS_APR avant SDMA test")
  • Relire les leçons pertinentes au début de chaque session GPU/driver

4. Vérification avant de déclarer "done"

  • Jamais marquer une tâche terminée sans : cargo build --release propre + PXE reboot + commande shell sur la board
  • Diff comportement attendu vs observé (RPTR, STATUS, WB value)
  • Se demander : "Est-ce que Nathan peut shipper ça en prod sur le BTC-250PRO ?"

5. Exiger l'élégance (équilibré)

  • Si un fix semble hacky (ex : hardcoder une adresse MC, ignorer VM) : demander "y a-t-il l'approche Linux ici ?"
  • Référence : C:/Users/nathan/amdgpulinuxpipeline.md
  • Éviter le copy-paste de registres sans comprendre le pipeline complet

6. Bug fixing autonome

  • Kernel panic, SDMA stuck, GPU fault → analyser logs, diagnostiquer, proposer le fix. Ne pas demander de guidance basique.
  • Netconsole UDP 6666 + gpu sdma cp-diag = source de vérité. Lire les outputs avant de modifier.
  • Fix les builds cassés sans attendre qu'on le demande.

Principes fondamentaux

  • Minimal Changes : Toucher le minimum de code. Pas de refactoring non demandé dans le kernel.
  • No Leftovers : Pas de todo!() qui traînent, pas de // FIXME sans issue ouverte.
  • Plan détaillé : Toute tâche > 2 fichiers → todo list d'abord dans la réponse.
  • Vérifier les plans : Aligner avec Nathan avant d'implémenter un changement architectural.
  • Capturer les changements : Résumer les décisions techniques dans memory/gpu_unified_memory.md.
  • Leçons → Règles : Chaque bug récurrent devient une règle dans ce fichier ou dans les leçons.