136 lines
8.4 KiB
Markdown
136 lines
8.4 KiB
Markdown
# ms-ai-architect — Development
|
||
|
||
Plugin development, testing, KB-refresh. Imported from `CLAUDE.md` via pointer.
|
||
|
||
## Legge til ny kunnskapsbase
|
||
1. Opprett `.md`-fil i riktig undermappe under den relevante skillens `references/`-mappe (f.eks. `skills/ms-ai-engineering/references/`)
|
||
2. Følg format fra eksisterende filer (header, dato, seksjoner)
|
||
3. Oppdater relevant SKILL.md med referanse
|
||
|
||
## Legge til ny kommando
|
||
1. Opprett `commands/navn.md` med frontmatter (`description`, `argument-hint`)
|
||
2. Følg mønster fra eksisterende kommandoer
|
||
3. Oppdater `commands/help.md` med ny kommando
|
||
4. Oppdater `CLAUDE.md`
|
||
|
||
## Legge til ny agent
|
||
1. Opprett `agents/navn-agent.md` med frontmatter (`name`, `description`, `model`, `color`, `tools`)
|
||
2. Inkluder tydelig "triggers on" i description
|
||
3. Oppdater `CLAUDE.md`
|
||
|
||
## Testing
|
||
|
||
### Statisk validering
|
||
```bash
|
||
# Kjør plugin-validering (frontmatter, encoding, KB-referanser)
|
||
bash tests/validate-plugin.sh
|
||
```
|
||
|
||
### KB-ferskhet (sitemap-basert, manuell drift)
|
||
|
||
**Apply-fasen kjøres via slash-kommandoen** (krever aktiv Claude Code-sesjon, holder oss innenfor Anthropic Consumer Terms § 3):
|
||
|
||
```text
|
||
/architect:kb-update # default: critical + high
|
||
/architect:kb-update --priorities critical # bare critical
|
||
/architect:kb-update --skip-discover # hopp over new-URL discovery
|
||
/architect:kb-update --dry-run # rapport uten apply
|
||
```
|
||
|
||
**Endringsrapport-fasen kan kjøres som rent Node-script (ingen LLM-kostnad):**
|
||
|
||
```bash
|
||
# Poll sitemaps → endringsrapport (ingen filendringer)
|
||
node scripts/kb-update/run-weekly-update.mjs --force
|
||
|
||
# Med discovery av nye relevante sider
|
||
node scripts/kb-update/run-weekly-update.mjs --force --discover
|
||
|
||
# Vis rapport på nytt etter polling
|
||
node scripts/kb-update/report-changes.mjs
|
||
|
||
# Bygg/oppdater URL-registry fra referansefiler
|
||
node scripts/kb-update/build-registry.mjs [--merge]
|
||
```
|
||
|
||
Systemet sammenligner Microsoft Learn sitemap-`<lastmod>` med filenes `Last updated:` header, og genererer en prioritert endringsrapport (critical/high/medium/low).
|
||
|
||
**Match rate:** ~73% av 1343 URLer matcher mot sitemaps (poll `--force`, juni 2026). Microsoft rebrandet «Azure AI Foundry» → «Microsoft Foundry» og flyttet `/azure/ai-foundry/` → `/azure/foundry/`; Sesjon 2 remappet de 164 ai-foundry-URLene (`migrate-ai-foundry.mjs`), som løftet foundry fra 0 % → ~62 % tracked. Resten som ikke matcher er nesten utelukkende `azure/foundry/openai/`-stier (egen URL-struktur — ikke remappet, ingen verifiserte mål).
|
||
|
||
**Taksonomi (lag 0):** sitemap-prefikser, relevans (INCLUDE/EXCLUDE), category→skill og file-priority bor i `scripts/kb-update/data/domain-taxonomy.json` (eneste sannhetskilde, tracket). `poll-sitemaps`, `discover-new-urls` og `report-changes` leser den. `category-skill-map.json` er ukonsumert av kode (legacy doc) — ved divergens vinner taksonomien (disk-sann).
|
||
|
||
**Schedulering:** Pluginen schedulerer ingenting. Bruker som vil ha periodisk varsling kan sette opp egen cron / launchd / systemd / GitHub Actions som kjører `node scripts/kb-update/run-weekly-update.mjs --force --discover` (rapport-fasen, ikke apply). Apply-fasen er bevisst manuell — den krever LLM-resonnering på diff og kjører fra en åpen Claude Code-sesjon.
|
||
|
||
Legacy (deprecated):
|
||
```bash
|
||
bash scripts/kb-staleness-check.sh # mtime-basert, upålitelig etter git clone
|
||
```
|
||
|
||
### Kurs-deteksjon (Spor C / C3 — Learn Platform API, opt-in)
|
||
|
||
Et parallelt, uavhengig spor fra sitemap-discoveren: oppdage at Microsoft har publisert **nye** eller **endrede** treningskurs (modules + learning paths) i produktene KB-en dekker, slik at operatøren kan vurdere om temaet bør dekkes. Et kurs er et *signal*, ikke en doc-side — det auto-ingestes aldri. Full spec: [`c3-course-detection-plan.md`](c3-course-detection-plan.md).
|
||
|
||
**To-stegs-mønster (samme invariant som `discover-new-urls`):**
|
||
|
||
1. **Deteksjon (Claude-fri, opt-in, Node-script).** `detect-courses.mjs` leser tre Entra-creds fra macOS Keychain, henter token, paginerer Platform API (`/api/v1/modules` + `/learning-paths`) med produkt- og `updatedAt.gt`-filter, diff-er mot `data/course-registry.json` (detektorens egen sporings-state), og skriver **kun** to private filer: `data/course-detection-report.json` (kandidater) + oppdatert `course-registry.json`. Importerer **aldri** `saveDecisions` — skriver hverken `skills/` eller `decisions.json`.
|
||
|
||
```bash
|
||
node scripts/kb-update/detect-courses.mjs # default data-dir
|
||
node scripts/kb-update/detect-courses.mjs --data-dir DIR # omdiriger IO (tester)
|
||
```
|
||
|
||
Fail-soft: mangler creds → `status:"skipped"` + exit 0; vedvarende nettverksfeil → `status:"error"` + exit 0. Opt-in inni opt-in: steget kjøres kun av scheduleren når `include_course_detection: true` (default `false`). Sett flagget via eier-CLI (skriver den gitignored local.md atomisk, bevarer øvrige nøkler):
|
||
|
||
```bash
|
||
node scripts/kb-update/write-schedule-config.mjs --enabled true --cadence daily --courses true
|
||
```
|
||
|
||
`--courses` er valgfritt — utelat det for å la en verdi satt andre steder stå urørt.
|
||
|
||
2. **SessionStart-surfacing (read-only).** `session-start-context.mjs` leser `course-detection-report.json` og viser en one-liner via `summarizeCourses` («Kurs-signaler: N nye / M endrede kurs i dekkede produkter. Kjør /architect:kb-update») — speiler skill-signaler-blokka. `removed` er kun et informasjonssignal i rapporten, aldri en surfacet lead (spec §4.2). Hooken spawner ingenting for kurs-sporet.
|
||
|
||
3. **Gate (operatør, Claude-i-loop).** `/architect:kb-update` §3c leser rapporten, presenterer nye/endrede leads, og skriver godkjente leads til den UID-nøklede `courses`-kolleksjonen i `decisions.json` (via `recordCourseLead`). `--dry-run` viser leads uten å skrive. **Strukturell invariant:** ingen apply-path leser `courses` → et godkjent kurs-lead trigger aldri fetch/transform/KB-skriving.
|
||
|
||
Slug→skill-mapping er config i `domain-taxonomy.json` (`course_products`), ikke hardkoding. `last_full_enum`-kadens (≥30 d) styrer når `removed` beregnes (kun full-enumerering — aldri inkrementelt).
|
||
|
||
### Skill-kvalitetsscore (Spor D — objektiv 0–100-score per skill)
|
||
|
||
Måler skill-kvalitet deterministisk mot Anthropics «Skill authoring best practices». Rubrikken K1–K10 (`eval.mjs`) + de fem ekstra deterministiske sjekkene N1–N5 aggregeres til én 0–100-score per skill via **vektet delpoeng med hardt gulv** på de bærende kriteriene (K1 trigger-presisjon, K10 søsken-overlapp): feiler ett gulv-kriterium kappes scoren under målet (89), uansett øvrig form. Mål: **alle 5 skills ≥90 %**. Full spec: [`skill-quality-scoring-plan.md`](skill-quality-scoring-plan.md).
|
||
|
||
```bash
|
||
node scripts/kb-eval/score-skill.mjs # human-rapport: score + sortert forbedringsliste per skill
|
||
node scripts/kb-eval/score-skill.mjs --json # maskin-output (scoreReport: target/scored/below)
|
||
node scripts/kb-eval/score-skill.mjs --gate 90 # non-zero exit hvis noen skill < 90
|
||
node scripts/kb-eval/score-skill.mjs --skill ms-ai-advisor # scope til én skill (inkrementelt)
|
||
```
|
||
|
||
Arkitektur: `eval.mjs buildReport()` (disk: deterministisk + K10 + merget operatør-gated judge-cache) → `lib/skill-score.mjs` (REN: `scoreSkill`/`scoreReport`/`formatScoreReport`, ingen disk). N1 name-validitet · N2 description ≤1024 · N3 refs én nivå dypt · N4 TOC i ref-filer >100 linjer · N5 forward-slash-stier. Judge-kriterier (K1/K4/K7/K8/K9) degraderer pent: mangler judge → ekskluderes fra teller+nevner, scoren merkes `provisional` (K1-gulv kan ikke håndheves), K10-gulvet (deterministisk) gjelder alltid.
|
||
|
||
**Korpus-invariant (roadmap):** Hele korpuset skal holde ≥90 % til enhver tid. Ved skill-endring (create/update/merge/split via `apply-skill-op.mjs`) re-scores **kun** den endrede skillen inkrementelt (men hele korpuset evalueres siden K10 trenger alle søsken-descriptions), og `--gate 90` håndhever terskelen via operatør-gate.
|
||
|
||
### E2E-regresjonstester
|
||
```bash
|
||
# Kjør alle E2E-suiter
|
||
bash tests/run-e2e.sh
|
||
|
||
# Kjør enkeltsuiter
|
||
bash tests/run-e2e.sh --security
|
||
bash tests/run-e2e.sh --cost
|
||
bash tests/run-e2e.sh --summary
|
||
bash tests/run-e2e.sh --ai-act
|
||
```
|
||
|
||
Fixture-basert validering av agent-output (sikkerhet, kostnad, sammendrag). Tester struktur, encoding, og domene-spesifikke krav uten å invokere Claude.
|
||
|
||
### Manuell test
|
||
```bash
|
||
# Test at plugin registreres
|
||
cd <plugin-root>
|
||
claude --plugin ./plugins/ms-ai-architect
|
||
|
||
# Kjør hovedcommand
|
||
/architect
|
||
|
||
# Vis alle kommandoer
|
||
/architect:help
|
||
```
|