---
title: ADR-skjema
description: Komplett YAML frontmatter-skjema og Markdown-strukturreferanse for Archgate Architecture Decision Records. Alle felt og valideringsregler forklart.
---

Hver Archgate ADR er en Markdown-fil lagret i `.archgate/adrs/` med YAML frontmatter som definerer beslutningens identitet og omfang. Denne siden dokumenterer frontmatter-skjemaet, Markdown-seksjonsstrukturen og valideringsatferd.

## Frontmatter-skjema

YAML frontmatter-blokken ligger mellom `---`-skilletegn øverst i filen.

```yaml
---
id: ARCH-001
title: Command Structure
domain: architecture
rules: true
files: ["src/commands/**/*.ts"]
---
```

### Felt

| Felt               | Type       | Påkrevd | Beskrivelse                                                                                                                                                                                                                               |
| ------------------ | ---------- | ------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `id`               | `string`   | Ja      | Unik identifikator. Må være ikke-tom. Konvensjon: `PREFIX-NNN` (f.eks. `ARCH-001`).                                                                                                                                                       |
| `title`            | `string`   | Ja      | Lesbar tittel på beslutningen. Må være ikke-tom.                                                                                                                                                                                          |
| `domain`           | `string`   | Ja      | Et registrert domenenavn i kebab-case med små bokstaver. Innebygde: `backend`, `frontend`, `data`, `architecture`, `general`. Egendefinerte domener registreres via [`archgate adr domain add`](/reference/cli/adr/#archgate-adr-domain). |
| `rules`            | `boolean`  | Ja      | Om denne ADR-en har en tilhørende `.rules.ts`-fil med automatiserte kontroller.                                                                                                                                                           |
| `files`            | `string[]` | Nei     | Globmønstre som avgrenser hvilke filer reglene gjelder for.                                                                                                                                                                               |
| `respectGitignore` | `boolean`  | Nei     | Om `.gitignore`-filer skal filtreres bort. Standard er `true`.                                                                                                                                                                            |

### id

ADR-identifikatoren. Etter konvensjon brukes domeneprefikset etterfulgt av et null-utfylt sekvensnummer (f.eks. `ARCH-001`, `BE-003`). Kommandoen `archgate adr create` genererer ID-er automatisk.

Enhver ikke-tom streng er gyldig, men å følge prefikskonvensjonen holder ADR-ene organisert og sorterbare.

### title

Et kort, beskrivende navn for den arkitektoniske beslutningen. Vises i `archgate adr list`-utdata og brukes som overskrift når AI-agenter refererer til ADR-en.

### domain

Grupperer relaterte ADR-er sammen. Domenet bestemmer også ID-prefikset som brukes av `archgate adr create`.

Prosjekter kan utvide det innebygde settet med egendefinerte domener via [`archgate adr domain add`](/reference/cli/adr/#archgate-adr-domain). Egendefinerte domene-til-prefiks-tilordninger lagres i `.archgate/config.json` og slås sammen med de innebygde ved lesing.

### rules

Sett til `true` når denne ADR-en har en tilhørende `.rules.ts`-fil. Når `archgate check` kjører, hopper den over ADR-er der `rules` er `false`.

### files

En valgfri matrise med globmønstre som avgrenser regelens fildekning. Når den er til stede, inneholder `ctx.scopedFiles` i regelfilen kun filer som matcher disse mønstrene. Når den er fraværende, er alle prosjektfiler i omfang.

```yaml
files: ["src/commands/**/*.ts"]
```

Flere mønstre kan spesifiseres:

```yaml
files: ["src/api/**/*.ts", "src/middleware/**/*.ts"]
```

### respectGitignore

Styrer om `.gitignore`-filer ekskluderes fra `ctx.scopedFiles`, `ctx.glob()` og `ctx.grepFiles()`. Standard er `true` når feltet utelates -- gitignorerte filer (f.eks. `node_modules/`, `dist/`) filtreres automatisk bort.

Sett til `false` når en regel med vilje trenger å inspisere ignorerte filer, for eksempel for å sjekke strukturen på byggeutdata:

```yaml
respectGitignore: false
files: ["dist/**/*.js"]
```

Når `respectGitignore` er `false`, inkluderes alle filer som matcher `files`-globene uavhengig av `.gitignore`-regler. Når man ikke er inne i et git-repository, har dette feltet ingen effekt -- alle matchede filer inkluderes.

---

## Domeneprefikser

Hvert domene tilordnes et prefiks som brukes i ADR-ID-konvensjonen.

### Innebygde domener

| Domene         | Prefiks | Eksempel-ID |
| -------------- | ------- | ----------- |
| `backend`      | `BE`    | `BE-001`    |
| `frontend`     | `FE`    | `FE-001`    |
| `data`         | `DATA`  | `DATA-001`  |
| `architecture` | `ARCH`  | `ARCH-001`  |
| `general`      | `GEN`   | `GEN-001`   |

Kommandoen `archgate adr create` bruker denne tilordningen til å autogenerere ID-er.

### Egendefinerte domener

Prosjekter kan registrere ytterligere domene-til-prefiks-tilordninger via [`archgate adr domain add`](/reference/cli/adr/#archgate-adr-domain). Når de er registrert, oppfører egendefinerte domener seg som innebygde: `archgate adr create --domain <name>` autogenererer ID-er med det tilhørende prefikset, og ADR-er med egendefinerte domener parses uten problemer.

Se [konseptsiden for domener](/concepts/domains/) for veiledning om når du bør introdusere et egendefinert domene.

---

## Konvensjon for filnavn

ADR-filer følger en navnekonvensjon som koder inn ID-en og en lesbar slug:

```
{ID}-{slug}.md              # Dokumentet
{ID}-{slug}.rules.ts        # Den tilhørende regelfilen (valgfri)
```

For eksempel:

```
ARCH-001-command-structure.md
ARCH-001-command-structure.rules.ts
```

Slugen er en kebab-case-versjon av tittelen, autogenerert av `archgate adr create`.

---

## Markdown-seksjoner

Etter frontmatter følger ADR-kroppen en standard seksjonsstruktur. Selv om Archgate ikke påtvinger spesifikke seksjoner, anbefales følgende struktur for konsistens.

### Context

Beskriver problemet eller situasjonen som utløste beslutningen. Inkluder alternativer som ble vurdert og hvorfor de ble forkastet.

```markdown
## Context

The CLI returns errors in inconsistent formats. Some commands print raw
stack traces, others print nothing, and a few use `console.error()` with
custom formatting.

**Alternatives considered:**

- **No standard** -- Let each command handle errors its own way. Simple
  but leads to an inconsistent user experience.
- **Try/catch wrapper** -- A global try/catch at the CLI entry point.
  Loses context about which command failed.
```

### Decision

Angir selve beslutningen og dens viktigste begrensninger. Dette er den primære seksjonen AI-agenter leser før de skriver kode.

```markdown
## Decision

All commands MUST use `logError()` from `src/helpers/log.ts` for error
output. Commands MUST NOT call `console.error()` directly.
```

### Do's and Don'ts

Konkret, handlingsrettet veiledning delt i to underseksjoner. Disse fungerer som en hurtigreferanse-sjekkliste for utviklere og AI-agenter.

```markdown
## Do's and Don'ts

### Do

- Use `logError(message, detail?)` for all error output
- Include a suggested fix in the detail parameter when possible
- Exit with code 1 for user errors, code 2 for internal errors

### Don't

- Don't call `console.error()` directly in command files
- Don't print stack traces to users
- Don't exit without printing an error message first
```

### Consequences

Delt i tre underseksjoner som dokumenterer avveininger.

```markdown
## Consequences

### Positive

- Consistent error formatting across all commands
- Machine-parseable error output when combined with `--json`

### Negative

- Requires importing `logError` in every command file
- Cannot use built-in error formatting from libraries

### Risks

- New contributors may use `console.error()` by habit. Mitigated by the
  automated rule that scans for direct `console.error()` calls.
```

### Compliance and Enforcement

Beskriver hvordan beslutningen håndheves gjennom automatiserte regler og manuell gjennomgang.

```markdown
## Compliance and Enforcement

### Automated Enforcement

- **Archgate rule** ARCH-002/no-console-error: Scans command files for
  `console.error()` calls. Severity: error.

### Manual Enforcement

Code reviewers MUST verify:

1. Error messages are actionable and include context
2. Exit codes match the error type (1 for user, 2 for internal)
```

### References

Lenker til relaterte ADR-er, ekstern dokumentasjon eller designdokumenter.

```markdown
## References

- [ARCH-001 -- Command Structure](./ARCH-001-command-structure.md)
- [Node.js process.exit documentation](https://nodejs.org/api/process.html#processexitcode)
```

---

## Tilhørende regelfil

Når `rules: true`, leter Archgate etter en tilhørende fil med samme navn men `.rules.ts`-endelse.

```
ARCH-002-error-handling.md          # rules: true i frontmatter
ARCH-002-error-handling.rules.ts    # tilhørende regelfil
```

Regelfilen må eksportere et standard `RuleSet` ved hjelp av et vanlig objekt med `satisfies RuleSet`:

```typescript
/// <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 src/helpers/log and use it instead",
            });
          }
        }
      },
    },
  },
} satisfies RuleSet;
```

Se [Rule API](/reference/rule-api/) for den komplette TypeScript API-referansen.

---

## Validering

YAML frontmatter valideres ved parsetidspunkt ved hjelp av et Zod-skjema. Ugyldig frontmatter forårsaker en parsefeil med en beskrivende melding.

### Påkrevde felt

Hvis et påkrevd felt mangler, feiler ADR-parsingen:

```
Invalid ADR frontmatter in ARCH-001-example.md:
  - domain: Required
```

### Ugyldig domeneformat

Hvis `domain` ikke er en gyldig kebab-case-identifikator (f.eks. har store bokstaver eller mellomrom):

```
Invalid ADR frontmatter in ARCH-001-example.md:
  - domain: domain must be lowercase kebab-case (e.g. 'backend', 'ml-ops')
```

Merk: parseren aksepterer ethvert navn som matcher kebab-case-mønsteret. Om et spesifikt navn er "kjent" for prosjektet -- og dermed har et prefiks som `archgate adr create` kan bruke -- avhenger av det innebygde settet pluss eventuelle egendefinerte domener registrert via [`archgate adr domain add`](/reference/cli/adr/#archgate-adr-domain). Å opprette en ADR med et uregistrert domenenavn feiler med en "Unknown ADR domain"-feil som foreslår å kjøre `archgate adr domain add`.

### Typefeil

Hvis `rules` er en streng i stedet for en boolean:

```
Invalid ADR frontmatter in ARCH-001-example.md:
  - rules: Expected boolean, received string
```

ADR-er som feiler validering, hoppes over av `archgate check` og rapporteres som feil.
