Gå til innholdet
Archgate

Hurtigstart

1. Installer Archgate

Section titled “1. Installer Archgate”

Hvis du ikke har installert CLI-en ennå:

Terminal window
# Standalone (no Node.js required)
curl -fsSL https://cli.archgate.dev/install-unix | sh


# Or via npm
npm install -g archgate

Se Installasjon-siden for alle alternativer, inkludert Windows og egendefinerte installasjonsmapper.

2. Initialiser prosjektet ditt

Section titled “2. Initialiser prosjektet ditt”

Naviger til prosjektroten din og kjør init-kommandoen:

Terminal window
cd my-project
archgate init

Dette oppretter .archgate/-mappen med følgende struktur:

.archgate/
  adrs/
    GEN-001-example.md   # Example ADR (rules: false)
  lint/
    README.md            # Conventions for linter-specific rules
  rules.d.ts              # Type definitions for .rules.ts files

De genererte filene gir deg et fungerende eksempel å bygge videre på.

3. Rediger eksempel-ADR-en

Section titled “3. Rediger eksempel-ADR-en”

Åpne .archgate/adrs/GEN-001-example.md. Hver ADR starter med YAML frontmatter som definerer identiteten:

---
id: GEN-001
title: Example Architecture Decision
domain: general
rules: false
---
  • id: Unik identifikator. Konvensjonen er <PREFIX>-NNN (f.eks. ARCH-001, GEN-001), men enhver streng fungerer.
  • title: Lesbart navn for beslutningen.
  • domain: Grupperer relaterte ADR-er (architecture, backend, frontend, data eller general).
  • rules: Sett til true hvis denne ADR-en har en tilhørende .rules.ts-fil med automatiserte sjekker. Det genererte eksemplet leveres med rules: false.
  • files: Valgfrie glob-mønstre som begrenser hvilke filer reglene gjelder for. Utelates den, gjelder reglene hele prosjektet.

Under frontmatter skriver du beslutningen i Markdown. Archgate pålegger ikke en bestemt seksjonsstruktur, men de anbefalte seksjonene er: Context, Decision, Do’s and Don’ts, Consequences, Compliance og References.

4. Legg til en tilhørende regelfil

Section titled “4. Legg til en tilhørende regelfil”

Opprett en .rules.ts-fil ved siden av ADR-en med samme navneprefiks (f.eks. GEN-001-example.rules.ts for det genererte eksemplet). Sett deretter rules: true i ADR-ens frontmatter — archgate check laster kun inn en tilhørende regelfil når ADR-en aktiverer det. Regler skrives i TypeScript med RuleSet-typen:

/// <reference path="../rules.d.ts" />


export default {
  rules: {
    "no-console-error": {
      description: "Use logError() instead of console.error()",
      async check(ctx) {
        for (const file of ctx.scopedFiles) {
          const matches = await ctx.grep(file, /console\.error\(/);
          for (const match of matches) {
            ctx.report.violation({
              message: "Use logError() instead of console.error()",
              file: match.file,
              line: match.line,
              fix: "Import logError from your helpers and use it instead",
            });
          }
        }
      },
    },
  },
} satisfies RuleSet;

Hver regel har en unik nøkkel, en beskrivelse og en asynkron check-funksjon. Inne i check har du tilgang til:

  • ctx.scopedFiles — Filer som matcher ADR-ens files glob-mønstre.
  • ctx.grep(file, pattern) — Søk i en fil etter regex-treff, returnerer filstier og linjenumre.
  • ctx.report.violation() — Rapporter et brudd med melding, filsti, linjenummer og valgfritt rettingsforslag.

5. Kjør sjekker

Section titled “5. Kjør sjekker”

Kjør samsvarssjekken mot kodebasen din:

Terminal window
archgate check

Archgate laster inn hver ADR med rules: true, kjører den tilhørende regelfilen og skriver ut resultatene. Avslutningskoden forteller deg utfallet:

AvslutningskodeBetydning
0Alle regler bestått. Ingen brudd funnet.
1Ett eller flere brudd oppdaget.
2Intern feil (f.eks. feilformatert ADR eller regel).

For å sjekke bare staged-filer (nyttig i pre-commit hooks eller CI):

Terminal window
archgate check --staged

Hva nå?

Section titled “Hva nå?”

Nå som du har et fungerende oppsett, kan du dykke dypere:

Forstå konseptene:

  • ADR-er — Hva Architecture Decision Records er og hvordan Archgate bruker dem.
  • Regler — Hvordan tilhørende .rules.ts-filer gjør beslutninger om til automatiserte sjekker.
  • Domener — Hvordan domener grupperer relaterte ADR-er og begrenser filtilordning.

Skriv dine egne:

  • Skrive ADR-er — Lær det fullstendige ADR-formatet og beste praksis for å skrive effektive beslutninger.
  • Skrive regler — Utforsk regel-API-et, avanserte mønstre og hvordan du tester reglene dine.
  • Vanlige regelmønstre — Mønstre du kan kopiere og lime inn for avhengighetssjekker, navnekonvensjoner og mer.

Integrer i arbeidsflyten din:

  • CI-integrasjon — Koble archgate check til GitHub Actions, GitLab CI eller en hvilken som helst pipeline.
  • Pre-commit Hooks — Kjør sjekker lokalt før hver commit.
  • Claude Code-plugin — Gi AI-agenter arkitekturbevisste guardrails med rollebaserte ferdigheter.
  • Cursor-integrasjon — Bruk Archgate med Cursor IDE for AI-assistert utvikling.