Gå til indholdet

AGENTS.md — sådan arbejder vi med AI i dette repo

Kanonisk instruktionsfil for AI-kodeagenter (Claude Code, Codex, Cursor m.fl.) der arbejder i dette repo. Bevidst værktøjs-neutral, så alle agenter kan bruge den. CLAUDE.md peger hertil.

Alt materiale er på dansk. Skriv nye dokumenter og commits på dansk.

1. Hvad er dette repo?

Central videns- og dokumentationsbase for Melsens — AI Website Factory (to brødre, AI-drevet virksomhed). Repoet indeholder strategi, arkitektur-beslutningsgrundlag, markedsresearch, produkter og beslutninger — ikke selve applikationskoden (den bor i egne repos, når fabrikken bygges).

Projektet i to spor: - Produktlinje A — isoleret pr. kunde: skræddersyet SaaS/app, egen deployment pr. kunde, salgbar som kode. - Produktlinje B — delt Website OS: ét multi-tenant kodebase → tusindvis af SMV-websites (fabrikken).

2. Repo-kort

Sti Indhold
administration/ Strategi, forretningsmodel, roadmap, roller, projektledelse
arkitektur/ Teknisk fundament + beslutningsgrundlag (nummererede docs)
arkitektur/adr/ Architecture Decision Records (trufne beslutninger)
markeds-research/ Markedsanalyse, niche, ICP, go-to-market
produkter/ Ét underbibliotek pr. produkt + _skabelon/
artifacts/ Committede kopier af visuelle/interaktive artifacts
GitHub Issues [Idé]-issues (idéer/moduler) + [Decision]-issues (åbne beslutninger)

3. Sådan arbejder vi med AI (arbejdsaftaler)

  1. Læs relevant materiale før du handler — start i administration/00-overblik.md og den relevante søjle.
  2. Verificér foranderlige fakta mod primærkilder. Priser, kapabiliteter, limits og leverandør-features skifter hurtigt — slå dem op hos leverandøren, dato-stempl (fx "verificeret ÅÅÅÅ-MM-DD"), og markér usikkerhed. Svar aldrig priser/limits fra hukommelsen.
  3. Kildeliste nederst i hvert dokument (klikbare links).
  4. Anbefalinger er FORSLAG, ikke beslutninger — indtil de er fanget som en ADR (se §5).
  5. Diskussionsoplæg markeres tydeligt øverst: Status: DISKUSSIONSOPLÆG — ingen beslutning truffet.
  6. Levende dokumentation: når noget ændres/besluttes, opdatér den relevante side i samme omgang.
  7. Vær ærlig om trade-offs — også når vores foretrukne valg taber på et punkt. Undgå at tilføje teknologi, fordi den er interessant; spørg altid "hvilket problem løser dette, som stakken ikke allerede løser?".
  8. Parallel research når emnet er bredt; syntetisér til ét kildehenvist dokument.

4. Beslutnings-livscyklus (vigtig)

  • Åbne, ikke-trufne beslutninger = [Decision]-issues (label decision), grupperet efter tema med tjeklister. Det er her "hvad mangler vi at beslutte" bor.
  • Idéer / moduler / features = [Idé]-issues (label idé).
  • Ufravigelige krav formuleres som rammer (ikke åbne valg) i det relevante dokument.
  • Når en beslutning træffes:
  • Sæt hak i boksen i [Decision]-issuet.
  • Skriv en ADR i arkitektur/adr/NNNN-kort-titel.md.
  • Opdatér det relevante dokument. → beslutningen flytter fra "åben på trackeren" til "besluttet og dokumenteret".

5. ADR-konvention

  • Kopiér arkitektur/adr/0001-skabelon.md → NNNN-kort-titel.md (fortløbende nummer).
  • ADR'er er uforanderlige: tilføj nye frem for at omskrive; markér erstattede med "superseded af ADR-XXXX" + link.
  • Skriv en ADR ved valg der er dyre at lave om: cloud/host, backend/database, auth, agent-framework, billing/betaling, datamodel. Trivielle valg behøver ingen ADR.

6. Artifacts-konvention

  • Hvert visuelt/interaktivt artifact har en committet kopi i artifacts/.
  • Opdatér kopien og katalogets "senest opdateret" i artifacts/README.md hver gang den hostede version ændres. Kilde-dokumenterne er den autoritative sandhed; artifacts er øjebliksbilleder.

7. Produkt-konvention

  • Ét produkt = ét underbibliotek i produkter/, kopieret fra _skabelon/, og tilføjet i produkter/produktiserede-tilbud.md.

7b. C4-arkitektur & docs-portal

  • Al software-arkitektur dokumenteres med C4-modellen — som LikeC4-DSL i arkitektur/c4/ (model.c4 er single source of truth). Minimum Context + Container pr. system; Code-niveau springes over. Se arkitektur/c4/README.md og ADR-0002. Bemærk: en C4-"Container" er ikke en Docker/OCI-container.
  • Diagrammer opdateres i samme PR som arkitekturændringen (levende dokumentation). Render + commit billeder med npx likec4@1.59.1 export png -o assets.
  • Docs-portal: MkDocs + Material, hostet privat på Cloudflare Pages + Access (auto-build ved push). Se docs-portal.md. Portalen embedder de eksporterede C4-billeder.

8. Git & samarbejde

  • Udvikl på den aftalte feature-branch; lav små, beskrivende commits på dansk; push.
  • Opret ikke pull requests medmindre der bedes om det.
  • Skriv aldrig interne model-id'er eller sessions-links ind i filer, der pushes til repoet.

9. Projektets faste rammer vs. åbne valg

Faste krav (besluttet): - MobilePay som betalingsmåde (engangs + recurring) er ufravigeligt.

Bærende principper (forslag — styrer arbejdet indtil en ADR ændrer dem): - To produktlinjer (A isoleret / B delt Website OS) — se arkitektur/06-* og arkitektur/07-*. - Portabilitet: OCI-container + Terraform + Postgres (linje A); struktureret indhold → delt renderer → live + statisk eksport (linje B). Kunden ejer domæne/indhold/data; vi ejer platform/moduler. - Sprog: TypeScript som standard; C#/.NET (Microsoft-kunder), Python (data/scripting).

Alt øvrigt er endnu ikke besluttet → se [Decision]-issues (label decision).

10. Start her

  • Strategisk overblik: administration/00-overblik.md
  • Arkitektur: arkitektur/07-website-os-multi-tenant-arkitektur.md (fabrikken), 06-isolation-hosting-og-overdragelse.md (isoleret), 08-modul-system.md + 09-billing-og-betaling.md
  • Marked: markeds-research/niche-og-icp.md
  • Åbne beslutninger: GitHub Issues → filter label:decision
  • C4-diagrammer: arkitektur/c4/ · Docs-portal/hosting: docs-portal.md

AGENTS.md er den kanoniske "sådan arbejder vi"-fil. Den beskriver proces og konventioner — det faglige indhold står i de enkelte dokumenter. Opdatér denne fil når vi aftaler nye arbejdsmåder.