Motivation#
The earlier posts introduced NixOS and the structure of a configuration repository. With these in place, an AI assistant can help edit and maintain the configuration. Besides Nix syntax, it needs to understand the repository layout. For example, placing a laptop-specific hardware setting in a common module imported by every host may affect other computers. This does not necessarily produce a syntax error.
To reduce repeated explanations during maintenance, I put the repository layout, common commands and precautions in a maintenance document for the assistant to read before editing. In practice, these instructions live in repository conventions, operational documents and update records. They can also be packaged as a skill supported by an AI tool. This post describes useful contents, using simplified examples you can adapt to your own repository.
Purpose of Maintenance Instructions#
The document should first describe where settings apply. For example, a laptop and a server have separate host configurations, and hardware settings for one computer belong in its host file. Syntax checks cannot replace understanding what a setting is for, so the assistant needs these conventions before editing.
Other problems have little to do with the code itself. Existing uncommitted work needs to be preserved. A failed build should not be recorded as a successful update. The assistant also needs to know where the configuration lives and which host output to select.
Adding these requirements to each conversation makes them easy to miss. Keeping them in a file lets a new conversation read them again. Update the relevant instructions when the repository layout or procedures change.
Task Description#
The maintenance document does not replace the actual request. For example, to add hardware support to a laptop, a request could be:
Check the hardware support needed by the laptop and keep the settings in its own configuration. Inspect existing changes before editing, then build the result. Tell me whether a reboot is needed and how to check the device afterward. Do not activate it yet.
This identifies the computer, the intended result and how far to proceed. If the assistant should also activate the configuration, say so. If the computer is busy, prepare the change first and apply it at a suitable time.
I do not think every conversation needs a long prompt. Put the recurring instructions in the maintenance document and explain what is different about the current task.
Contents of the Maintenance Document#
Repository structure#
Start with the common configuration, host files and generated hardware descriptions. Using the previous post’s example, the instructions could say:
- Put common tools and shared settings in
modules/common.nix; - Put settings for one computer in
hosts/<host>/configuration.nix; - Generate hardware descriptions on the corresponding computer rather than copying another machine’s disk configuration;
- Rebuild using the appropriate flake output for the current computer;
- Review
flake.lockupdates separately rather than updating every input to make an error disappear.
The assistant then knows where to start looking before editing. Update these instructions when the directory structure changes.
Before editing#
Check for existing Git changes:
| |
Then read the relevant configuration and recent update notes. When the running state matters, inspect:
| |
These paths can differ after an activation that has not been followed by a reboot. The latest commit in the repository alone does not establish that the computer is using it.
Configuration checks and builds#
Start with the diff and flake:
| |
The first command catches some whitespace and patch-format problems. The second checks evaluation without building the declared checks. When a common module changes, evaluate the affected host outputs, not only the current computer.
Then build the system that will be updated, for example:
| |
A build can still fail after evaluation because of downloads, compilation or disk space. The assistant should therefore describe the check and build results separately. A long build can be monitored; if it remains unfinished, record that so the next session can continue from there.
The options for nix flake check are explained in the official reference. Post 5 goes through evaluation, building and activation in detail.
Applying and verifying the configuration#
When the task only prepares the configuration, the assistant can provide the command to apply it:
| |
It should also explain whether a reboot is needed, which service to check and how to try the new feature. During the early migration, I performed some of the operations requiring sudo or a reboot at the computer myself.
If the assistant applies the change, the result still needs checking. For a service, inspect its systemd status and logs and try connecting. For a kernel change, arrange a reboot. When changing networking remotely, consider how to recover if the connection drops.
After switch, inspect the retained generations before deciding whether sudo nixos-rebuild switch --rollback is the right recovery action. Recovery from a temporary test is different, as post 5 explains. Changes to databases or files may also need separate data recovery.
Documentation and Update Notes#
After a configuration change, I want the relevant instructions updated as well. If a command changes, a file moves or a service needs another initialization step, write down the new procedure. Otherwise the old instructions will lead to the same problem next time.
Update notes can be short, but they should describe what happened. A successful build, an activation and a reboot are different results. A documentation edit does not need an invented system generation; steps that have not been performed can simply be marked as pending.
Before committing, review the complete diff and stage only the intended files. Push according to the current task. Passwords, keys and raw private logs should stay out of commits and chat.
Maintenance instructions reduce repeated explanations and help me continue the work later. They do not guarantee that the assistant will follow them correctly, so the configuration and its actual behavior still need checking. When a new problem appears, add its scope and the procedure for handling it.
