Skip to content
Darkone NixOS Framework

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

Section titled “Rules”
  • One to three lines, at the top of the file, before the code.
  • Describe the role of the file, not its line-by-line implementation.
  • Flag any constraint: generated file, do not edit, dependencies.
  • Concise style; do not repeat the file name.

Example

Section titled “Example”
# Service module: Caddy reverse-proxy for zone services.
# Options under `darkone.service.caddy`. See dnf/AGENTS.md for conventions.
{ config, lib, ... }: