--- 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 ` 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 /// 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.