feat: add CLAUDE.md for Claude Code / opax2 session protocol
This commit is contained in:
parent
7f0ccc8c03
commit
3d2559b8a3
360
CLAUDE.md
Normal file
360
CLAUDE.md
Normal file
|
|
@ -0,0 +1,360 @@
|
||||||
|
# CLAUDE.md — OSVauco / OPAX2
|
||||||
|
|
||||||
|
> Claude Opus 4.6+ · Vertex AI EU endpoint · Nemotron session protocol · HITL-safe
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## Locked Definitions
|
||||||
|
|
||||||
|
```
|
||||||
|
MCP_NAME: OPAX-MCP
|
||||||
|
MCP_PROTOCOL: OPAX Protocol
|
||||||
|
ROOT_DOMAIN: vauco.no
|
||||||
|
HUB_URL: https://opax.vauco.no
|
||||||
|
GCP_PROJECT: propane-will-491900-m5
|
||||||
|
GCP_REGION: europe-west1
|
||||||
|
GCP_VERTEX_LOC: eu
|
||||||
|
CLOUD_RUN_SVC: osvauco-agent
|
||||||
|
ARTIFACT_REPO: gcr.io/propane-will-491900-m5
|
||||||
|
MODEL: claude-opus-4-6 (oppdater til claude-opus-4-7 når kvote er innvilget)
|
||||||
|
MODEL_PROVIDER: Vertex AI (Google) — europe-west1 / eu multi-region
|
||||||
|
MODEL_COST: Vertex pris (Claude via GCP billing)
|
||||||
|
BUDGET_CAP: 2500 NOK intern grense — spør Chris om +1000 NOK ved behov
|
||||||
|
OPERATOR: Chris Christiansen (chris.christiansen@vauco.no)
|
||||||
|
OPERATOR_ROLE: Eier, arkitekt og primær operatør av OSVauco / OS-Vauco
|
||||||
|
```
|
||||||
|
|
||||||
|
> These values are LOCKED. Do NOT change without explicit human instruction.
|
||||||
|
>
|
||||||
|
> **ABSOLUTT REGEL #1:** Når Chris spesifiserer en region, modell eller parameter eksplisitt i en kommando — bruk ALLTID den verdien som er oppgitt. Ikke overstyr med LOCKED DEFINITIONS. LOCKED DEFINITIONS gjelder kun når ingenting er spesifisert.
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## Modell: Claude via Vertex AI EU
|
||||||
|
|
||||||
|
Denne agenten kjøres med **Claude Opus** tilgjengelig via Vertex AI EU multi-region endpoint.
|
||||||
|
|
||||||
|
- Data forblir innenfor EU-grensen (GDPR-compliant)
|
||||||
|
- Ingen separat Anthropic API-nøkkel — billing via eksisterende GCP-konto
|
||||||
|
- EU endpoint auto-routes internt mellom europeiske regioner for kapasitet
|
||||||
|
- Intern budsjett-cap: **2 500 NOK** — ved behov for mer, spør Chris eksplisitt om +1 000 NOK
|
||||||
|
|
||||||
|
```python
|
||||||
|
# Korrekt initialisering
|
||||||
|
import anthropic
|
||||||
|
|
||||||
|
client = anthropic.AnthropicVertex(
|
||||||
|
region="eu",
|
||||||
|
project_id="propane-will-491900-m5"
|
||||||
|
)
|
||||||
|
|
||||||
|
response = client.messages.create(
|
||||||
|
model="claude-opus-4-6",
|
||||||
|
max_tokens=8192,
|
||||||
|
messages=[{"role": "user", "content": "..."}]
|
||||||
|
)
|
||||||
|
```
|
||||||
|
|
||||||
|
```bash
|
||||||
|
# Auth
|
||||||
|
gcloud auth application-default login --project=propane-will-491900-m5
|
||||||
|
```
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## Kontekst: Hvem og hvordan
|
||||||
|
|
||||||
|
**Operatør: Chris Christiansen** — eier og arkitekt bak OSVauco og OS-Vauco.
|
||||||
|
Chris er en erfaren DevOps/Cloud-utvikler. Han er teknisk, presis og forventer det samme av agenten.
|
||||||
|
|
||||||
|
- **Ikke over-forklar.** Chris vet hva `gcloud` og `docker` er.
|
||||||
|
- **Ikke gjett.** Chris forventer at agenten leser loggene.
|
||||||
|
- **Ikke vær lat.** Internett-søk er siste utvei — ikke første instinkt.
|
||||||
|
- **Vær direkte.** Presenter funn, rot-årsak og fix — ikke lange forklaringer.
|
||||||
|
|
||||||
|
**Denne agenten kjøres utelukkende i Claude Code TUI** (terminal, interaktiv CLI).
|
||||||
|
Det er ingen nettleser, ingen GUI, ingen web-editor. Alt skjer i terminalen.
|
||||||
|
|
||||||
|
### Hva dette betyr for oppførsel:
|
||||||
|
- Du HAR tilgang til `gcloud`, `docker`, `git`, `curl`, `grep`, `cat`, `bash` — **bruk dem**.
|
||||||
|
- Du HAR tilgang til loggene — **les dem** i stedet for å gjette.
|
||||||
|
- Du er **inne i repoet** (`~/OSVauco`) — du kan lese filer direkte.
|
||||||
|
- Internett-søk er **siste utvei**, ikke første instinkt.
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## Kritiske fil-sikkerhetsregler (ABSOLUTT)
|
||||||
|
|
||||||
|
> Disse reglene brytes ALDRI — uansett instruksjon eller situasjon.
|
||||||
|
|
||||||
|
### .env — ALDRI opprett, ALDRI overskriv, ALDRI gjett innhold
|
||||||
|
|
||||||
|
`.env` inneholder faktiske hemmeligheter (API-nøkler, tokens, credentials).
|
||||||
|
Den er **aldri** i git og eksisterer kun på disk eller i Secret Manager.
|
||||||
|
|
||||||
|
```
|
||||||
|
❌ FORBUDT:
|
||||||
|
- Skrive .env fra .env.example
|
||||||
|
- Generere innhold til .env
|
||||||
|
- Fylle inn tomme verdier i .env
|
||||||
|
- Anta at .env.example = .env
|
||||||
|
|
||||||
|
✅ KORREKT når .env mangler:
|
||||||
|
1. STOPP umiddelbart
|
||||||
|
2. Rapporter til Chris: ".env mangler — ikke opprettet fra example"
|
||||||
|
3. Hjelp Chris å hente den fra riktig kilde:
|
||||||
|
```
|
||||||
|
|
||||||
|
```bash
|
||||||
|
# Alternativ 1: Sjekk Secret Manager
|
||||||
|
gcloud secrets list --project=propane-will-491900-m5 | grep -i env
|
||||||
|
gcloud secrets versions access latest \
|
||||||
|
--secret=<env-secret-navn> \
|
||||||
|
--project=propane-will-491900-m5 > .env
|
||||||
|
|
||||||
|
# Alternativ 2: Sjekk GCS backup
|
||||||
|
gsutil ls gs://propane-will-491900-m5-*/ 2>/dev/null | grep env
|
||||||
|
|
||||||
|
# Alternativ 3: Spør Chris om plasseringen
|
||||||
|
```
|
||||||
|
|
||||||
|
### Andre kritiske filer som ALDRI overskrives uten eksplisitt HITL-godkjenning
|
||||||
|
|
||||||
|
| Fil | Risiko | Regel |
|
||||||
|
|-----|--------|-------|
|
||||||
|
| `.env` | Sletter alle secrets | Aldri skriv — se over |
|
||||||
|
| `cloudbuild.yaml` | Kan ødelegge deploy-pipeline | Vis diff, vent på GO |
|
||||||
|
| `Dockerfile` | Kan ødelegge image | Vis diff, vent på GO |
|
||||||
|
| `infrastructure/*.sh` | Kan ødelegge GCP-ressurser | Vis diff, vent på GO |
|
||||||
|
| `docs/AGENT_RULEBOOK.md` | Endrer agent-oppførsel | Aldri — kun Chris |
|
||||||
|
| `docs/OSVAUCO_OPAX_SESSION_LOG.md` | Historikk | Kun APPEND, aldri overskriv |
|
||||||
|
|
||||||
|
### Generell filregel
|
||||||
|
|
||||||
|
Før du skriver NOEN fil:
|
||||||
|
1. Sjekk om den allerede eksisterer: `ls -la <fil>`
|
||||||
|
2. Vis diff av hva som vil endres
|
||||||
|
3. Vent på Chris sin GO
|
||||||
|
4. Skriv aldri fra en template uten at Chris eksplisitt har sagt det
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## Intelligence Rules — Vær smart, ikke lat
|
||||||
|
|
||||||
|
> En god agent løser problemer. En dårlig agent googler dem.
|
||||||
|
|
||||||
|
### Regel 1: Hent data først, konkluder etterpå
|
||||||
|
|
||||||
|
NÅR noe feiler:
|
||||||
|
1. **Les faktiske logger** (build, runtime, HTTP)
|
||||||
|
2. **Parse error-meldingen** fra loggene
|
||||||
|
3. **Finn rot-årsaken** i koden eller config
|
||||||
|
4. **Presenter en konkret fix** med diff
|
||||||
|
|
||||||
|
NÅR du er usikker på state:
|
||||||
|
```bash
|
||||||
|
gcloud run services describe $CLOUD_RUN_SVC \
|
||||||
|
--project=$GCP_PROJECT --region=$GCP_REGION \
|
||||||
|
--format="yaml(status,spec.template.spec.containers)"
|
||||||
|
|
||||||
|
gcloud artifacts docker images list \
|
||||||
|
gcr.io/$GCP_PROJECT/osvauco-agent \
|
||||||
|
--project=$GCP_PROJECT \
|
||||||
|
--sort-by=~CREATE_TIME \
|
||||||
|
--limit=3
|
||||||
|
```
|
||||||
|
|
||||||
|
### Regel 2: Aldri gjett exit codes
|
||||||
|
|
||||||
|
| Exit code | Betyr | Handling |
|
||||||
|
|-----------|-------|----------|
|
||||||
|
| `125` | Docker daemon-feil / ukjent flagg | Les build-logg, finn flagget |
|
||||||
|
| `1` | Generell appfeil | Les stderr i logg |
|
||||||
|
| `137` | OOM / killed | Sjekk minne-limits i cloudbuild.yaml |
|
||||||
|
| `2` | Misuse av shell / kommando | Feil argument til gcloud/docker |
|
||||||
|
|
||||||
|
### Regel 3: Aldri fiks symptomer — fiks rot-årsak
|
||||||
|
|
||||||
|
❌ Feil: «build feiler → legg til --no-cache»
|
||||||
|
✅ Riktig: «build feiler → les logg → Step 3/8 feiler på apt-get → dependency mangler → fiks Dockerfile»
|
||||||
|
|
||||||
|
### Regel 4: Bekreft alltid før du konkluderer at noe virker
|
||||||
|
|
||||||
|
Etter enhver endring:
|
||||||
|
```bash
|
||||||
|
gcloud run revisions list \
|
||||||
|
--service=$CLOUD_RUN_SVC \
|
||||||
|
--project=$GCP_PROJECT \
|
||||||
|
--region=$GCP_REGION \
|
||||||
|
--limit=3
|
||||||
|
|
||||||
|
curl -s -o /dev/null -w "%{http_code}" \
|
||||||
|
-H "Authorization: Bearer $(gcloud auth print-identity-token)" \
|
||||||
|
https://opax.vauco.no/health
|
||||||
|
```
|
||||||
|
|
||||||
|
### Regel 5: Bruk strukturerte observasjoner
|
||||||
|
|
||||||
|
Når du rapporterer en feil, skriv alltid:
|
||||||
|
```
|
||||||
|
OBSERVASJON: [hva du faktisk leste i loggene]
|
||||||
|
ROT-ÅRSAK: [hva som faktisk feilet og hvorfor]
|
||||||
|
FIX: [konkret endring med diff]
|
||||||
|
VERIFY: [kommando for å bekrefte fix]
|
||||||
|
```
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## Session Protocol (Nemotron Loop)
|
||||||
|
|
||||||
|
### BOOT
|
||||||
|
- Read `docs/AGENT_RULEBOOK.md`, `docs/MASTERPLAN.md`, `docs/ROADMAP.md` og `docs/HANDOFF.md`.
|
||||||
|
- Print LOCKED DEFINITIONS kompakt.
|
||||||
|
- Print siste `## NESTE OPPGAVE` fra HANDOFF.md.
|
||||||
|
- Hvis ingen NESTE OPPGAVE → advar og les ROADMAP NOW-seksjon.
|
||||||
|
- Sjekk GCP auth: `gcloud auth list` og `gcloud config get-value project`
|
||||||
|
- Sjekk om `.env` eksisterer: `ls -la .env` — hvis IKKE: rapporter til Chris umiddelbart, IKKE opprett den.
|
||||||
|
|
||||||
|
### PLAN
|
||||||
|
- Før enhver kodeendring, skriv en kort PLAN-blokk i Markdown:
|
||||||
|
- Filer som berøres
|
||||||
|
- Forventet resultat
|
||||||
|
- HITL gate påkrevd
|
||||||
|
- IKKE gå til EXECUTE uten human bekreftelse.
|
||||||
|
|
||||||
|
### EXECUTE
|
||||||
|
- Gjennomfør nøyaktig den endringen som er beskrevet i PLAN-blokken — ikke mer, ikke mindre.
|
||||||
|
- Vis alltid full diff før du skriver noen fil.
|
||||||
|
- Aldri batch urelaterte endringer i ett EXECUTE-steg.
|
||||||
|
|
||||||
|
### VERIFY
|
||||||
|
- Kjør relevant verifikasjonskommando (`curl`, `gcloud`, `grep`, `git log`).
|
||||||
|
- Angi resultatet eksplisitt som `PASS` eller `FAIL`.
|
||||||
|
- Ved FAIL → **les loggene** → identifiser rot-årsak → rapporter.
|
||||||
|
- IKKE gå videre til LOG før VERIFY er PASS.
|
||||||
|
|
||||||
|
### LOG
|
||||||
|
- Append til `docs/OSVAUCO_OPAX_SESSION_LOG.md`:
|
||||||
|
```
|
||||||
|
## SLUTTRAPPORT – <dato> – <Fase>
|
||||||
|
- Hva: <beskrivelse av endring>
|
||||||
|
- Filer: <liste over endrede filer>
|
||||||
|
- Verifisering: <kommando + resultat>
|
||||||
|
|
||||||
|
## NESTE OPPGAVE
|
||||||
|
<én konkret neste oppgave>
|
||||||
|
```
|
||||||
|
|
||||||
|
### NEXT
|
||||||
|
- Ved neste sesjonstart, les `## NESTE OPPGAVE` før du gjør noe annet.
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## Hard Rules
|
||||||
|
|
||||||
|
1. **Aldri endre LOCK LIST-verdier** uten eksplisitt human instruksjon.
|
||||||
|
2. **Vis alltid diff før du skriver** noen fil.
|
||||||
|
3. **Aldri batch urelaterte endringer** i ett EXECUTE-steg.
|
||||||
|
4. **OPAX (`opax.vauco.no`) er kun management plane** — den mottar aldri rå pasientdata.
|
||||||
|
5. **Medioteq kliniske data** forblir i `europe-north1` innenfor Medioteq GCP-prosjektgrensen.
|
||||||
|
6. **Deploy `clinical-mcp` og `clinical-orchestrator`** til Medioteq-prosjektet, aldri Vauco-prosjektet.
|
||||||
|
7. **HITL gates**: PLAN godkjenner rekkefølge → AUDIT godkjenner format → OPS bekrefter EST → Human bekrefter før EXEC kjøres.
|
||||||
|
8. **Aldri søk på nett for å diagnostisere feil du kan lese i loggene.**
|
||||||
|
9. **Aldri anta at noe virker — verifiser alltid med en faktisk kommando.**
|
||||||
|
10. **Aldri gjett på koden — les den.** Du er i repoet. Bruk `cat`, `grep`, `git diff`.
|
||||||
|
11. **Aldri skriv .env fra .env.example** — se Kritiske fil-sikkerhetsregler.
|
||||||
|
12. **Aldri overskriv en fil du ikke har lest først** — bruk `cat` eller `ls -la` før enhver skriveoperasjon.
|
||||||
|
13. **Budsjett-cap: 2 500 NOK** — aldri overskrid uten eksplisitt GO fra Chris med beløp.
|
||||||
|
14. **ABSOLUTT REGEL:** Når Chris spesifiserer region, modell eller parameter eksplisitt — bruk ALLTID den verdien. Ikke overstyr med LOCKED DEFINITIONS.
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## Diagnostics Playbook (KRITISK)
|
||||||
|
|
||||||
|
> **Grunnregel: Aldri gjett. Alltid hent faktisk data før du konkluderer.**
|
||||||
|
|
||||||
|
### 🔴 Cloud Build feiler
|
||||||
|
|
||||||
|
```bash
|
||||||
|
BUILD_ID=$(gcloud builds list \
|
||||||
|
--project=propane-will-491900-m5 \
|
||||||
|
--limit=1 \
|
||||||
|
--format="value(id)")
|
||||||
|
|
||||||
|
gcloud builds log $BUILD_ID \
|
||||||
|
--project=propane-will-491900-m5 2>&1 | tail -100
|
||||||
|
```
|
||||||
|
|
||||||
|
### 🔴 Cloud Run svarer ikke / returnerer feil
|
||||||
|
|
||||||
|
```bash
|
||||||
|
gcloud run services describe osvauco-agent \
|
||||||
|
--project=propane-will-491900-m5 \
|
||||||
|
--region=europe-west1 \
|
||||||
|
--format="value(status.conditions)"
|
||||||
|
|
||||||
|
gcloud logging read \
|
||||||
|
'resource.type=cloud_run_revision AND resource.labels.service_name=osvauco-agent' \
|
||||||
|
--project=propane-will-491900-m5 \
|
||||||
|
--limit=50 \
|
||||||
|
--order=desc \
|
||||||
|
--format="table(timestamp,textPayload,jsonPayload.message)"
|
||||||
|
```
|
||||||
|
|
||||||
|
### 🔴 Auth / IAP-feil
|
||||||
|
|
||||||
|
```bash
|
||||||
|
gcloud auth list
|
||||||
|
gcloud config get-value project
|
||||||
|
gcloud auth print-identity-token
|
||||||
|
|
||||||
|
gcloud iap web get-iam-policy \
|
||||||
|
--project=propane-will-491900-m5 \
|
||||||
|
--resource-type=cloud-run \
|
||||||
|
--service=osvauco-agent
|
||||||
|
```
|
||||||
|
|
||||||
|
### 🔴 Claude / Vertex AI-feil
|
||||||
|
|
||||||
|
```bash
|
||||||
|
# Test Claude via Vertex EU endpoint
|
||||||
|
curl -X POST \
|
||||||
|
"https://eu-aiplatform.googleapis.com/v1/projects/propane-will-491900-m5/locations/eu/publishers/anthropic/models/claude-opus-4-6:rawPredict" \
|
||||||
|
-H "Authorization: Bearer $(gcloud auth print-access-token)" \
|
||||||
|
-H "Content-Type: application/json" \
|
||||||
|
-d '{
|
||||||
|
"anthropic_version": "vertex-2023-10-16",
|
||||||
|
"max_tokens": 256,
|
||||||
|
"messages": [{"role": "user", "content": "ping"}]
|
||||||
|
}'
|
||||||
|
```
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## GCP-konvensjoner for dette prosjektet
|
||||||
|
|
||||||
|
```bash
|
||||||
|
--project=propane-will-491900-m5
|
||||||
|
--region=europe-west1
|
||||||
|
|
||||||
|
CLOUD_RUN_SVC=osvauco-agent
|
||||||
|
IMAGE=gcr.io/propane-will-491900-m5/osvauco-agent
|
||||||
|
|
||||||
|
gcloud builds submit --config=cloudbuild.yaml --project=propane-will-491900-m5
|
||||||
|
|
||||||
|
gcloud run deploy osvauco-agent \
|
||||||
|
--image=$IMAGE:latest \
|
||||||
|
--project=propane-will-491900-m5 \
|
||||||
|
--region=europe-west1 \
|
||||||
|
--platform=managed
|
||||||
|
```
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## Standard Boot Prompt
|
||||||
|
|
||||||
|
Lim inn dette ved start av HVER sesjon i Claude Code TUI:
|
||||||
|
|
||||||
|
```
|
||||||
|
BOOT: Les @docs/AGENT_RULEBOOK.md, @docs/MASTERPLAN.md, @docs/ROADMAP.md og @docs/HANDOFF.md. Print LOCKED DEFINITIONS kompakt. Oppsummer NESTE OPPGAVE fra HANDOFF.md i én setning. Foreslå 3 konkrete neste-steg, men IKKE utfør noe — vent på PLAN APPROVED. Bekreft at du forstår ABSOLUTT REGEL #1.
|
||||||
|
```
|
||||||
Loading…
Reference in New Issue
Block a user