Code header writing rules

Every code file carries a short header explaining its role. It helps humans and AI agents alike find their way without reading the whole file.

Rules

1st line: concise description of the file’s role.
Describe the role, not the line-by-line implementation; explain the why.
Target usage: using, maintaining, configuring, debugging.
Flag any constraints: generated file, do not edit, dependencies.
English, concise; never restate what the code already expresses.

Admonitions in the header (Nix)

The header of a Nix module may contain Starlight admonitions (note, tip, caution, danger): they feed the module reference generated by just codegen.

# Service module: Caddy reverse-proxy for zone services.
#
# :::tip[Activation]
# Enabled by default by host profiles exposing services.
# :::
{ config, lib, ... }:

Generated file

A file produced by a tool states it in the header, so it is not edited:

# This file is generated by 'just generate' or 'just clean'
# from the configuration file etc/config.yaml
# --> DO NOT EDIT <--